1. Mailjet
  2. Support
  3. Documentation

Passport for Transactional Emails

Summary

Introduction

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!

Access Passport for Transactional Emails

From the main menu, select Transactional → My Transactional Templates

.

Transactional Passport

Create a Transactional Template

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.

Transactional Passport

For this example, we will select the Receipt template. Enter a new template name and click ‘Use this template’.

Transactional Passport

[top]

Define Template Details (Email & Sender Details)

Enter the key sender and email information:

Transactional Passport

  • Email Subject: The subject of your transactional email as it will appear in the recipient’s inbox.
  • Customize your preview text: Change the default preview text to help increase your open rates.
  • From: Name: The name your recipients will see in the ‘From’ field.
  • From: Address: Select a sending address from the drop-down list.
  • Use a different reply-to address (optional): To have replies sent to another email address, click the link to enter a different email address.

Please note: The information entered here is used to generate the sample code at the end of the template creation process and is not stored with the template. This information needs to be entered each time the template is used in Send API.

Once the details have been entered, click 'Start and design your template'.

[top]

Design with Passport

Passport uses a drag & drop interface that allows you to quickly design your transactional template:

Add content (text, images, buttons, etc) by clicking the content block and dragging it to your template. To move any content block, just drag and drop it to the new location.

Transactional Passport

Add sections to your campaign by dragging and dropping a section onto your campaign.

Transactional Passport

Customize your content by simply clicking within any section and make your changes using the toolbar that appears.

Transactional 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...

[top]

HTML Block

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

Add HTML code blocks directly into your template.

Transactional Passport

Drag the HTML block to your template. 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. The complete Template Language Reference Guide can be found on dev.mailjet.com under Transactional Templating.

Simply click and drag the {IF} Template Language block onto your template.

Transactional Passport

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

[top]

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”.

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.

Live Preview Mode

To preview your template, click ‘Preview & Test’ from the main design page.

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, tablet, desktop).

Transactional Passport

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

Click on the ‘X’ to close the Variables Preview window and check out how your transactional email looks.

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

[top]

Send a Test

From the Preview & Test page, you can send a test email to view how your email will behave with conditional sections.

Before you send a test email, enter variable placeholders in the Variables Preview window and click ‘Update variables’.

Transactional Passport

There are two possible test options:

  • Send a test email (same as sending a test campaign)
  • Use the Send API

Transactional Passport

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

Once you have finished previewing and testing, simply close the modal window to return to Passport.

Transactional Passport

[top]

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.

Transactional Passport

To help you quickly integrate your template into your environments, several code examples have been provided: Curl, PHP, Node, Ruby, Python, Go, Java, C#

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 Passport

And that’s it - you are ready to use your template in production!

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

Happy Sending!

[top]

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