GreenArrow Email Software Documentation

Mail Classes API

Overview

GreenArrow Engine’s SimpleMH system classifies mail into Mail Classes. Each message that’s processed by SimpleMH is assigned a Mail Class, which is used to determine which SimpleMH Mail Features to use.

Non-Configurable Attributes

The following Mail Class attributes are not configurable via this API but are configurable with GreenArrow Engine’s web interface.

  • Regex Before HTML Conversion
  • Regex After HTML Conversion
  • Regex for HTML Part
  • Regex for Text Part

All other Mail Class attributes are configurable via this API.

Configurable Attributes

The following are the configurable attributes defined for Mail Classes.

mail_class

hash

/

required


id

integer

/

read-only

A unique automatically generated identifier.

name

string

/

required

A descriptive name for this Mail Class.

  • Must be unique (case-insensitive)
  • Must be 2-64 characters long
  • May consist only of ASCII letters and underscores (a-z, A-Z and _)
  • May not contain two underscores next to each other

Please see the Bounce Processor Concepts documentation for caveats regarding long mail class names.

listid

string

/

required

The ListID to assign mail in this Mail Class to.

  • Must be 1-20 characters long
  • May not be the single letter a
  • May not begin with the letter a followed by a digit (0-9)
  • May consist only of ASCII letters and numbers (a-z, A-Z and 0-9), underscores (_), and plus signs (+)
seed

hash

/

default: null



Controls whether GreenArrow sends sample messages from each campaign to a seed list. This value may be overwritten on a per-message basis by using the X-GreenArrow-SeedDo header and the X-GreenArrow-SeedProgress header.

Setting to null will clear these values, disabling seeding.

start

integer

The number of messages to send before sending a sample to the first seed account.

  • Must be an integer greater than or equal to 0.
  • Must be less than seed.end.
end

integer

The message count that the last seed should be sent to by. If the campaign includes less messages than this value, and the X-GreenArrow-SeedProgress header header is not used, then the entire seed list will not be sent to.

  • Must be an integer greater than 0.
  • Must be greater than seed.start.
track_clicks_and_opens

boolean

/

default: false

Controls whether click and open tracking are turned on. This value may be overwritten on a per-message basis by using the X-GreenArrow-Click-Tracking-Do header.

manage_unsubscribe_links

boolean

/

default: false

Controls whether the SimpleMH unsubscribe link management feature is enabled.

archive_sample_count

integer

/

default: null

Controls the amount of sample messages GreenArrow should archive for each campaign.

IMPORTANT NOTE: Currently the email messages that are archived are not visable in the application. This feature may be removed or changed in future versions.

Setting to null will clear this value, disabling message archival.

  • Must be an integer greater than or equal to 0.
convert_textonly_to_html

hash



The options in this hash are used to convert text-only emails to HTML.

do_conversion

boolean

/

default: false

If true, all text-only email messages are converted to HTML emails and the below conversion details (header, footer, and link_text) are obeyed.

IMPORTANT NOTE: If do_conversion is set to false, then as a side-effect all of the other fields in this hash are cleared. (This behavior may be changed in a future version.)

header

string

The HTML header to insert when converting the text-only message to HTML.

footer

string

The HTML footer to insert when converting the text-only message to HTML.

link_text

string

Anchor text to use when converting links found in the text-only email to HTML.

modify_html

hash

/

default: null



The options in this hash are used modify HTML-only and the HTML portions of multipart/alternative messages.

Setting to null will clear these values, disabling HTML modification.

html_header

string

HTML to insert at the top of the HTML. This is inserted right after the opening of the <body> tag, or at the top of the document if no <body> tag is found. (This has nothing to do with the HTML <head> tag or email headers.)

html_footer

string

HTML to insert at the bottom of the HTML. This is inserted right after the closing of the </body> tag, or at the bottom of the document if no </body> tag is found.

text_header

string

The header to insert into the text portion of each message.

text_footer

string

The footer to insert into the text portion of each message.

bounce_message_passthrough

boolean

/

default: false

When enabled, GreenArrow sends a copy of each bounce message back to the original Return-Path recipient. GreenArrow will still process bounces locally when using this feature.

