Knowledge Base/SMTP Integration/SMTP Headers API

Using SMTP Headers to customize your messages

posted this on July 06, 2012 03:27 PM

If you're integrating via SMTP, you can use SMTP headers to customize your messages, add tracking, or specify options for Mandrill to apply to your messages. Specify a custom Reply-To header or any of the Mandrill-specific X-MC-* headers for more control over your SMTP messages.

Custom header reference

Header Purpose Format of header content
X-MC-Track Enable open or click-tracking for the message. Comma-separated list of strings, maximum of two strings (one for opens, one for clicks)
opens: enables open tracking
clicks_all: enables click tracking on all emails
clicks: same as clicks_all
clicks_htmlonly: enables click tracking only on html emails
clicks_textonly: enables click tracking only on text emails
X-MC-Autotext Automatically generate a plain-text version of the email from the HTML content. "true", "on", "yes", "y" or 1 to turn on automatic text generation
"false", "off", "no", "n" or 0 to turn off automatic text generation
X-MC-AutoHtml Automatically generate an HTML version of the email from the plain-text content. "true", "on", "yes", "y" or 1 to turn on automatic HTML generation
"false", "off", "no", "n" or 0 to turn off automatic HTML generation
X-MC-Template Use an HTML template stored in your Mandrill account template_name|block_name

template_name is the name of the stored template.
block_name is the name of the mc:edit region where the body of the SMTP generated message will be placed. Optional and defaults to "main".
X-MC-MergeVars Add dynamic data to replace mergetags that appear in your message content. A JSON-formatted object with name/value pairs for the variable name and value, separated by commas.

Multiple instances of this header may be added.

Recipient-specific values: add the _rcpt name with the recipient email address as the value, followed by other variable names and their values for that recipient.
X-MC-GoogleAnalytics Add Google Analytics tracking to links in your email for the specified domains. A comma-separated list of the domains for Google Analytics data to be added to.
X-MC-GoogleAnalyticsCampaign Add an optional value to be used for the utm_campaign parameter in Google Analytics tracked links. String campaign name
X-MC-Metadata Information about any custom fields or data you want to append to the message. Up to 200 bytes of JSON-encoded data as an object. The object should be flat; nested object structures are not supported.
X-MC-URLStripQS Whether to strip querystrings from links for reporting. "true" or "false"
X-MC-PreserveRecipients Whether to show recipients of the email other recipients, such as those in the "cc" field. "true" or "false"
X-MC-InlineCSS Whether to inline the CSS for the HTML version of the email (only for HTML documents less than 256KB). "true" or "false"
X-MC-TrackingDomain Set a custom domain to use for tracking opens and clicks instead of String domain name
X-MC-SigningDomain Set a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients). String domain name
X-MC-Subaccount Select a subaccount for sending the mail. String the unique id of a subaccount for this message

The subaccount must exist. Otherwise, the mail will be accepted at the SMTP server but ultimately fail to send.
X-MC-ViewContentLink Control whether the View Content link appears for emails sent for your account. "true" or "false"

Set to false to disable the 'View Content' link for the email. This doesn't disable internal content logging by Mandrill for compliance and abuse, but limits the content as viewed in the account.
X-MC-BccAddress An optional address that will receive an exact copy of the message, including all tracking data Can include a single email address; the address won't show up in the Outbound Activity, nor will this email be tracked individually. This mimics the BCC recipient from the account's Sending Options.
X-MC-Important Whether this message is important and should be delivered ahead of non-important messages "true" or "false"

defaults to false
X-MC-IpPool Specify a dedicated IP pool for the message. String the name of the dedicated IP pool that should be used to send the message.

If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
X-MC-ReturnPathDomain Specify a custom domain to use for the message's return-path String the domain to use for the return-path

must be a domain configured in your account already
X-MC-SendAt Specify a future date/time that the message should be scheduled for delivery UTC timestamp in YYYY-MM-DD HH:MM:SS format

Only available for paid accounts


How you set the headers is dependent upon your environment. For example, in a Rails 3 mailer, there is a handy headers method you can use:

class MyMailer < ActionMailer::Base
  def welcome
    mail to:      '', # normal mailer stuff
         from:    '',
         subject: 'blah blah'

    headers['X-MC-Track'] = "opens, clicks_htmlonly"
    headers['X-MC-GoogleAnalytics'] = ","

