Mail Classes API

Table of Contents
Overview
Non-Configurable Attributes
Configurable Attributes
Get a List of Mail Classes
Get Details on a Single Mail Class
Create a Mail Class
Update a Mail Class
Delete a Mail Class

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 can be overridden on a per-message basis using the X-GreenArrow-Click-Tracking-Do header.

If you are a GreenArrow cloud customer this field might be forced on and hidden from the UI and API.

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.

This can be overridden on a per-message basis using the X-GreenArrow-Disable-Auto-List-Unsubscribe-Header header.

If you are a GreenArrow cloud customer this field might be forced on and hidden from the UI and API.

handle_bounce_and_fbl
boolean, default: true

This option instructs GreenArrow to modify the email message so that the Bounce Processor is able to process bounces and spam complaints for messages using this Mail Class.

If you are using the Lite Bounce Processor, you will typically want this option to be disabled.

When handle_bounce_and_fbl is enabled (or the header X-GreenArrow-HandleBounceAndFbl is enabled), messages sent from this mail class will be affected in the following ways:

The 5321.MailFrom (MAIL FROM / Return-Path) address will be overwritten so that GreenArrow receives and processes bounces resulting from these messages.
An X-Mailer-Info header will be added to these messages to aid in complaint processing and identification.
An X-Mailer-Info-Extra header will possibly be added to aid in bounce processing.
The automatically generated List-Unsubscribe header will include a mailto: option (instead of only the HTTP option). This mailto: option is a variant of GreenArrow’s 5321.MailFrom address indicating the message represents an unsubscribe.

When this setting is disabled, the above behaviors will not be in effect.

This can be overridden on a per-message basis using the X-GreenArrow-HandleBounceAndFbl header.

If you are a GreenArrow cloud customer this field might be forced on and hidden from the UI and API.

event_tracking_metadata_storage
string, default: local

This attribute configures the Event Tracking Metadata Storage for messages processed by this Mail Class.

This can be overridden by the X-GreenArrow-EventTrackingMetadataStorage message header.

Available options:

system_default	Use the default_event_tracking_metadata_storage.
local	Use Local Metadata Event Tracking.
stateless	Use Stateless Metadata Event Tracking.
external	Use External Metadata Event Tracking.

statistic_report_grouping
string, default: per_day

This attribute controls how statistics are grouped for this mail class. A thorough explanation of the options and ramifications are discussed in the Statistic Report Grouping documentation.

The default of this attribute is ordinarily Per Day, but is affected by the legacy_behavior directive default_statistic_report_grouping_per_instanceid_legacy.

Valid options:

per_instanceid_legacy
per_instanceid
per_instanceid_and_day
per_day
per_hour

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_109",
      "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,
      "handle_bounce_and_fbl": true,
      "event_tracking_metadata_storage": null,
      "statistic_report_grouping": "per_day"
    }
  },
  "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,
    "handle_bounce_and_fbl": true,
    "event_tracking_metadata_storage": "stateless"
  }
}

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,
      "handle_bounce_and_fbl": true,
      "event_tracking_metadata_storage": "stateless",
      "statistic_report_grouping": "per_day"
    }
  },
  "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,
    "handle_bounce_and_fbl": false
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mail_class": {
      "id": 2,
      "name": "updated_name_three",
      "listid": "mc_listid_842",
      "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,
      "handle_bounce_and_fbl": false,
      "event_tracking_metadata_storage": null,
      "statistic_report_grouping": "per_day"
    }
  },
  "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
}