bcc

string

/

default: null

An email address to BCC for all emails sent in this Mail Class.

add_email_headers

string

/

default: null

Custom email headers to add to each email.

This should be lines that represent properly formatted headers as defined by RFC5322 (except use the LF character for newline termination).

For example:

X-foo: bar
X-baz: header folding
 is supported

Setting to null will clear this value and no extra email headers will be written.

  • All X-GreenArrow-* headers are prohibited except for X-GreenArrow-DKIM, X-Greenarrow-DKIM-Only-Using-Domain, X-GreenArrow-Signing-Selector, and X-GreenArrow-Signing-Key-Filename.
  • The X-Mailer-Info header is prohibited.
  • Max length of 1024
  • If omitted, a trailing newline will be added
  • Lines are terminated with LF characters. CR or CR-LF will be converted into LF characters.
virtual_mta

hash

/

required



You may select which VirtualMTA to use by specifying either its id or name. If both values are specified, the id will be used, and the name ignored. To use the system default VirtualMTA, assign an id of 0.

id

integer

A unique automatically generated identifier.

name

string

The name of this VirtualMTA.

url_domain

hash



You may select which URL domain to use by specifying either its id or name. If both values are specified, the id will be used, and the name ignored.

Setting to null will clear this value, and cause SimpleMH to select the default URL domain.

id

integer

A unique automatically generated identifier.

domain

string

The fully qualified domain name to use as a URL domain. Should not include an http:// or https:// prefix.

bounce_address

hash



Keys in this hash will overwrite each other, and both cannot be set at once.

use_system_default

boolean

/

default: true

Setting to true will clear the address value, and cause SimpleMH to select the default bounce address.

address

string

Email address to deliver bounces to.

  • Must be a valid email address
add_message_id_if_missing

boolean, default: false

If messages injected using this Mail Class do not have a Message-ID header, one will be added automatically.

disable_auto_list_unsubscribe_header

boolean, default: false

Messages sent by SimpleMH ordinarily automatically add a List-Unsubscribe header. If this setting is enabled, that header will no longer be automatically added.

Get a List of Mail Classes

GET /ga/api/v3/eng/mail_classes

Parameters

The following parameters are valid for the above endpoint.

page

integer

/

optional

The page number from which to retrieve. Page numbering starts at 0.

page_token

string

/

optional

The page_token to retrieve the next page based on the prior query results.

name

string

/

optional

Filter the results to just a single Mail Class with this name (case-insensitive).

Examples:

GET /ga/api/v3/eng/mail_classes?page={page}
GET /ga/api/v3/eng/mail_classes?page_token={page_token}
GET /ga/api/v3/eng/mail_classes?name={name}

Response

The response will contain a list of Mail Classes in the following format.

mail_classes

array of hashes


id

integer

An automatically generated identifier.

name

string

A descriptive name for this Mail Class.

pagination

hash


page

integer

The page number of this result set. Page numbers start at 0.

per_page

integer

The number of records returned on each page.

num_pages

integer

The total number of pages in the result set.

num_records

integer

The total number of records that are in the result set.

next_page_token

string

A unique identifier that can be used to retrieve the next result set.

null is returned if this is the last page.

Example 1: Get the First Page of Mail Classes