An example in PHP using SwiftMailer:

$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
$headers->addTextHeader('X-MC-Track', 'opens, clicks_htmlonly');
$headers->addTextHeader('X-MC-GoogleAnalytics', '');

Tag Your Messages

Tags help classify your messages. Transactional email is very immediate in nature, meaning you tell Mandrill to send X email to Y address, and Mandrill delivers it. By default, Mandrill doesn't have much context about that message: was that a welcome email? a shipping status email? etc.

Add tags to your emails to provide that missing context. With tags attached, it's easier to report on your transactional activity, so you can ask questions like "how many welcome emails are bouncing?" or notice trends such as "order status emails aren't delivering to Hotmail addresses" so you can further diagnose issues.

Set the X-MC-Tags header to add tags to your emails. This should contain a comma-separated list of strings to add to this message as tags.

Notes about tags: Stats are accumulated using tags, though Mandrill only stores 100 tags per account (not including system-generated tags), so this should not be unique for every message or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.

Enable open and click tracking

Use the X-MC-Track header to control open and click tracking. This should include a comma-separated list of up to 2 strings: one for opens and one for clicks.

The available settings are:

  • opens: enables open tracking
  • clicks_all: enables click tracking on all emails
  • clicks: same as clicks_all
  • clicks_htmlonly: enables click tracking only on html emails
  • clicks_textonly: enables click tracking only on text emails
  • If you provide another value, open and click tracking will be disabled.

Automatically generate plain-text from HTML content

This is a useful header if you send HTML emails but don't want to make your own plain-text versions. Some email clients won't display HTML emails or your recipients may have disabled HTML emails in their mail settings. With this header you can be sure a fallback plain-text version of your message will be delivered, even if you don't take the time to craft one by hand.

The X-MC-AutoText header tells Mandrill whether to generate plain-text from your HTML. This header accepts "true", "on", "yes", "y", and 1 as positive values which will turn the feature on. It accepts "false", "off", "no", "n", and 0 as negative values, turning the feature off.

Automatically generate HTML from plain-text content

Like the previous setting, this will allow Mandrill to auto-generate part of your message. Open tracking is generally only possible with HTML emails because Mandrill embeds a tiny invisible image in the footer of the HTML portion of the email and tracks whenever that image is downloaded. To help ensure you can track opens when you're only creating plain-text emails, you can have Mandrill create an HTML version of that email automatically to add the open-tracking image. To enable this, set X-MC-AutoHtml to "true", "on", "yes", "y", or 1. To disable this feature, set this header to "false", "off", "no", "n" or 0.

Use stored templates

You can create HTML templates for future use in your Mandrill account. If you have a MailChimp account, you have the option of sending your MailChimp templates to your Mandrill account by using the Send to Mandrill button for your MailChimp templates.

The X-MC-Templateheader should be set with the pattern "template_name|block_name".

  • template_name: set to whatever you named your template in the Mandrill interface (this will match the MailChimp template name if you sent a template from MailChimp)
  • block_name: allows you to specify which mc:edit content block of the template you wish to fill with this email's body content. This is optional and defaults to "main"

Specify merge tags for dynamic or personalized content

Add dynamic data per-recipient using the X-MC-MergeVars header. Each header should be a JSON-formatted object, with name/value pairs separated by commas. To assign a global value for "var1" (the merge tag |VAR1|), Mandrill expects to receive:

X-MC-MergeVars: {"var1": "global value 1"}

To set a recipient-specific value, use the name _rcpt with the recipient's email address as the value, along with the mergevar and value pairs, like this:

X-MC-MergeVars: {"_rcpt": "", "fname": "John", "lname":"Smith"}

