Knowledge Base/Getting Started/Templates and Dynamic Content

How do I use merge tags to add dynamic content?

posted this on July 9, 2012, 2:40 PM

You've got the copy ready for your transactional emails. Now you want to personalize your messages with your recipients' names, addresses, order information or other content. Merge tags allow you to define a placeholder where pieces of recipient information can be injected at the time of sending.

Add merge tags to your templates or content

Add merge tags to stored templates in your account or to content that you provide at the time of sending.


Merge tags take the following form (with a pipe and asterisk on each side of the merge tag name):


In your template or content, merge tags might look like this:

Dear *|FNAME|*,
   Thank you for your purchase on *|ORDERDATE|* from ABC Widget Company. 
We appreciate your business and have included a copy of your invoice below.


Please let us know if you have further questions.

     -- ABC Widget Co.

There are three (3) merge tags included above. At the time of sending, provide global values and/or recipient-specific data for each merge tag.


  • Content length for merge tags in Mandrill is generally unlimited, so you can provide 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 (see SMTP section below for details).
  • Merge tags can be composed of alphanumeric characters and underscores.

Provide merge data through the API

For sending API calls (messages/send and messages/send-template) or template rendering (templates/render):

Provide 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 provide recipient-specific values if sending to more than one recipient at a time. For global_merge_vars and merge_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": "",
                "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": "", "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.

Topic is closed for comments