Skip to main content

Email Templates​

Email templates enable you to send flexible, custom tailored emails to many different recipients hassle-free, and all in one easy request.

Using Email Templates​

To use email templating, you need to make two small changes to your request.

The first step is to add a template_type field to the content item, and assign it the value of the type of template you wish to use.
Currently, the only supported template type is mustache.

"content" : [
  {
    "type": "text/plain",
    "value": "Template", 
    "template_type": "mustache"
  }
]
warning

The template_type field must be present in each content part that contains a template. If no template_type field is set, that content part will not be modified, and any templating within will be sent as normal text.

Next, simply add the data to fill in your template to the dynamic_template_data field in each personalization:

"personalizations": [
    {
      "to": [{ "email": "recipient@example.com" }],
      "dynamic_template_data": {"key": "value"}
    }
  ]
tip

You can use the dry-run query argument to preview messages before they are sent and ensure that everything is rendered properly.

Example​

Here is an example of a full request using email templates:

{
  "personalizations": [
    {
      "to": [{ "email": "recipient1@example.com" }],
      "dynamic_template_data": {"name": "Jane Doe"}
    },
    {
      "to": [{ "email": "recipient2@example.com" }],
      "dynamic_template_data": {"name": "John Smith"}
    }
  ],
  "from": { "email": "sender@example.com" },
  "subject": "Template Example",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello {{name}}",
      "template_type": "mustache"
    }
  ]
}

This request will generate and send unique emails to each recipient, with the following respective contents:

Hello Jane Doe
Hello John Smith

Mustache Templates​

Mustache is a simple and flexible templating language that allows you to easily create custom messages for all your recipients.

Here are some features you may find useful:

tip

The full mustache template documentation can be found here.
Please note that some features may not be supported, see the Supported Mustache Features section for more details.

Subfields​

Using the . symbol, you can access subfields for a given key:

Example​
{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com"}],
      "dynamic_template_data": {
        "name": {
          "title": "Ms.",
          "first": "Jane",
          "last": "Doe"
        }
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template Subfield Example",
  "content": [
    {
      "type": "text/plain",
      "value": "Dear {{name.title}} {{name.last}}, \nYou have set your account name to {{name.first}} {{name.last}}, is this correct?",
      "template_type": "mustache"
    }
  ]
}
Result:​
Dear Ms. Doe, 
You have set your account name to Jane Doe, is this correct?

List Iteration​

Using the # opening symbol and / closing symbol, you can iterate through lists:

Example​
{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com"}],
      "dynamic_template_data": {
        "purchases": [
          {
            "name": "bread",
            "price": "11.27"
          },
          {
            "name": "eggs",
            "price": "4.99"
          },
          {
            "name": "milk",
            "price": "7.49"
          }
        ]
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template List Example",
  "content": [
    {
      "type": "text/html",
      "value": "Your receipt: \n<ul>\n{{#purchases}}<li>{{name}}: ${{price}}</li>\n{{/purchases}}</ul>",
      "template_type": "mustache"
    }
  ]
}
Result:​
Your receipt: 
<ul>
<li>bread: $11.27</li>
<li>eggs: $4.99</li>
<li>milk: $7.49</li>
</ul>

If Checks​

Using the # opening symbol and / closing symbol, you can check for booleans:

Example​
{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com"}],
      "dynamic_template_data": {
        "anniversary": true,
        "account_age": 3
      }
    },
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "dynamic_template_data": {
        "anniversary": false,
        "account_age": 5
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template If Example",
  "content": [
    {
      "type": "text/html",
      "value": "Thank you for being such a loyal customer!{{#anniversary}}You have been with us for {{account_age}} year(s) now!\nHere is a coupon code as thanks: 50OFF{{/anniversary}}",
      "template_type": "mustache"
    }
  ]
}
Results​
Thank you for being such a loyal customer!
You have been with us for 3 year(s) now!
Here is a coupon code as thanks: 50OFF
Thank you for being such a loyal customer!

If-not checks​

Using the ^ symbol, you can format text to display when a given variable is false, or does not exist.

Example​
{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "dynamic_template_data": {
        "verified": true
      }
    },
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "dynamic_template_data": {
        "verified": false
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template If-not Example",
  "content": [
    {
      "type": "text/html",
      "value": "{{#verified}}Your account has been successfully verified!{{/verified}}{{^verified}}Account verification failed.{{/verified}}",
      "template_type": "mustache"
    }
  ]
}
Results​
Your account has been successfully verified!
Account verification failed.

HTML Escaping​

By default, mustache HTML-escapes substitutions so that they aren't rendered as HTML, potentially breaking formatting. If you want to disable escaping, you can do it either using triple brackets {{{ }}} or the & symbol:

Example​
{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "dynamic_template_data": {
        "sample_text": "<b>Big Text</b>"
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template Html Escaping Example",
  "content": [
    {
      "type": "text/html",
      "value": "Here is some sample text: {{{sample_text}}}\nAnd again: {{&sample_text}}\nUnescaped text: {{sample_text}}",
      "template_type": "mustache"
    }
  ]
}
Results​
Here is some sample text: <b>Big Text</b>
And again: <b>Big Text</b>
Unescaped text: &lt;b&gt;Big Text&lt;/b&gt;

Comments​

You can also leave comments in your templates, and they will not be rendered for the end user.

Example​
{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "dynamic_template_data": {
        "sample_text": "sample value"
      }
    }
  ],
  "from": {
    "email": "sender@example.com"
  },
  "subject": "Template Comments Example",
  "content": [
    {
      "type": "text/html",
      "value": "Here is some sample text:{{! TODO: add second sample text }} {{sample_text}}.",
      "template_type": "mustache"
    }
  ]
}

Result​

Here is some sample text: sample value.

Supported Mustache Features​

We support the following Mustache Templating features: (Names as per the Mustache documentation)

  • Variables
  • Dotted names
  • Implicit Iterator
  • Non-Empty Lists
  • Non-False Values
  • Inverted Sections
  • Comments
  • Set Delimiter