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.
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.
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
The valid values for the Instance ID depends on the Statistic Report Grouping configured for the message’s mail class.
If the mail class uses Per InstanceID (Legacy)
/ per_instanceid_legacy
, valid values:
- Must start with a number.
- Consist of letters and numbers up to a total length of
27
characters.
Otherwise (for all other types of Statistic Report Grouping), valid values:
- May contain any printable lower-ASCII character
\x20
-\x7E
. - May be up to 300 characters in length.
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.
See the Statistic Report Grouping documentation for more information on how the instance id can be factored into a message’s SendID.
SendIDs are used case-insensitively within GreenArrow. This means that two InstanceIDs that are only different by casing will be incorporated into the same SendID.
InstanceID case is preserved from what is originally specified in the X-GreenArrow-InstanceID
with regards
to the instanceid
field included in event delivery.
Please see the Bounce Processor Concepts documentation for caveats regarding long InstanceID values.
X-Job
This header is only parsed if the process_x_job_header directive is enabled.
This header is treated as an equivalent to X-GreenArrow-InstanceID
. If both headers are provided,
then X-Job
will be used in favor of X-GreenArrow-InstanceID
.
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 (
+
)
Please see the Bounce Processor Concepts documentation for caveats regarding long ListID values.
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
The VirtualMTA that any given message will use is determined according to the following priority:
- The VirtualMTA set by Custom Code During Delivery Attempts.
- A matching header_pattern directive with
set_virtualmta=
,set_virtualmta_precedence=higher
, andevaluate_on_retry=yes
on message retries. - A matching header_pattern directive with
set_virtualmta=
andset_virtualmta_precedence=higher
on first delivery attempt. - The
X-Virtual-MTA
header (if process_x_virtual_mta_header is enabled). - The
X-GreenArrow-MtaID
header. - A matching header_pattern directive with
set_virtualmta=
andevaluate_on_retry=yes
on message retries. - A matching header_pattern directive with
set_virtualmta=
on first delivery attempt. - The VirtualMTA set by the SMTP service into which the message was injected (this is the
GREENARROW_MTAID
that can be specified when setting default values on an SMTP service). - The
GREENARROW_MTAID
environment variable when the message is injected on the command-line. - The Mail Class VirtualMTA.
- The default VirtualMTA.
X-Virtual-MTA
This header is only parsed if the process_x_virtual_mta_header directive is enabled.
This header is treated as an equivalent to X-GreenArrow-MtaID
. If both headers are provided,
then X-Virtual-MTA
will be used in favor of X-GreenArrow-MtaID
.
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]
X-GreenArrow-Obscured-Email
This header instructs SimpleMH to avoid logging the recipient’s actual email address.
See Obscured Email Addresses documentation for more information.
-
Example:
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
X-GreenArrow-Click-Tracking-ID.
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.
X-GreenArrow-HandleBounceAndFbl
This header instructs GreenArrow to do Bounce & FBL Handling on this message.
This header overrides the Handle Bounce & FBL
(handle_bounce_and_fbl) option on the Mail Class.
Example:
X-GreenArrow-HandleBounceAndFbl: no
Valid values:
yes
no
1
0
If you are a GreenArrow cloud customer this header may be ignored.
Click and Open Tracking and List-Unsubscribe
Headers
X-GreenArrow-URL-Domain
Specifies the URL domain to use for click and open tracking.
This value must begin with http://
or https://
– otherwise it is ignored.
Example:
X-GreenArrow-URL-Domain: https://example.com
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 300 characters long, but we recommend keeping it as short as possible to reduce overhead.
X-GreenArrow-List-Unsubscribe-HTTP-URL
SimpleMH adds a List-Unsubscribe header to any messages injected into it without that header already present.
The SimpleMH List-Unsubscribe
header includes an https
and mailto
address. If you wish to customize only the https
address in the header, you can use the X-GreenArrow-List-Unsubscribe-HTTP-URL
header.
Example:
X-GreenArrow-List-Unsubscribe-HTTP-URL: https://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.
X-GreenArrow-List-Unsubscribe-HTTP-URL-Post
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:
X-GreenArrow-List-Unsubscribe-HTTP-URL-Post: List-Unsubscribe=One-Click
The 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.
X-GreenArrow-Disable-Auto-List-Unsubscribe-Header
Let SimpleMH know that you do not want it to automatically add a List-Unsubscribe header.
Example:
X-GreenArrow-Disable-Auto-List-Unsubscribe-Header: yes
Valid values:
yes
no
1
0
X-GreenArrow-Tracker-Format
SimpleMH supports multiple formats for its click and open tracking URLs.
Option A (using the path):
https://clicktracker.example.com/click/encodedclickdata
Option B (this is the default, raw query string):
https://clicktracker.example.com/click?encodedclickdata
Option C (query string param):
https://clicktracker.example.com/click?qs=encodedclickdata
Selecting which click and open tracker format to use can be done two ways.
-
Per-email, specify the
X-GreenArrow-Tracker-Format
header:X-GreenArrow-Tracker-Format: b
-
Globally, set
a
,b
, orc
in/var/hvmail/control/opt.simplemh.tracker_format
:echo b > /var/hvmail/control/opt.simplemh.tracker_format
X-GreenArrow-EventTrackingMetadataStorage
Specify the Event Tracking Metadata Storage for this message.
This header overrides the Event Tracking Metadata Storage
setting that would otherwise be used (for this message only).
Available options:
system_default | |
local | |
stateless | |
external |
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 do one of the following:
- Manually specify a unique identifier for each campaign. The
X-CampaignID
header 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.
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
DKIM Headers
See the X-GreenArrow-DKIM header documentation.
X-GreenArrow-Pcompat-DKIM-Disable
Use this header to disable DKIM signing that would otherwise be performed by pcompat_dkim_key and its associated directives.
Example:
X-GreenArrow-Pcompat-DKIM-Disable: yes
Valid values:
yes
no
1
0