If you only have one recipient, use the same format as the global values above (no need to specify the recipient address since there's only one).

A separate header should be used for each recipient of an email being transmitted via SMTP. SMTP headers have a maximum length of 1000 characters, so if the header content for the global values or for an individual recipient exceeds 1000 characters, it can be broken into two (or more) headers. Just be sure to specify the recipient email address for every header for that recipient.

NOTE: SMTP headers generally may only contain ASCII characters, so if you have non-ASCII characters, such as special characters or accented characters, they'll need to be escaped. Typically, you'll want to use a JSON library that automatically escapes any non-ASCII characters.

Add Google Analytics tracking

Adding Google Analytics tracking variables to your links is a popular way to track the effectiveness of your email campaigns.

Mandrill supports two headers for this purpose. The first is a whitelist of domains which are eligible for Google Analytics variables. Some links don't work as intended when a query string is added, or if arbitrary things are added to the query string. To avoid this, you'll tell Mandrill which links are intended to receive the Google Analytics variables.

The second header is to associate these links with a particular Google Analytics campaign. What this actually means is up to you: it's frequently a Google search campaign, but you could technically put whatever tracking variable you want in here. It's what gets added to the utm_campaign parameter.

X-MC-GoogleAnalytics: a comma-separated list of domains which tracking will be added to
X-MC-GoogleAnalyticsCampaign: the value Mandrill will set for utm_campaign variable

Use custom metadata

This is a means for attaching arbitrary data to a message, which you can later use to link information back to your application or system. Metadata should be provided as a JSON-encoded object. The object should be flat; nested object structures are not supported.

You can configure Mandrill with the names of up to 10 metadata fields to index for searching. Non-indexed fields are still stored, but are not searchable.

X-MC-Metadata: up to 200 bytes of JSON-encoded metadata. If the metadata exceeds 200 bytes, it will be discarded.

Modify querystring settings for click tracking

During reporting, Mandrill strips the querystring from your links by default. This is normally what you want, as querystrings should usually just be metadata and shouldn't be counted towards the uniqueness of a URL. However, some CMSes may not act this way, so the option to disable this behavior is included.

For example, the following 3 links:

…would all be reported as the same link:

If this option is set to false, however, they would be tracked as 3 entirely separate domains.

X-MC-URLStripQS can be set to "true" or "false" to tell Mandrill whether to strip the querystring from links when reporting for this particular email. It defaults to whatever you have set on your Mandrill Sending Defaults page, which in turn defaults to true.

Preserve recipient headers for group emails

If you send to more than one recipient at a time and want all recipients to see each other recipient's information, you can use the X-MC-PreserveRecipients header. Recipients will be able to reply-all and see other recipient information if this is set to "true". If it's set to "false", Mandrill will rewrite the To and Cc headers for your email and only show information about an individual recipient.

Customize the tracking domain for click tracking

By default, the open tracking image and all click-tracking URLs in emails you send use a domain or subdomain; links get redirected from to the final destination. If you prefer, you can set up custom tracking domains to use your own subdomain in open and click tracking URLs instead of You'll need to set up custom click tracking domains first. Once you do, you can specify a default click tracking domain in your Sending Options. To change this on a per-message basis, provide the click-tracking subdomain in the X-MC-TrackingDomain header.

Customize the signing domain for email authentication

Every email that Mandrill sends is authenticated in multiple ways. We provide the ability to customize SPF and DKIM records so that your domain can explicitly give Mandrill permission to send on your behalf. If you're sending on behalf of clients, though, you may not have the ability to change the SPF and DKIM settings for those domains. In those cases, you may want to have the emails authenticated for your domain, though, instead of In email clients like Gmail and Outlook, this means that recipients would see the emails as coming from your domain, on behalf of your client. To set the signing domain for each message, specify a domain in the X-MC-SigningDomain header.

Specify the subaccount for sending the message

Subaccounts are an additional way for users who send on behalf of many others, or who operate multi-tenant systems to separate sending for different users (besides using tags or metadata, for example). With subaccounts you can separate reputation, activity, reports, and quotas for different types of senders in a single Mandrill account.

Use this header to specify a subaccount to send the message. The subaccount must exist in order for the message to be sent. The subaccount cannot be validated by the SMTP server, so the message will be accepted by the SMTP server, but then not sent if the subaccount doesn't exist.

By default, a View Content link is available for 24 hours after a message is sent. For sensitive emails, you may want to disable this link so the contents aren't visible in the account. Setting this parameter to "false" will disable the View Content link for this message. Note: This doesn't disable Mandrill's own internal logging or analysis of the message, just the visibility from within the account.

Topic is closed for comments