Use merge tags to personalize your messages with your recipients' names, addresses, order information, or other customized content. Add merge tags to stored templates in your account or to content that you provide at the time of sending in your API request or SMTP message.
In This Article
Format
Merge tags use the following format, with a pipe (|
) and asterisk (*
) on each side of the merge tag name:
*|MERGETAG|*
In your template or content, merge tags might look like this:
Dear *|FNAME|*,
Thanks for your purchase on *|ORDERDATE|* from ABC Widget Company. We appreciate your business and have included a copy of your invoice below.
*|INVOICEDETAILS|*
-- ABC Widget Co.
There are three merge tags included in the previous examples. At the time of sending, provide global values and/or recipient-specific data for each merge tag.
Limitations
-
Content length for merge tags in Mandrill is generally unlimited, so you can give as little or as much data as needed when sending the email.
-
If you're sending via SMTP, SMTP headers are limited in length, so there's an upper limit on the amount of content that can be passed in a single SMTP header.
-
Merge tags can be composed of alphanumeric characters and underscores. Colons (
:
) cannot be used in merge tags.
Provide Merge Data through the API
For sending API calls (messages/send
and messages/send-template
) or template rendering (templates/render
):
-
Give global or default values for merge tags by using the
global_merge_vars
parameter. These will be used in the case where a recipient doesn't have a recipient-specific value defined. -
Use the
merge_vars
parameter to store recipient-specific values if sending to more than one recipient at a time. Forglobal_merge_vars
andmerge_vars
, provide the name of the merge tag and the value to be used using two key-value pairs.
Here's an example JSON snippet for how global_merge_vars
and merge_vars
should be passed:
...
"message": {
"global_merge_vars": [
{
"name": "var1",
"content": "Global Value 1"
}
],
"merge_vars": [
{
"rcpt": "emailadress@domain.com",
"vars": [
{
"name": "fname",
"content": "John"
},
{
"name": "lname",
"content": "Smith"
}
]
}
],
...
Provide Merge Data using SMTP Headers
-
Use the SMTP Headers API to provide global and recipient-specific merge values 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": "emailadress@domain.com", "fname": "John", "lname":"Smith"}
-
If you only have one recipient, use the same format as the global values in the previous example (no need to set 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.
Conditional or Dynamic Merge Tags
Mandrill supports conditional merge tags, but because Mandrill doesn't store list data, all merge tag values need to be provided in the API call or SMTP headers, and the conditions would be checking against those values.
Mandrill conditional merge tags support traditional IF, ELSE, ELSEIF, IFNOT logic, and the following operators:
- = equal to
- != does not equal
- > greater than
- < less than
- >= greater than or equal to
- <= less than or equal to
Examples
Use IF conditions to display content only when the condition evaluates as true:
*|IF:MERGE|*
content to display if a value for MERGE is provided
*|END:IF|*
*|IF:MERGE=x|*
content to display if the value for MERGE is x
*|END:IF|*
Note: When using a condition like *|IF:MERGE=x|*
, and no value for MERGE
is provided, the condition will evaluate as false.
Use IF and ELSE conditions to display content when a condition is true, but alternate content when the condition evaluates as false:
*|IF:MERGE|*
content to display
*|ELSE:|*
alternative content
*|END:IF|*
Use ELSEIF to display one of several possible options. Only the content following the first condition evaluated as true will be displayed—other conditions will be skipped:
*|IF:MERGE=x|*
<p>content to display if the value for MERGE is x</p>
*|ELSEIF:MERGE=y|*
<p>content to display if the value for MERGE is not x, but is y</p>
*|ELSEIF:MERGE=z|*
<p>content to display if the value for MERGE is not x or y, but is z</p>
*|ELSE:|*
<p>alternate content to display if the value for MERGE is not x, y, or z</p>
*|END:IF|*
Nest merge tags to display content based on multiple conditions:
*|IF:MERGE1=x|*
*|IF:MERGE2=y|*
<div mc:edit="main">
<p>content to display if both conditions are true</p>
</div>
*|END:IF|*
*|END:IF|*
Use negative conditions to show content when a condition is not met:
*|IF:MERGE!=x|*
content to display if the value for MERGE is not x
*|ELSE:|*
content to display if the value for MERGE is x
*|END:IF|*
*|IFNOT:MERGE|*
content to display if MERGE is not provided
*|ELSE:|*
content to display if MERGE is provided
*|END:IF|*
Use greater than, less than, equal to, etc. to display content based on numerical comparisons:
*|IF:AGE >= 18|*
Don't forget to vote this Tuesday!
*|END:IF|*
*|IF:PURCHASES >= 20|*
Enjoy this 40% off coupon! *|COUPON20|*
*|ELSEIF:PURCHASES >= 10|*
Enjoy this 20% off coupon! *|COUPON10|*
*|ELSE:|*
Enjoy this 10% off coupon! *|COUPON|*
*|END:IF|*
Content-Encoding Merge Tags
Use the content encoding class of merge tags to change how the content inside your merge tags displays.
Examples
*|HTML:YOUR_MERGETAG|*
This tag handles merge field contents as raw HTML and makes no changes.
*|URL:YOUR_MERGETAG|*
Encodes the value of your merge tag for inclusion in a URL.
*|TITLE:YOUR_MERGETAG|*
Changes the value of your merge tag to be title case (the first letter in each word is capitalized).
*|LOWER:YOUR_MERGETAG|*
Changes the value of your merge tag to be all lowercase.
*|UPPER:YOUR_MERGETAG|*
Changes the value of your merge tag to be all uppercase.
Mailchimp Merge Tags
You can also use the following Mailchimp merge tags in Mandrill:
*|FNAME|*
*|LNAME|*
*|EMAIL|*
*|DATE:FORMAT|*
*|CURRENT_YEAR|*
-
For
*|FNAME|*
and*|LNAME|*
, Mandrill will try to parse the name provided in the To header of the message to get the recipient's name. Similarly, for*|EMAIL|*
, we'll look at the recipient's email address in the To header to populate the value for that tag. -
Use
*|DATE:FORMAT|*
to show the current date in a specific format. For example,*|DATE:d/m/y|*
whered
is replaced by the day of the month in 2 digits,m
by the month with 2 digits, andy
by the year in 4 digits. View a full reference of date options on http://us3.php.net/manual/en/function.date.php. -
Most other Mailchimp merge tags won't work by default in Mandrill. Tags like
*|ARCHIVE|*
,*|LIST:ADDRESS|*
, integration-specific tags, and RSS-to-email merge tags have a specific meaning in Mailchimp as they're tied to a list or campaign. -
Mandrill doesn't store lists) or campaign data, so you can use merge tags to personalize emails in Mandrill, but you also need to provide the values for those merge tags at the time of send in your API request or SMTP message.
-
The Mailchimp
*|ARCHIVE|*
merge tag creates an online version of your email so recipients can view it as a webpage in browsers. Most transactional emails are highly personalized or contain information that shouldn't be publicly-accessible, so Mandrill doesn't create a public version of those emails. If you're sending bulk email, you might consider hosting a version of the email on your own website that you can link to in your emails. -
The Mailchimp
*|FORWARD|*
merge tag generates a link to an online form where recipients can share your email with others. Because Mandrill emails are generated and tracked individually, a web version is not provided automatically. To mimic the Forward to a Friend option in Mandrill, you could create your own online version of the email, host it on your website, and then give your recipients a way to share that online version with friends (through a direct link or an online form). Then you could track when people fill out the form or when they click the link for the shared email. -
Mandrill provides an easy-to-use merge tag to add an unsubscribe link in your Mandrill emails automatically. Mandrill's
*|UNSUB|*
merge tag uses a similar format to the Mailchimp unsubscribe merge tag: it consists of the word UNSUB, followed by a colon, and a full web address (withhttp://
orhttps://
) where recipients should be redirected when the unsubscribe is processed:*|UNSUB:http://mywebsite.com/unsub|*
You can also provide a link to your own unsubscribe process.
Use Merge Tags in Email Headers
In addition to using merge tags to personalize your message content, you can also use merge tags to customize some email headers.
API
Include merge tags in your API request:
"subject": "Your order: *|ORDERID|* has been received",
Then provide global or per-recipient merge vars:
. . .
"merge_vars": [
{
"rcpt": "recipient@example.com",
"vars": [
{
"name": "FNAME",
"content": "Jane"
},
{
"name": "ORDERID",
"content": "123456"
}
]
}
],
. . .
SMTP
Add merge tags in your message headers, then use the custom SMTP header, X-MC-MergeVars
, to provide global or per-recipient values for those merge tags.
Template Defaults
Add merge tags in the Template Defaults part of your Mandrill templates. You'll still need to provide values for the merge tags in your API request or SMTP message.
- Go to Outbound in your Mandrill account.
- Click Templates in the top menu.
- Hover over your template name and click edit code.
- Under Template Defaults, add your merge tag(s) in the field under From Name or Subject.
Note
-
If you provide a different subject or from name in your API request or SMTP message, that will override your default template settings.
-
If you have a merge tag with a long value or have added a handful of merge tags for your message headers, you may hit header length limits with some email servers or clients. This could result in your emails appearing incorrectly for some recipients.
-
It's best to use merge tags for small snippets of information that you need to inject at the time of send. We strongly recommend sending a handful of live test emails to various email clients when using merge tags in message headers.
-
Merge tags are supported in the from name, subject line, and body of an email only. Merge tags can't be included in custom
X-
headers or the List-Unsubscribe header. -
It's not possible to use a merge tag as the default From Address for your template.