Email Templates

In this article: 


Email Templates allow you to design, edit, and host HTML email templates on Mailtrap Email Delivery Platform and reference them via API.

You don’t need to save the template in your code; you can upload HTML or use one of the ready-made templates. Then, you can call the template via API, send it to your recipients with Mailtrap Email Sending, or inspect it in your virtual inbox with Mailtrap Email Testing. 

Note: You should have both Email Testing and Email Sending accounts set up to use Email Templates for testing. This doesn’t apply to sending. 

By storing the template on Mailtrap platform and calling it via API, you can easily change the template code without committing to your codebase. 

Additionally, Email Templates support Variables, and Mailtrap uses Handlebars as a template engine. 

You can put {{user_name}} into your template and pass “John” as the “user_name” value via API. Afterward, Mailtrap renders the rest of the HTML and replaces the variable with the value. Handlebars also support more logic operators. For more information, check our article on using Handlebars syntax with Mailtrap.

Email Templates are available for all Email Sending and Email Testing users. Each email sent using templates counts towards your monthly quota. Each account can have up to 100 email templates. If you need more - please contact Support.

Creating a template - Email Sending and Email Testing

To create a template, you need to add a sending domain in advance. Check our Sending Domain Setup guide if you need any help with that.  

Important Note: To be able to send emails using email templates in production, your domain needs to be verified. The verification isn’t necessary for sending email templates to your Email Testing inbox. 

To create a template, follow the steps below: 

  1. Navigate to the Email Templates menu and click the Create New Template button 

  1. Click the drop-down menu to select one of your domains, then click the Select button to choose a template and confirm with the Create Template button. 

  1. Proceed to review and edit the template, then click Save to complete the action.

    • The main Email Templates menu features all your saved templates. To quickly access a saved template, just click on it within the main menu.

Editing and customizing templates - Email Sending and Email Testing 

Mailtrap gives you a few options to ensure templates perfectly fit your needs. Here’s what you can do. 

Details tab

Each template is required to have a name, category, and an assigned domain.

Adding an Email category to a template is beneficial because you’ll see the performance stats in Email Sending for each template under Email Categories, where each category equals a template (applies to Email Sending Email Templates). 

For example, you create a template for a welcome email and name it Welcome Email, then use the same naming for the template category.

Reminder: To save changes to your template, click the Save Template button. Otherwise, the changes won’t be applied.

Code editing

Each email template needs to have a defined subject, and here you can also use a variable.

As for the content itself, you can edit the HTML or Text part, depending on the emails you want to send. 

The editor supports Find and Replace options, and you can use Cmd+F or Win+F as a hotkey to reveal a quick search bar.

If your template has an error, Handlebars cannot render it. You’ll see an error message in the Preview tab, and the RAW code with an error will be highlighted in the Editor

You can’t save a template with errors, either. Remember that we don’t validate HTML.

Image upload

Mailtrap Email Templates allow you to use and host your images within our platform. To make things easier, you can upload images from the Code Editor and get a public URL to reference an image in the template under the <img> tag. Here’s a quick guide.

1. Click Upload image in the upper right corner of the Code Editor

2. Hit the Upload New button in the following menu and choose an image from your local drive (Supported formats are JPG, PNG, and GIF, and the maximum file size is 2 MB).

3. Once the image is uploaded, you will receive a confirmation notification. If the file format is unsupported or the image is too big, you will receive the corresponding error message. 

4. Click the copy icon to copy the image URL to your clipboard, then click Templates to go back to the editing menu.

5. Proceed to add the image to the template body under the <img> tag. You’ll be able to preview it in the template as soon as the asset is added. 

You can delete image assets by clicking on the trashcan icon at the far right of the image. This action can’t be undone, and the templates featuring the image will no longer display the asset.

You can filter the uploads using search. All assets are available within your account and the templates themselves. 

Tip: Use logical names in image filenames. For example - Logo.png, not 1232.png.


As mentioned earlier, when you change the code, you see real-time changes in the Preview space.

You can switch between Mobile/Desktop previews, but note that this isn’t an exact rendering of your email, just an emulation to see the visual representation of the code for reference. 

Test Data

Mailtrap automatically parses your template and shows all the variables we found. The Test Data tab helps you preview the object variables, which you pass via the Mailtrap Sending API or Mailtrap Testing API to send your email in production or test it in staging.

By default, as a value, we put a variable name and add the “Test_” prefix.

You can change the values, and that’s reflected under the email Preview. However, these changes are not saved even if you click the Save Template button. When you leave the page, we prefill values again with “Test_” values.

Send test

If you’re using email templates in production, you can send a test email to the account owner's email address to run basic tests. Simply press the Send Test button. 

Important Notes:

  • Send Test feature isn’t the same as testing email templates with Email Testing. 
  • To send a successful test email, save your template first and make sure it doesn’t have any Handlebars errors. 
  • Your domain should be verified to send a test. 
  • Each test email is billed over your quota.

Template integration - Email Sending 

  1. Navigate to Email SendingEmail Templates in the menu on the left. 

  1. Select your template and open the Integrations tab. 

    • Here, you can find ready-made examples of sending emails using different languages and Mailtrap Sending API. When choosing PHP, Node.js, Ruby, or Python, you’ll also find links to official SDKs. 

  1. Copy the code for the desired programming language or cURL. The snippet already contains credentials such as template UUID (the main ID of your Template), your API token, and the Sending API endpoint. 

  1. Paste the code into your project and customize it if needed. Then run the code to send an email to the email address you indicated in your script. 

For more details, open the API docs and go to Email Sending APIEmailsSend email (including template). Under Body, click the dropdown menu, and choose EmailFromTemplate

Template integration - Email Testing 

  1. Navigate to Email SendingEmail Templates in the menu on the left. 

  1. Select your template and open the Integrations tab. 

    • Here, you can find ready-made examples of sending emails using different languages and Mailtrap Sending API. Note: SDKs don’t support Email Templates for Email Testing yet. However, you can use this feature with any library that supports HTTP requests. 

  1. Copy the code for the desired programming language or cURL. The snippet already contains a template UUID (the main ID of your Template), but you'll need to change the API endpoint and the API token (see the next steps). 

  1. Paste the code into your project. Change the Sending API endpoint ( ) to Testing API endpoint ( ). 

  1. You’ll also need your inbox_id . You can access it by going to Email Testing and opening the desired inbox. inbox_id is the number in the URL. 

  1. Add the inbox_id to the end of the endpoint URL, like in the screenshot below. 

  1. The last parameter you’ll need to modify is Authorization: Bearer , which requires your API token as the value. Go to SettingsAPI Tokens and copy the token next to the chosen inbox. 

  1. Now, substitute the API token in the script with the token you just copied. 

  1. Finally, run the test and check the inbox you specified in the script to inspect your email template. 

For more details, open the API docs and go to Email Testing APITest EmailsSend email. Under Body, click the dropdown menu, and choose EmailFromTemplate

List of templates and user permissions

Clicking on Email Templates in the side menu lists all the templates you can access.

Access to templates is managed on a domain level. You need to have Admin access to a domain to manipulate the templates. In case you don’t have Edit rights, you can’t change the template.

Reminder: You can delete a template. However, this action is irreversible, so be sure to change the sending/testing code after deletion. When the template is deleted, the UUID is also deleted, and Mailtrap won’t be able to render it. 

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us