Become an Email Pro With Our Templates API

Email templates are the secret sauce for producing consistent and scalable email campaigns. 

At Mailgun, we’ve made several responsive email templates available through our user interface. These HTML files contain modular code blocks that define your emails’ look and feel. 

We’ve also published open-source templates on GitHub to cover your everyday email needs. All you need to do is add your email content.

But what if you already have a template or need more customization beyond our plug-and-play designs? You can now use our Templates API to bring your own email templates to your Mailgun account.

Below, we’ll discuss where to find an email template, how to upload your template to Mailgun via the Templates API, and some best practices.

What are the benefits of email templates?

Email templates are HTML files that contain reusable code that makes building email campaigns a breeze. Instead of writing and testing new code each time, you can just cut and paste text, image URLs, and links into an existing template to produce a new campaign.

Key benefits include:

• Efficiency: Skip reinventing the wheel, and simply paste your email content into the template and go.

• Consistency: Maintain an on-brand look and feel throughout all of your emails by using the same code.

• Scaling: Enable non-technical team members to create email campaigns by decreasing the reliance on developers to design campaigns one by one.

In short, email templates do the heavy lifting of creating new email formats for your campaigns.

What are some types of email templates?

But there are so many templates – how can you know which one is the right one? Below, we’ve identified three main types of email templates and provided a brief description of the needs they meet:

• Email blasts are one-off marketing campaigns sent to most of your users.

• Transactional emails are messages triggered by user actions on your site, such as creating an account, purchasing something, or requesting a new password.

• Email newsletters are recurring conversations between your brand and your subscribers. Send emails like these to keep your users engaged.

Where can I find email templates?

In case you don’t want to upload your own email templates, here’s a list of free Mailgun templates:

• Choose from six existing templates on our user interface.

• Fork transactional email templates from our Github repository.

• Check out the free HTML templates at Email on Acid. 

You can use our templates as-is or inspiration to create a new template. Then, you can upload your templates to your Mailgun account via the Templates API. 

How do I get started with the Templates API?

Before uploading your email template, you must have a Mailgun account and a verified domain in our system. In addition, note that we currently only support the Handlebars template engine, which is a popular choice for email design.

Below, we’ll walk through two ways to store and initialize a template. Then, we’ll talk about versioning your templates and sending test emails to check if your template is stored correctly. 

Our Templates API is part of Mailgun’s powerful Email API. You can access our Templates API at the following endpoint: /templates. Check out our API reference docs for the Templates API for more detailed information.

How do I store a template and initialize at the same time?

Let’s get started with storing your template in your Mailgun account. 

First, let’s try storing a template with an initial active version by issuing a POST request to the Templates API endpoint. This stores the template’s metadata as well as its content.

In this request, the name, tag, and template parameters are required. The name parameter indicates the template name, used to reference the template in other API calls. The tag parameter identifies the specific version of this template. Versioning is beneficial in email campaigns, which we’ll discuss more below. The template parameter specifies the template content itself. Here, you can paste the template’s HTML content directly into the request.

But what if your template is stored on your local disc? The sample request below shows how to pull the template contents from a file. For this example, let’s assume your template is saved locally as billing.html.

As in the first example, this requires the name, template, and tag parameters.

How do I store a template and then initialize it separately?

Alternatively, you can store a template in two steps:

1. Store a template’s metadata.

2. Store a version of the template.

When you store a template without using the tag parameter to add a version number or the template parameter to provide the template content, you record the template’s metadata within your Mailgun account. Your template isn’t active at this time, but is instead stored for later.

To make your template active, you need to update the stored template metadata by providing the template content in another request. This creates the first version, v0, of your template.

Store a template’s metadata

Use the following request to store a template’s metadata without initializing.

The name parameter is required.

Store a version of the template

Use the following request to store a version of a template after you’ve created a record of the template’s metadata. Once again, let’s assume that the template’s content is stored on your local disc as billing.html. We’ve used Python in the example below.

Your template is now active since you’ve provided the template’s content and version number.

Why do I need to create versions of a template?

For your template to be active, you need to have at least one version. The initial version is named v0 in the tag parameter of the examples above. But, sometimes, it’s helpful to have multiple versions of a template.

For instance, you can use multiple versions to:

• Provide information or product updates.

• Conduct user experience research on copy, design elements, or calls to action.

• Adapt emails to fit evolving campaign needs.

Keep in mind, you must always have one active version of a template. Emails use this active version unless otherwise specified. By default, the active version is the first version you store when you upload your template.

As shown below, you can update the active version to a new version with a simple PUT request using the Templates API endpoint. For this example, let’s assume there are two versions of your template, v0 and v1, and that v0 is currently active.

The above request reassigns the active version to v1. Use this request to take advantage of the versioning functionality, which provides a powerful way to deploy your template across multiple campaigns.

So, what about sending?

Now that we’ve added your template to your account, let’s use Mailgun’s Messages API to send a test email. We could just render a message, but sending a test message allows you to see if your variable information is working as it should. Note that you need to make sure you’re attaching your data correctly for variable information to work. How you do this depends on whether you’re sending via SMTP or API.

Let’s send a test message with a POST request using recipient variables in a JSON object. We’ll use Mailgun’s Messages API to do this.

If you’ve attached your data properly, the test email should match your rendering with the variables in place.

How do I send a specific version of a template?

We talked about how creating multiple versions of an email template truly superpowers your campaign. But how do you send a specific version of a template?

By default, emails use the active version of your template. However, it’s pretty simple to configure your email to send a specific version that isn’t active. Use the following flags in your API call: t:version and t:text.

The t:version flag indicates which version of your template to use. For the t:text key-value pair, pass yes to render your template in the text part of your email.

Wrapping up

And that’s it! We’ve successfully stored our template in our Mailgun account, tried out versioning, and sent out test emails. Head over to our docs to fully harness our Templates API.

If you run into any issues with your templates, send us a support ticket! We’ll reach out as soon as we can.

Feeling creative? Send us your template designs! Read more about this in our blog post and check out the official rules.