If you're integrating via SMTP, you can use SMTP headers to customize your messages, add tracking, or specify options for Transactional Email to apply to your messages. Specify a custom Reply-To
header or any of the Transactional Email-specific X-MC-*
headers for more control over your SMTP messages.
In This Article
- Custom Header Reference
- Implementation
- Tag Your Messages
- Enable Open and Click Tracking
- Generate Plain-Text from HTML Content
- Generate HTML from Plain-Text Content
- Use Stored Templates
- Specify Merge Tags for Dynamic or Personalized Content
- Add Google Analytics Tracking
- Use Custom Metadata
- Change Query String Settings for Click Tracking
- Preserve Recipient Headers for Emails with Multiple Recipients
- Customize the Tracking Domain for Open and Click Tracking
- Set the Subaccount for Sending a Message
- Choose Whether to Show a View Content Link
- Send a Copy of Every Message Sent to a Single Email Address
- Prioritize Sending for a Message
- Choose a Dedicated IP Pool
- Set a Custom Return Path Domain
- Schedule a Message to Send at a Specific Date and Time
- Set the Merge Language
Custom Header Reference
Header | Purpose | Format |
---|---|---|
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 trackingclicks_all : enables click tracking on all emailsclicks : same as clicks_all clicks_htmlonly : enables click tracking only on html emailsclicks_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 generationfalse , 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 generationfalse , off , no , or n to turn off automatic HTML generation |
X-MC-Template | Use an HTML template stored in your Transactional Email account | template_name|block_name template_name is the name of the stored templateblock_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 mandrillapp.com | String domain name |
X-MC-Subaccount | Select a subaccount for sending the mail. | String the unique id of a subaccount for this messageThe 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 Transactional Email 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 messageIf 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-pathThe 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 formatThis option is available for paid accounts only. |
X-MC-MergeLanguage | Set the merge language for the email | String one of mailchimp or handlebars |
Implementation
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: 'someone@example.com', # normal mailer stuff
from: 'you@yourdomain.com',
subject: 'blah blah'
headers['X-MC-Track'] = "opens, clicks_htmlonly"
headers['X-MC-GoogleAnalytics'] = "yourdomain.com, yourotherdomain.com"
end
end
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', 'yourdomain.com');
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 Transactional Email to send an email to a specific recipient, and Transactional Email delivers it. But by default, Transactional Email 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 Transactional Email 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:
Setting | Description |
---|---|
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 Transactional Email 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 Transactional Email 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 Transactional Email 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 Transactional Email account. If you have a Mailchimp account, you have the option of sending your Mailchimp templates to your Transactional Email 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 Transactional Email 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|*
), Transactional Email 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": "emailadress@domain.com", "fname": "John", "lname":"Smith"}
Note
-
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. Transactional Email supports two headers for this purpose.
The first is a safelist 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 Transactional Email, 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 toX-MC-GoogleAnalyticsCampaign
: the value Transactional Email will set forutm_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 http://www.domain.com and http://domain.com, your X-MC-GoogleAnalytics
header would look like:
X-MC-GoogleAnalytics: www.domain.com, domain.com
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": "foo@example.com", "user_id": "123" }
X-MC-Metadata: { "_rcpt": "bar@example.com", "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, Transactional Email 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 Transactional Email whether to strip the query string from links when reporting for this particular email. It defaults to whatever you have set in your Transactional Email account Sending Defaults.
For example with this option enabled, the following three links would all be reported as the same link—http://example.com/profile:
- http://example.com/profile
- http://example.com/profile?option_a=123&option_b=456
- http://example.com/profile?option_b=456&option_a=123
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
, Transactional Email 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 mandrillapp.com domain or subdomain. Links get redirected from mandrillapp.com 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 mandrillapp.com. 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 Transactional Email account. Learn how to get started with Subaccounts.
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 Transactional Email SMTP server, so the message will be accepted by the SMTP server, but then not sent if the subaccount doesn't exist.
Choose Whether to Show a View Content Link
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 Transactional Email'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 Transactional Email'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 mandrillapp.com, 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 Transactional Email. If you need to receive bounce details in your own application or to a specific email address, you can set up webhooks, and Transactional Email 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, Transactional Email 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 Transactional Email 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.