Templates

Mailgun allows you to store predefined templates via the Template API and use them to send messages via the Sending API by providing the template name. The hard defined limit for templates is 100 templates per domain. Each template can have up to 10 versions.

To learn more about templates and how to use them, see the article: What's Up with Mailgun Templates?

To send a message using the template feature:

First, you must create a template. You can do this via the Template API, or via our Template Builder in our UI.

curl -X POST -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/templates \
    --form-string template='<div class="entry"> <h1>{{title}}</h1> <div class="body"> {{body}} </div> </div>' \
    -F name='template.test' \
    -F description='Sample template'

The response returns stored template information:

{
  "template": {
     "createdAt": "Wed, 29 Aug 2018 23:31:13 UTC",
     "description": "Sample template",
     "name": "template.test",
  },
  "message": "template has been stored"
}

The template is now ready to use for sending messages:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <postmaster@YOUR_DOMAIN_NAME>' \
    -F to=recipient@example.com \
    -F subject='Hello there!' \
    -F template="template.test" \
    -F t:variables='{"title": "API documentation", "body": "Sending messages with templates"}'

If you are sending a MIME, you can instead pass template variables via the X-Mailgun-Template-Variables header.

Handlebars

Mailgun's templates use a fork of the template engine, Handlebars. To provide values for substitution, you must use Attaching Data to Messages.

One of the easy ways to implement dynamic content in your template is to use Handlebar's Block Helpers. Mailgun's implementation of Handlebars supports the following block helpers: if, unless, each, with, equal.

The if block helper

The if block helper will allow you to conditionally render a block in your template. For examples, if you wanted to use a tempate that would dynamically change language body, you would include the following in your HTML:

{{#if english}}
<p>This text is in the English language.</p>
{{else if spanish}}
<p>Este texto está en idioma español.</p>
{{else if french}}
<p>Ce texte est en langue française.</p>
{{/if}}

In order to send the spanish version, for example, you would pass the h:X-Mailgun-Variables parameter with the following JSON data:

{"spanish" : "true"}

The unless block helper

The unless block helper is essentially the inverse of the if helper. The block will only be rendered if the expression returns a false value. Include the following in your HTML:

{{#unless paid}}
<h3 class="warning">WARNING: Your account is past due and will be suspended shortly. Please contact our billing department for assistance</h3>
{{/unless}}

And example JSON payload would like this this:

{"paid" : "false"}

The each block helper

When using the each helper, you can iterate a list. Iclude the following HTML:

{{#each user.services}}
<li>You scheduled {{this.service}} on {{this.date}}</li>
{{/each}}

Your JSON data could look something like this:

{
 "user":
 {
    "services":
    [
       {
          "date":"07/30/2019",
          "service":"deliverability consultation"
       },
       {
          "date":"08/05/2019",
          "service":"sales consultation"
       }
    ]
 }
}

The email would end up looking like this:

• You scheduled deliverability consultation on 07/30/2019
• You scheduled sales consultation on 08/05/2019

The equal block helper

The equal helper renders a block if the string version of both arguments are equals. For example, if you include the following in your HTML below:

<p>{{#equal foo "bar"}}foo is bar{{/equal}}</p>
<p>{{#equal foo baz}}foo is the same as baz{{/equal}}</p>
<p>{{#equal nb 0}}nothing{{/equal}}</p>
<p>{{#equal nb 1}}there is one{{/equal}}</p>
<p>{{#equal nb "1"}}everything is stringified before comparison{{/equal}}</p>

Then pass the h:X-Mailgun-Variables parameter with the following JSON data:

{"foo": "bar", "baz": "bar", "nb": 1}

The resulting email would end up looking like this:

foo is bar

foo is the same as baz

there is one

everything is stringified before comparison