How to Use SMTP Headers to Customize Your Messages

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.

In This Article

Custom Header Reference

X-MC-Tags Add tags to the outgoing message Comma-separated list of strings, each string being a tag to apply to the message

No more than 50 characters per tag and 100 tags per account
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, or y to turn on automatic text generation

false, off, no, or n 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, or y to turn on automatic HTML generation

false, off, no, or n 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 merge tags that appear in your message content A JSON-formatted object with name/value pairs for the variable name and value, separated by commas

You can add more than one instance of this header.

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 aren’t supported.
X-MC-URLStripQS Whether to strip query strings from links for reporting true or false
X-MC-PreserveRecipients Whether to show recipients of the email other recipients, like 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-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 Whether to show the View Content link for delivered emails 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 This header can include a single email address only. The address won’t show up in the Outbound Activity, and won’t be tracked individually. This mimics the BCC recipient from the account’s Sending Options page.
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 doesn’t exist, your default pool will be used instead.
X-MC-ReturnPathDomain Specify a custom domain to use for the message’s return-path domain String the domain to use for the return-path

The domain must be 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

This option is available for paid accounts only.
X-MC-MergeLanguage Set the merge language for the email String one of mailchimp or handlebars


How you set the headers is dependent upon your environment. For example, in a Rails 3 mailer, there is a 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

Use tags to classify certain types or groups of emails you send. For example, transactional email is immediate in nature—you tell Mandrill to send an email to a specific recipient, and Mandrill delivers it. But by default, Mandrill doesn't have much context about that message—was it a welcome email, shipping status email, etc. Add tags to your emails to provide that missing context.

When you tag messages, it's easier to report on your transactional activity, so you can ask questions like, 'how many welcome emails are bouncing' or notice trends like 'order status emails aren't delivering to Hotmail addresses' so you can diagnose issues on your own.

To add tags to your SMTP emails, include the X-MC-Tags headers. This should contain a comma-separated list of strings to add to the message as tags.

Stats are accumulated using tags though Mandrill only stores 100 tags per account (not including system-generated tags), so this shouldn't be unique for every message or change regularly. Tags should also 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 two strings: one for opens and one for clicks.

The available settings are:

opens Enables open tracking
clicks_all Enables click tracking on all emails (HTML and plain-text)
clicks Same as clicks_all—enables click tracking on all emails (HTML and plain-text)
clicks_htmlonly Enables click tracking on HTML emails only
clicks_textonly Enables click tracking on text emails only


If you provide any other values, open and click tracking will be disabled.

Generate Plain-Text from HTML Content

Use this option 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 always be included.

The X-MC-AutoText header tells Mandrill whether to generate plain-text from your HTML. Use a positive value (true, on, yes, or y) to enable the feature and a negative value (false, off, no, or n) to disable the feature.

Generate HTML from Plain-Text Content

Use this option to auto-generate the HTML part of your email based on the text you provide. Open tracking is possible only 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 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.

Use a positive value (true, on, yes, or y) to enable the feature and a negative value (false, off, no, or n) to disable the feature.

Use Stored Templates

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-Template header 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: 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"

Use 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. For example, 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 in the earlier example. There's no need to specify the recipient address since there's only one.

  • Use a separate header 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.

  • SMTP headers may contain only ASCII characters, so if you have non-ASCII characters like accents, 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 that 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 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 that tracking will be added to
  • X-MC-GoogleAnalyticsCampaign: the value Mandrill will set for utm_campaign variable

Be sure to include any subdomains used in your URLs so Google Analytics tracking can be added. For example, if your message contains links to both and, your X-MC-GoogleAnalytics header would look like:


Use Custom Metadata

To include custom metadata with an SMTP submission, include the X-MC-Metadata header with a JSON-encoded set of key-value pairs as the value. Metadata should be provided as a JSON-encoded object. The object should be flat as nested object structures aren't supported.

For example:

X-MC-Metadata: { "user_id": "45829", "location_id": "111" }

And to include per-recipient metadata, include a _rcpt key in the encoded JSON object to indicate which recipient the metadata should apply to.:

