GreenArrow Email Software Documentation

SimpleMH 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.

X-GreenArrow-MailClass

Determines the Mail Class of this email.

Examples:

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

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.

Please see the Bounce Processor Concepts documentation for caveats regarding long InstanceID values.

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 and 0-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

Please see the Bounce Processor Concepts documentation for caveats regarding long ListID values.

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.

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.

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 and 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.

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.

  1. Per-email, specify the X-GreenArrow-Tracker-Format header:

    X-GreenArrow-Tracker-Format: b

  2. Globally, set a, b, or c in /var/hvmail/control/opt.simplemh.tracker_format:

    echo b > /var/hvmail/control/opt.simplemh.tracker_format

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:

  1. Manually specify a unique identifier for each campaign. The X-CampaignID header is documented in GreenArrow Monitor’s Identifying Campaigns page.
  2. 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 and 100

DKIM Headers

See the X-GreenArrow-DKIM header documentation.

 Mail Classes
Set Mail Class with SMTP AUTH 

Copyright © 2012–2023 GreenArrow Email