GET /ga/api/v3/eng/mail_classes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_classes": [
      {
        "id": 1,
        "name": "my_mail_class_one"
      },
      {
        "id": 2,
        "name": "my_mail_classtwo"
      },
      {
        "id": 3,
        "name": "my_mail_class_three"
      },
      {
        "id": 4,
        "name": "my_mail_class_four"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 4,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Find a Mail Class by Name

GET /ga/api/v3/eng/mail_classes?name=my_mail_classtwo

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_classes": [
      {
        "id": 2,
        "name": "my_mail_classtwo"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 1,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Single Mail Class

GET /ga/api/v3/eng/mail_classes/{id}

Response

The response will contain details on the requested record:

mail_class

hash

The attributes for this hash are defined in the Attributes section of this document.

Example

GET /ga/api/v3/eng/mail_classes/1

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_class": {
      "id": 1,
      "name": "my_mail_class_one",
      "listid": "mc_listid_13",
      "seed": {
        "start": 1,
        "end": 3
      },
      "track_clicks_and_opens": false,
      "manage_unsubscribe_links": false,
      "archive_sample_count": null,
      "convert_textonly_to_html": {
        "do_conversion": false,
        "header": null,
        "footer": null,
        "link_text": null
      },
      "modify_html": null,
      "bounce_message_passthrough": false,
      "bounce_address": {
        "address": null,
        "use_system_default": true
      },
      "bcc": null,
      "add_email_headers": null,
      "virtual_mta": {
        "id": 0,
        "name": "System Default Route"
      },
      "url_domain": null,
      "add_message_id_if_missing": false,
      "disable_auto_list_unsubscribe_header": false
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Mail Class

POST /ga/api/v3/eng/mail_classes

Payload

mail_class

hash

/

required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a mail_class key containing the full Mail Class record as defined in the Mail Class Attributes.

Example

POST /ga/api/v3/eng/mail_classes

{
  "mail_class": {
    "name": "a_new_mail_class",
    "listid": "12345",
    "virtual_mta": {
      "id": 0
    },
    "manage_unsubscribe_links": true,
    "add_message_id_if_missing": true,
    "bounce_message_passthrough": true,
    "disable_auto_list_unsubscribe_header": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_class": {
      "id": 5,
      "name": "a_new_mail_class",
      "listid": "12345",
      "seed": null,
      "track_clicks_and_opens": false,
      "manage_unsubscribe_links": true,
      "archive_sample_count": null,
      "convert_textonly_to_html": {
        "do_conversion": false,
        "header": null,
        "footer": null,
        "link_text": null
      },
      "modify_html": null,
      "bounce_message_passthrough": true,
      "bounce_address": {
        "address": null,
        "use_system_default": true
      },
      "bcc": null,
      "add_email_headers": null,
      "virtual_mta": {
        "id": 0,
        "name": "System Default Route"
      },
      "url_domain": null,
      "add_message_id_if_missing": true,
      "disable_auto_list_unsubscribe_header": true
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Mail Class

PUT /ga/api/v3/eng/mail_classes/{id}

Payload

mail_class

hash

/

required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a mail_class key containing the full Mail Class record as defined in the Mail Class Attributes.

Example

PUT /ga/api/v3/eng/mail_classes/2

{
  "mail_class": {
    "name": "updated_name_three",
    "seed": {
      "start": 10,
      "end": 20
    },
    "bcc": "[email protected]",
    "convert_textonly_to_html": {
      "do_conversion": true,
      "header": "html header",
      "footer": "html footer",
      "link_text": "html link text"
    },
    "modify_html": {
      "html_header": "modified html header",
      "html_footer": "modified html footer",
      "text_header": "text header",
      "text_footer": "text footer"
    },
    "add_email_headers": "X-Test: Header",
    "add_message_id_if_missing": true,
    "disable_auto_list_unsubscribe_header": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_class": {
      "id": 2,
      "name": "updated_name_three",
      "listid": "mc_listid_78",
      "seed": {
        "start": 10,
        "end": 20
      },
      "track_clicks_and_opens": false,
      "manage_unsubscribe_links": false,
      "archive_sample_count": null,
      "convert_textonly_to_html": {
        "do_conversion": true,
        "header": "html header",
        "footer": "html footer",
        "link_text": "html link text"
      },
      "modify_html": {
        "html_header": "modified html header",
        "html_footer": "modified html footer",
        "text_header": "text header",
        "text_footer": "text footer"
      },
      "bounce_message_passthrough": false,
      "bounce_address": {
        "address": null,
        "use_system_default": true
      },
      "bcc": "[email protected]",
      "add_email_headers": "X-Test: Header\n",
      "virtual_mta": {
        "id": 0,
        "name": "System Default Route"
      },
      "url_domain": null,
      "add_message_id_if_missing": true,
      "disable_auto_list_unsubscribe_header": true
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Mail Class

DELETE /ga/api/v3/eng/mail_classes/{id}

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/mail_classes/2

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}


Copyright © 2012–2024 GreenArrow Email