SimpleMH Headers
- Table of Contents
- Mail Class and Campaign Related Headers
-
Click and Open Tracking and
List-Unsubscribe
Headers - GreenArrow Monitor Headers
- DKIM Headers
This document describes the headers used for GreenArrow Engine SimpleMH Injections. The X-GreenArrow-*
headers will be stripped from the message by GreenArrow Engine. Remaining headers will be left intact, unless setting them is a SimpleMH feature. For example, SimpleMH sets the X-Mailer-Info
header, and Return-Path
for you.
Mail Class and Campaign Related Headers
X-GreenArrow-MailClass
Determines the Mail Class of this email.
Examples:
X-GreenArrow-MailClass: newsletter
- An example implementation is in the PHPMailer SimpleMH Example page.
Valid values:
- Letters and underscores.
A Mail Class is usually defined in SimpleMH’s web browser interface. On some installations of GreenArrow Engine, Mail Classes are defined in the /var/hvmail/control/simplemh-config
file.
X-GreenArrow-InstanceID
Determines the instance identifier of this email message. An instance is a set of messages that are all part of the same email “campaign”.
This header is not used to uniquely identify each email. For example, in a campaign sent to 100,000 recipients, all 100,000 emails should have the same Instance ID.
Example:
X-GreenArrow-InstanceID: 0901220005
Valid values:
- Must start with a number.
- Letters and numbers up to a total length of
20
characters.
We recommend making sure that each Instance-ID is used for only one campaign.
Here are some ideas:
-
Use the primary key value for your injecting application’s database entry for the campaign being sent.
-
Use the date as the first part of the Instance-ID, such as
0901220005
which would be the fifth email campaign triggered on January 22, 2009. -
Use a database sequence or auto-increment column to guarantee unique values.
-
Use the Unix time integer (seconds since the epoch) to create the instance id, as long as you can guarantee that you will not start two instances in the same second and that the system clock will not go backwards.
A campaign’s SendID is constructed by concatenating the InstanceID to the Mail Class. For example, if the following headers are present in a message:
X-GreenArrow-MailClass: a
X-GreenArrow-InstanceID: 100525
Then the resulting SendID would be a100525
.
SimpleMH will group messages together with the same SendID (Mail Class + InstanceID combination) for up to 3 weeks, even if the messages are injected on different days. However, after 3 weeks the same SendID will create a new campaign in Engine’s stats. If there is no InstanceID designated, SimpleMH will use a 6-digit date: YYMMDD
as the default ID, and will group all messages together for that Mail Class from that 24-hour period.
X-GreenArrow-ListID
Specifies which ListID to associate a message with. This value, if specified takes precedence over the Mail Class’s ListID.
-
Example:
X-GreenArrow-ListID: t100
The ListID can be up to 20
characters long, but we recommend keeping it as short as possible to reduce overhead.
The ListID may contain the following characters:
- ASCII alphanumeric characters (
a
-z
,A
-Z
and0
-9
) - Underscores (
_
) - Plus signs (
+
)
X-GreenArrow-MtaID
Specifies which VirtualMTA to associate a message with. This value, if specified takes precedence over the Mail Class’s VirtualMTA.
-
Example:
X-GreenArrow-MtaID: transactional
X-GreenArrow-BounceMailboxOverride
This header allows you to specify a bounce mailbox that will override both the $RETURN_PATH_OVERRIDE
variable in /var/hvmail/control/simplemh-config
and the Override default bounce address
Mail Class setting.
-
Example:
X-GreenArrow-BounceMailboxOverride: [email protected]
Click and Open Tracking and List-Unsubscribe
Headers
X-GreenArrow-Click-Tracking-Do
Lets SimpleMH know if you want to do click and open tracking on this email message or not. This overrides the Track clicks and opens
setting for the Mail Class.
Example:
X-GreenArrow-Click-Tracking-Do: yes
Valid values:
yes
no
1
0
X-GreenArrow-Click-Tracking-ID
Adds an extra identifier for events that get recorded by the Event Notification System. If this header is set, its value gets recorded as the click_tracking_id
.
Example:
X-GreenArrow-Click-Tracking-ID: 1234
Valid values:
- A string composed of ASCII characters between
32
and126
. In other words, any ASCII characters that are not a control character or tab.
The Click-Tracking-ID can be up to 100 characters long, but we recommend keeping it as short as possible to reduce overhead.
X-GreenArrow-List-Unsubscribe-HTTP-URL
SimpleMH includes a mailto
version of the List-Unsubscribe
header by default, which is one type of List-Unsubscribe
header. If you wish to also include a URL
List-Unsubscribe
in addition to the mailto
, you can use the X-GreenArrow-List-Unsubscribe-HTTP-URL
header. The URL provided in this header is used in the List-Unsubscribe
header in addition to the automatically generated mailto address.
Example:
X-GreenArrow-List-Unsubscribe-HTTP-URL: http://domain.com/unsubscribe/1-32383893-57-566-60d358adf6afe74-5d11c85933
Valid Values:
- Any valid URL that will result in a subscriber status update equivalent to a spam complaint. Clicking this URL should result in a deactivation of the original subscriber who received the email.
GreenArrow Monitor Headers
X-CampaignID
GreenArrow Monitor uses the Subject
and From
address to decide what email messages to group together as one “campaign”. If you plan to re-use the same Subject
and From
address for multiple campaigns, or use different Subjects
or From
addresses in the same campaign, then you should manually specify a unique identifier for each campaign. The X-CampaignID
header is documented in GreenArrow Monitor’s Identifying Campaigns page.
X-GreenArrow-SeedDo
Lets SimpleMH know if you want to send this instance/campaign to a seed list or not. Every email message in the instance/campaign should have this header for the seeding to work properly. This overrides the Automatically seed mailings
setting in the Mail Class’s configuration.
Example:
X-GreenArrow-SeedDo: yes
Valid values:
yes
no
1
0
X-GreenArrow-SeedProgress
Set the value of this header to the percent of total email messages sent in this instance/campaign. This lets SimpleMH know how far the sending of this instance has progressed, so it knows how to evenly distribute seed messages over the campaign. This overrides the Number of emails to start seeding at
and Number of emails to finish seeding by
settings for the Mail Class.
Example:
X-GreenArrow-SeedProgress: 50.23
Valid values:
- Decimal number between
0
and100