Raw Injection Headers

• Table of Contents
• VirtualMTA, List and Send Headers
  • X-GreenArrow-MtaID
  • X-GreenArrow-SendID
  • X-GreenArrow-ListID
• Bounce and Spam Complaint Processing
  • Return-Path / Bounce Address
  • X-Mailer-Info
• GreenArrow Monitor Headers
  • X-CampaignID
• DKIM and DomainKeys Headers
  • X-GreenArrow-DKIM-Only-Using-Domain
  • X-GreenArrow-Signing-Selector
  • X-GreenArrow-Signing-Key-Filename
  • X-GreenArrow-DomainKeys-Enable
• Caveats

This document describes the headers used for Raw Injections. The X-GreenArrow-* headers will be stripped from the message by GreenArrow Engine. Remaining headers will be left intact.

VirtualMTA, List and Send Headers

X-GreenArrow-MtaID

Specifies which VirtualMTA is used to send a message. Valid values are:

• A name listed under one of the Name columns in GreenArrow Engine’s VirtualMTAs page. For example:

  X-GreenArrow-MtaID: smtp1-1
  

• The numeric ID that forms the last part of the URL that a VirtualMTA’s View button links to. For example:

  X-GreenArrow-MtaID: 2
  

If no VirtualMTA is specified, or if the VirtualMTA that is specified doesn’t exist, then the message will be sent through the default VirtualMTA of the server.

X-GreenArrow-SendID

Specifies which SendID to associate a message with.

• Example:

  X-GreenArrow-SendID: 20111229
  

X-GreenArrow-ListID

Specifies which ListID to associate a message with.

• Example:

  X-GreenArrow-ListID: t100
  

The ListID can be up to 20 characters long, but we recommend keeping it as short as possible in order to reduce overhead.

The ListID may contain the follow characters:

• ASCII alphanumeric characters (a-z, A-Z and 0-9)
• Underscores (_)
• Plus signs (+)

Bounce and Spam Complaint Processing

Return-Path / Bounce Address

You must properly set the Return-Path on outgoing messages for the Bounce Processor to work. The Return-Path encodes the recipient address, ListID, and the SendID of the message.

The Return-Path should be in the following form when injecting through SMTP:

LocalPartOfBounceMailbox-Listid-SendID-RecipientAddressInVERPFormat@DomainOfBounceMailbox

The Return-Path should be in the following form when injecting through /var/hvmail/bin/sendmail or /var/hvmail/bin/qmail-inject:

LocalPartOfBounceMailbox-Listid-SendID-@DomainOfBounceMailbox-@[]

Definitions:

For example, with the data:

The Return-Path when injecting through SMTP would be:

[email protected]

The Return-Path when injecting through /var/hvmail/bin/sendmail or /var/hvmail/bin/qmail-inject would be:

[email protected]@[]

Example Implementation:

• An example PHP implementation can be found in the PHPMailer Raw Injection Example page.

X-Mailer-Info

You must properly set the X-Mailer-Info header on outgoing messages for the Spam Complaint Processor to work. The X-Mailer-Info header encodes the recipient address, ListID, and the SendID of the message.

Example Implementations:

• An example PHP implementation can be found in the PHPMailer Raw Injection Example page.
• An example Perl subroutine is shown below:

use MIME::Base64;

sub create_feedback_header
{
    my $listid = shift;
    my $sendid = shift;
    my $recipient = shift;

    my $data_to_encode = lc($listid . "," . $recipient . "," . $sendid);
    # plan: reverse, rot13, base64, change alphabet, rot13
    my $encoded = reverse($data_to_encode);
    $encoded =~ tr/a-zA-Z/n-za-mN-ZA-M/;
    $encoded = MIME::Base64::encode_base64($encoded, "");
    $encoded =~ tr/+\//-_/;
    $encoded =~ s/[\n=]//g;
    $encoded =~ tr/a-zA-Z/n-za-mN-ZA-M/;

    return "X-Mailer-Info: $encoded";
}

GreenArrow Monitor Headers

X-CampaignID

GreenArrow Monitor uses the Subject and From address to determine what email messages will be grouped together as one “campaign” in the system. If you plan to re-use the same Subject and From address for multiple campaigns, or use different Subject lines 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.

DKIM and DomainKeys Headers

X-GreenArrow-DKIM-Only-Using-Domain

Causes the message to be signed with a domain other than the one used in the From or Sender header. The message will be signed only with DKIM and not with DomainKeys. DKIM has the ability to sign for an arbitrary domain name, but DomainKeys does not.

• Example:

  X-GreenArrow-DKIM-Only-Using-Domain: example.com
  

X-GreenArrow-Signing-Selector

Specifies the selector for use in signing, instead of the standard of default. In example below, greenarrow is used. This applies to both DomainKeys and DKIM signing.

• Example:

  X-GreenArrow-Signing-Selector: greenarrow
  

X-GreenArrow-Signing-Key-Filename

Specifies the filename of the private key, relative to the /var/hvmail/control/domainkeys/ directory. You would normally specify the domain name (in lowercase), then a slash, then the selector to retrieve a private key for a domain/selector pair. Directory back-references (/../) are not allowed. If you’re using a selector other than default, then be sure to include the X-GreenArrow-Signing-Selector header as well.

• Example:

  X-GreenArrow-Signing-Key-Filename: example.com/greenarrow
  

X-GreenArrow-DomainKeys-Enable

Enables DomainKeys signing, which is turned off by default. This is in addition to the DKIM signing which is turned on by default.

We recommend against doing this since DKIM is better and DomainKeys is deprecated.

• Example:

  X-GreenArrow-DomainKeys-Enable: 1
  

Caveats

Header folding is not supported for Raw Injection’s X-GreenArrow-* headers.