Skip to main content

Using the X-MSYS-API Header for Engagement Tracking

Last updated March 2020

The X-MSYS-API header can be used to override the configuration option to enable or disable engagement tracking for a specific message. Also, you can specify engagement tracking data in the header fields. For details about engagement tracking for SMTP injections, see Tracking Engagement for SMTP .

X-MSYS-API Header Attributes

The X-MSYS-API header must be a JSON object serialized as a string that holds the various attributes for the message. Table 41.1, “X-MSYS-API Header Attributes” lists the fields supported in the JSON object.

FieldTypeDescriptionRequiredNotes
campaign_idstringName of the campaign to associate with the SMTP messagenoCampaign ID is available during engagement events. Maximum length - 64 bytes
metadataJSON objectJSON key value pairs associated with the SMTP messagenoMetadata is available during engagement events based on a configuration option. See “engagement_tracker – HTTP Engagement Tracking”. A maximum of 200 bytes is available.
optionsJSON objectJSON object in which engagement tracking options are enabled or disablednoFor a full description, see the Options Attributes.
tagsJSON objectArray of text labels associated with the SMTP messagenoTags are available during engagement events. Maximum number of tags = 10 per recipient, 100 system wide. Any tags over the limits are ignored.

Table 41.2, “Options Attributes” lists the fields supported in the "options" JSON object.

FieldTypeDescriptionRequiredNotes
click_trackingbooleanWhether click tracking is enabled or disabled for the SMTP messagenoIf specified, this field takes precedence over the configuration option. For the order of precedence, see “Enabling Engagement Tracking”.
open_trackingbooleanWhether open tracking is enabled or disabled for the SMTP messagenoIf specified, this field takes precedence over the configuration option. For the order of precedence, see “Enabling Engagement Tracking”.

Note

There are no X-MSYS-API header fallbacks for the following:

Configuration OptionContext Variable
click_tracking_schemesmtpapi_click_tracking_scheme
open_tracking_schemesmtpapi_open_tracking_scheme
tracking_domainsmtpapi_tracking_domain
tracking_link_expirysmtpapi_tracking_link_expiry

You must specify the configuration options or the context variables in Lua policy. This is especially important for tracking_domain, as the default value of "localhost:8080" is not appropriate for production environments. See “Configuration Options for Engagement Tracking” or “Using Policy for Engagement Tracking”, respectively.

X-MSYS-API Header Line Length

SMTP defines a maximum line length of 1000 characters including CRLF. Since the X-MSYS-API header is a JSON-encoded string possibly containing many tags and metadata, it is likely that this limit will be exceeded. If the value of the JSON string is longer than 998 characters, it must be folded across multiple lines before the message is injected, as shown in the following example:

X-MSYS-API: {"options" : {"open_tracking" : false, "click_tracking" : true},
   "metadata" : {"key" : "value"}, "tags" : ["cat", "dog"], "campaign_id" :
   "my_campaign"}

When the header is unfolded on the receiving system, as per rfc2822, a single space will be added between each line of the header.

For example,

X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes
   ome_campaign" }

will be unfolded with a space in the "my_awes ome_campaign" string:

X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes ome_campaign" }

Ideally, header values should be folded on whitespace. To ensure whitespace is present in a JSON-encoded string in Perl, use the JSON module's space_before and space_after modifiers, as shown in the following example:

my $api_hash = {
  options => {
    open_tracking => JSON::false
  },
  campaign_id => "my_awesome_campaign"
};

my $js = JSON->new();
$js->space_before(1);
$js->space_after(1);

my $x_msys_api_string = $js->encode($api_hash);

non-ASCII Characters in the X-MSYS-API Header

If non-ASCII characters are present in the "campaign_id", "tags", or "metadata" fields, they must be escaped or rfc2047-encoded.

For example,

my $js = JSON->new();
$js->ascii(1);

will cause $js->encode to escape non-ASCII characters resulting in a JSON-encoded string such as:

X-MSYS-API: {"options" : {"open_tracking" : false, "click_tracking" : true},
   "metadata" : {"my_utf8" : "\u00e7\u00a7\u0081\u00e3\u0081\u00af\u00e3\u0082\u00ac" },
   "tags" : ["cat", "dog"], "campaign_id" : "my_campaign"}

Invalid JSON Values in the X-MSYS-API Header

If the X-MSYS-API header includes invalid JSON values, the SMTP message will be rejected with one of the following codes:

CodeExamples
550

5.6.0 X-MSYS-API 'metadata' must be of type 'json object'

5.6.0 smtpapi_campaign_id context is limited to 64 bytes

| | 421 |

4.3.3 [internal] smtpapi unable to generate unique transmission id

|

Was this page helpful?