- Table of Contents
- Mail Class and Campaign Related Headers
Click and Open Tracking and
- 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
Determines the Mail Class of this email.
- An example implementation is in the PHPMailer SimpleMH Example page.
- 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
This header is ignored if the email is injected by an authenticated user who is configured using engine_user_force_mail_class or its equivalency in the UI/API.
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.
- Must start with a number.
- Letters and numbers up to a total length of
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
0901220005which 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
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.
Specifies which ListID to associate a message with. This value, if specified takes precedence over the Mail Class’s ListID.
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 (
- Underscores (
- Plus signs (
Specifies which VirtualMTA to associate a message with. This value, if specified takes precedence over the Mail Class’s VirtualMTA.
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.
X-GreenArrow-BounceMailboxOverride: [email protected]
This header instructs SimpleMH to avoid logging the recipient’s actual email address.
See Obscured Email Addresses documentation for more information.
X-GreenArrow-Obscured-Email: userid-1 X-GreenArrow-Obscured-Email: [email protected]
In order to use bounce, unsubscribe, and spam complaints reports,
emails sent via SimpleMH using
X-GreenArrow-Obscured-Email should include
A primary key identifier from your database can be good to use for this.
We recommend against using the Archive a Sample of
Messages feature of mail
classes when using
X-GreenArrow-Obscured-Email, as the recipient’s email address
would be written as part of the message archive.
Click and Open Tracking and
Specifies the URL domain to use for click and open tracking.
This value must begin with
https:// – otherwise it is ignored.
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.
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
- A string composed of ASCII characters between
126. In other words, any ASCII characters that are not a control character or tab.
The Click-Tracking-ID can be up to 300 characters long, but we recommend keeping it as short as possible to reduce overhead.
SimpleMH adds a List-Unsubscribe header to any messages injected into it without that header already present.
List-Unsubscribe header includes an
mailto address. If you wish to customize only the
https address in the header, you can use the
- 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.
If you include the
X-GreenArrow-List-Unsubscribe-HTTP-URL header in your message, you can also specify
X-GreenArrow-List-Unsubscribe-HTTP-URL-Post. This additional header will set the value of
List-Unsubscribe-Post in the final message.
A common value for this header is:
List-Unsubscribe-Post header is a mechanism to make unsubscribing easier
in some email clients. Making unsubscribing easier for subscribers is a good
way to increase the quality of your mailing list. For more information on
List-Unsubscribe-Post, see RFC8058: Signaling One-Click Functionality for
List Email Headers.
SimpleMH supports multiple formats for its click and open tracking URLs.
Option A (using the path):
Option B (this is the default, raw query string):
Option C (query string param):
Selecting which click and open tracker format to use can be done two ways.
Per-email, specify the
echo b > /var/hvmail/control/opt.simplemh.tracker_format
GreenArrow Monitor Headers
GreenArrow Monitor uses the
From address to decide what email messages to group together as one “campaign”. If you plan to re-use the same
From address for multiple campaigns, or use different
From addresses in the same campaign, then you should do one of the following:
- Manually specify a unique identifier for each campaign. The
X-CampaignIDheader is documented in GreenArrow Monitor’s Identifying Campaigns page.
- Turn on the Automatically Seed Mailings option for the desired Mail Class.
If mail is injected with the
X-CampaignID header set, and it belongs to a Mail Class that has the
Automatically Seed Mailings feature turned on, then the
X-CampaignID header is ignored, and
Automatically Seed Mailings takes precedence.
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.
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.
- Decimal number between