X-MC-Metadata: { "group_id": "users_active" }
X-MC-Metadata: { "_rcpt": "", "user_id": "123" }
X-MC-Metadata: { "_rcpt": "", "user_id": "456" }

There's a 200-byte limit for metadata. Once 200-byte limit is reached, none of the metadata will be included. Since this is structured data, there isn't a way for us to anticipate where to truncate which value.

Change Query String Settings for Click Tracking

During reporting, Mandrill strips the query string from your links by default. Normally that's desirable since query strings are typically just metadata and shouldn't be counted towards the uniqueness of a URL. Some CMS providers may not act this way, so the option to disable this behavior is included.

X-MC-URLStripQS can be set to "true" or "false" to tell Mandrill whether to strip the query string from links when reporting for this particular email. It defaults to whatever you have set in your Mandrill account Sending Defaults.

For example with this option enabled, the following three links would all be reported as the same link—


With the option disabled, the three links would be tracked as three entirely separate URLs.

Preserve Recipient Headers for Emails with Multiple Recipients

If you send to more than one recipient at a time and want all recipients to see each other recipient's information, 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 Open and 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 After you add a custom tracking domain, you can define a default click tracking domain on the Sending Defaults page in your account. To change this on a per-message basis, provide the click-tracking subdomain in the X-MC-TrackingDomain header.

Set the Subaccount for Sending a Message

Subaccounts help you separate reputation, activity, reports, and quotas for different types of messages being sent from a single Mandrill account. Learn how to get started with Suabccounts.

Use the X-MC-Subaccount to set a subaccount to send a message.

The subaccount must exist for the message to be sent. Subaccounts can't be validated by the Mandrill 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 the X-MC-ViewContentLink parameter to false will disable the View Content link for the message.

This doesn't disable Mandrill's own internal logging or analysis of the message, just the visibility from within your account.

Send a Copy of Every Message Sent to a Single Email Address

This is Mandrill's built-in Bcc recipient option. With this option enabled, we'll send a blind-carbon-copy of the email (including all tracking information) to the address you specify.

We don't charge for these emails, but since all tracking is included for the Bcc recipient too, if that recipient opens or clicks the email, those actions will be tracked back to the original recipient and will affect reports.

Enable this option using the X-MC-BccAddress header.

Prioritize Sending for a Message

If you have a campaign or large batch of emails getting queued into your account's backlog, we'll reserve an extra 5% of your hourly quota so more critical emails like password resets or order confirmations can send without delay.

Use the X-MC-Important header with a value of true to flag important messages and give them priority over other messages you're currently sending.

Choose a Dedicated IP Pool

When you have more than one dedicated IP address, you can create different pools to manage those IPs. For example, as you send larger volumes of email, it can be helpful to use different IPs for different types of mail like bulk vs. transactional.

Set a dedicated IP pool on a per-message basis using the X-MC-IPPool header.

Set a Custom Return Path Domain

The Return-Path header is used to show where SMTP events and bounce messages should be sent. By default, this address points to, but you can customize the Return-Path domain to point to your own domain instead.

When using a custom Return Path domain, bounces will still be handled by Mandrill. If you need to receive bounce details in your own application or to a specific email address, you can set up webhooks, and Mandrill will send information to your webhook URL whenever these events occur. From there, you can process the events as needed in your application/database or use a bit of code to forward the bounce information along in a new email.

Enable a custom return path domain on a per-message basis using the X-MC-ReturnPathDomain header.

Schedule a Message to Send at a Specific Date and Time

When you send a message, Mandrill allows you to schedule a time when the message should be sent. We'll store the message until then and then send it automatically.

Provide the scheduled time in the X-MC-SendAt header. Both SMTP and the API accept a UTC timestamp in YYYY-MM-DD HH:MM:SS format.

Since you're using SMTP and don't have direct access to the message ID that Mandrill generated for your message (that's generated by our API), you can also use the messages/list-scheduled method to look up scheduled messages for a specific recipient.

Set the Merge Language

This option sets the merge language to use when evaluating merge tags in your emails. For example, you can use the MailChimp merge language or Handlebars.

Control this option on a per-message basis using the X-MC-MergeLanguage header.