1. Mailjet
  2. Support
  3. Documentation

Passport for Transactional Emails



Whether you're a marketer, designer or coder, working collaboratively creating engaging transactional emails was never that easy… until now with Passport:

Email designers or Marketers can now design beautiful and impactful transactional templates without coding skills:

  • Design your transactional email with drag and drop
  • Preview your emails instantly over multiple devices
  • Manage your templates in your company’s online library

Developers will also benefit from advanced features allowing them to create rich templates which adapt their content depending on the recipient’s characteristics:

  • Create conditional sections using variables passed to Send API
  • Use HTML blocks of code
  • Add loops, conditionals, arrays using Mailjet’s Template Language
  • Convert designed sections into Template Language with one click
  • Access sample code (Curl, PHP, Ruby, Java, …) for testing and integration
  • Download any template as HTML

And remember, any templates created with Passport have native responsive design!

Create a Transactional Template

From the main menu, select Transactional → My Transactional Templates


Transactional Passport

Click the 'Create a new template' button to continue.

Transactional Passport

The next step is to pick a base template that you can build upon.

Enter a new template name and click ‘Use this template’.

Transactional Passport

Now the fun part - customizing the template with Passport. For detailed information on how to use all the features in Passport, please read our Passport Guide.

Let’s take a look at the powerful features that allows you to code advanced transactional emails...


HTML Block

The HTML block is an easy way to design an HTML block the way you want and to see the rendering live in your email template. Drag the HTML block to your template.

Transactional Passport

Click the block to select it, then click on the 'HTML' button from the toolbar to open the HTML editor window and start coding.

Transactional Passport

{IF} Template Language

The Template Language block allows you to introduce advanced templating capabilities within your transactional template including loops, conditional statements, using arrays and more.

Mailjet’s Template Language is based on popular templating syntax (such as Django and Twig) and allows you to add logic to your email to include or remove sections of the delivered email. (Developers: For detailed information on syntax, variables, and functions, please check out our Template Language Guide.)

Simply click and drag the {IF} Template Language block onto your template. Then double-click the block to open the Template Language code editor.

Transactional Passport

And start coding!

For this example, we want to display a discount code to any customer who has made at least 5 previous orders. Using the variable ‘totalorders’ which will be passed to the Send API allows us to make the simple conditional statement:

{% if var:totalorders > "5" %}
Please use this discount code #1CUST to enjoy 10% off your next purchase!
{% endif %}

Transactional Passport

Once you are done coding, click ‘Validate Code’. The Template Language block cannot be rendered live within Passport - it will always appear as a black block with the total number of code lines and variables within.

Transactional Passport


Conditional Sections

With conditional sections, you have the power to display content sections in your email based on the value of variable sent with the Send API.

For example, you want to display an Exclusive Special to customers who live in New York when sending their order confirmation email. Simply put, if the city (variable sent to Send API) equals New York (value defined in your transactional template) then display the Exclusive Special section when sending the email.

Hover your mouse over a section to view its current section condition.
By default, all sections have no conditions: ’Always show this section’.

Transactional Passport

To create a condition: Click within the section to select it, then click ‘add condition’.

Transactional Passport

Then simply fill out the fields:

Transactional Passport

1) Click Only if
2) Variable Name: the name of the parameter that will be passed to the Send API
3) Select an operator from the drop-down list (equals, not equals, …)
4) Enter a value (true, false, alphanumeric value, ...)

Using the example mentioned above, here is the ‘Exclusive Special’ conditional section for customers who reside in New York:

Transactional Passport

Please note: even though you are limited to a simple “if” condition, you can mimic an “if else” statement by creating a condition in a different section with the opposite value.

Transactional Passport

View the condition when you hover or click in the section.

Transactional Passport

To remove a condition: Click on the section to select it, then click on ‘edit’...

Transactional Passport

Then select the ‘Always’ option.

Transactional Passport

Live Preview Mode

To preview your template, click Preview & Test → Preview Email.

Transactional Passport

The advanced preview mode allows you to set values of your variables for a true live preview of your transactional email across different devices (mobile, desktop).

In the Variables Preview window, Passport has identified the variables that are present in your email, including any variables set in the conditional sections and in the template language blocks. Simply add placeholder values in the Variables List then click ‘Update variables’.

Transactional Passport

Please note, conditional sections cannot be executed in the preview mode. To see the final rendering of the transactional email, you can send yourself a test message.

Transactional Passport


Send a Test

Before you send a test email, please enter the subject and sender information if you have not done so already. This information is only used to generate the sample code and is not stored with the template. (Note: This information needs to be entered each time the template is used in Send API.)

Transactional Passport

Now click on 'Preview & Test'.

Transactional Passport

There are two possible test options:

  • Send a test email (same as sending a test campaign)
    Before sending a test email, go to ‘Preview Email’ and enter placeholder values for any variables you may have.
  • Use the Send API
    If you select the Send API test, a modal will appear showing the template version attribute that you need to add to your API call, along with sample code that you can easily copy.

    Transactional Passport


Troubleshooting Your Test Emails

When using templating language features in Passport, you may inadvertently insert a syntax error. If a syntax error is identified in your test emails, the message will not be sent by Mailjet.

Typical syntax errors include:

  • A variable has no default value in the template but is used in the API call
  • A variable is missing from the Send API request

It is essential to be able to troubleshoot your transactional template before using it in production. With Passport, it is possible to receive an error message when your template contains a syntax error.

Actually, when a syntax error occurs, the templating language processing engine can identify the issue. A message from templating-language-error@mailjet.com will be sent to the given address, containing the error message in the body and an attachment containing the source of the original message.

Here are some common templating errors:

expression parsing error ## Unknown identifier: var:day ## near ## {{var:day ##
There is a variable that was not defined in “Vars”. This error can be fixed by adding a default value for the variable.

not valid template ## near ## y}} ##
This error occurs when there is a missing {% end if %}

"var:day" is not an array value
This error occurs when you are trying to do a loop on a non-array value.

Once you find and correct the syntax issue, simply send another test message.

You can use the error reporting system with your own transactional messages sent with the Send or SMTP API. Simply add the following headers in your API send request:

  • MJ-TemplateErrorReporting: Email Address where a carbon copy with error message is sent to.
  • MJ-TemplateErrorDeliver: Define if the message is delivered to the recipient even if an error is discovered in the templating language.

By default, the delivery of a message in error to the recipient is turned off.

Check out our Transactional Templating Guide for more information.

Publishing & Using Your Template

Click ‘Save & Publish’ from the main design page.

Transactional Passport

Congratulations, your new transactional template is now published and ready for use. To help you quickly integrate your template into your environments, several code examples have been provided: Curl, PHP, Node, Ruby, Python, Go, Java, C#

Transactional Passport

Please note that you need to set the variable values in the sample code. It is recommended to test your template in a pre-production environment so you can set the variables values and view the final data on your transactional emails.

Transactional PassportRelated Reading

If you have any questions on using Passport Transactional, please open a ticket with our Support Team.

Happy Sending!


Try Mailjet now ?
Create an account - no engagement, no hidden fees