Summary
- Choose the right type of variable
- Understand the syntax and default values
- Enable Templating Language and provide your variables
- Display content with conditions
- Organize data with objects and arrays
- Repeat content with loops
- Add templating language in the Email Editor
- Assign and format values
- Use Mailjet's predefined variables
- Use variables in links and images
- Syntax rules
- Manage errors and test your template
- Related resources
Mailjet Templating Language helps you personalize your emails and adapt their content to each recipient. You can insert contact details, display different content based on a condition, repeat a section for several items, and format values such as prices.
This guide explains the main concepts with practical examples. Start with contact properties for marketing campaigns, or use variables supplied through the Send API or SMTP relay for transactional emails such as order confirmations and account notifications.
Choose the right type of variable
A variable is a placeholder that Mailjet replaces with a value when your email is sent. The prefix before its name tells Mailjet where to find that value.
| Type | Where the value comes from | When to use it | Example |
|---|---|---|---|
data |
A contact property stored in Mailjet. | Marketing campaigns and transactional emails. | [[data:firstname]] |
var |
Data supplied with a transactional email through the Send API or SMTP relay. | Message-specific information, such as an order number or delivery date. | {{var:order_number}} |
mj |
Information supplied by Mailjet. | Details about the recipient, sender, or template. | {{mj:template.ID}} |
Mailjet also supports segmentation-based expressions for more advanced use cases. These are outside the scope of this guide. See the Template Language Reference for details.
Contact properties: use information already stored in Mailjet
Use a data variable when the information is saved as a contact property, such as a first name, country, or preferred language. Mailjet looks up the property's value for the recipient when processing the email.
Example:
Hello [[data:firstname]], welcome to our newsletter!
- If the recipient's
firstnameproperty containsGina, the email displays: Hello Gina, welcome to our newsletter! - If the property exists but the recipient has no value for it, no name is displayed.
To keep the greeting readable when a value is missing, add a default value.
Transactional variables: provide information with each email
Use a var: variable for information your application supplies with each email through the Send API or SMTP relay. For example, you can reuse the same order confirmation template and supply a different order number for each purchase.
In your template
Your order {{var:order_number}} is confirmed.In your Send API v3.1 message
{
"Variables": {
"order_number": "MJ-12345"
}
}Result
Your order MJ-12345 is confirmed.
Mailjet uses the supplied value for the email. The recipient's stored contact properties stay the same.
👉Use webhook variables in Automation emails
If your Automation workflow starts with a webhook event, your application can include values such as an order number or delivery date in that event. Put the values in the Variables object inside Data. Set Tag to the event name configured in your workflow.
Example webhook payload
{
"ContactMail": "customer@example.com",
"Tag": "purchase_completed",
"Data": {
"Variables": {
"order_number": "MJ-12345"
}
}
}In the Send Email block that sends the order confirmation, enable Use data from webhook. In the email template, use {{var:order_number}} just as in the Send API example above. When the workflow reaches that block, Mailjet replaces the placeholder with MJ-12345.
For setup instructions and a complete payload example, see Use webhook data in the Send Email block.
Marketing campaigns: Use data: variables to personalize campaigns with stored contact properties. A var: reference can use a default value, and set can assign a value directly in the template. A reference to an undefined var: variable without a default can block the message.
Understand the syntax and default values
Mailjet uses different delimiters for values and instructions. Delimiters are the brackets or symbols surrounding your code.
| Syntax | Purpose |
|---|---|
[[data:firstname]] |
Insert a contact property as a standalone placeholder. |
{{var:order_number}} |
Print a transactional variable. |
{{ ... }} |
Print the result of an expression or function. |
{% ... %} |
Add an instruction, such as a condition, loop, or value assignment. |
Contact properties also support curly braces, for example {{data:firstname}}. Use square brackets for simple contact property placeholders. Inside conditions and functions, reference the property directly as data:firstname, without another pair of brackets.
Add a fallback when information is missing
A default value is the text or value Mailjet uses when the corresponding personalization value is unavailable. Add it after the variable name, separated by a colon.
| Example | Fallback |
|---|---|
[[data:firstname:"there"]] |
Displays there when the contact has no first name value. |
{{var:delivery_date:"to be confirmed"}} |
Displays to be confirmed when no delivery date is supplied. |
{{var:optional_text:""}} |
Displays nothing when the value is unavailable. |
{{var:optional_text:" "}} |
Displays one space when the value is unavailable. |
Example:
Hello [[data:firstname:"there"]]!
Result:
If the contact's first name is Gina:
Hello Gina!
If the contact's first name is missing:
Hello there!
Simple text defaults can also be written without quotation marks, such as {{var:name:there}}. Quoted defaults make text values easier to identify and let you explicitly provide an empty string or a space.
Enable Templating Language and provide your variables
For transactional emails, enable templating in your Send API request or SMTP headers. Otherwise, templating expressions may appear as ordinary text in the delivered email.
| Sending method | Enable templating | Provide variable values |
|---|---|---|
| Send API v3.1 | "TemplateLanguage": true |
Variables object |
| Send API v3 | "Mj-TemplateLanguage": true |
Vars object |
| SMTP relay | X-MJ-TemplateLanguage: true |
X-MJ-Vars header containing a JSON object |
Templating is disabled by default for these sending methods.
Example: send a personalized email with Send API v3.1
The following is a complete JSON request body for POST https://api.mailjet.com/v3.1/send. Replace the sender address with a validated sender and the recipient address with your test address.
{
"Messages": [
{
"From": {
"Email": "sender@example.com",
"Name": "Your store"
},
"To": [
{
"Email": "recipient@example.com",
"Name": "Gina"
}
],
"Subject": "Your order confirmation",
"TemplateLanguage": true,
"TextPart": "Hello {{var:firstname:\"there\"}}, your order {{var:order_number}} is confirmed.",
"HTMLPart": "<p>Hello {{var:firstname:\"there\"}}, your order {{var:order_number}} is confirmed.</p>",
"Variables": {
"firstname": "Gina",
"order_number": "MJ-12345"
}
}
]
}When sending a stored transactional template, use its TemplateID instead of supplying HTMLPart and TextPart. Keep TemplateLanguage enabled and supply the variables used by the template.
Unless identified as a complete request, the JSON examples below are configuration fragments. Merge them into the appropriate message object in your request.
Example: provide variables through SMTP
Add these custom headers to your transactional email:
X-MJ-TemplateLanguage: true
X-MJ-Vars: {"firstname":"Gina","order_number":"MJ-12345"}Your email content can then use the same var placeholders as the Send API example.
Campaign drafts created through the API
If you create a campaign draft through the API and add templating language to its content, include the following setting in the Headers object of /campaigndraft/{ID}/detailcontent:
{
"Headers": {
"X-MJ-TemplateLanguage": "1"
}
}This enables templating for the draft's content. Continue to use contact properties for recipient-specific values in marketing campaigns.
Display content with conditions
A condition lets you show content only when a requirement is met. For example, you can personalize a greeting when a first name is available or display a shipping update when an order has been dispatched.
-
ifstarts the condition. -
elseifchecks another condition if the previous one was not met. -
elsesupplies alternative content when no previous condition was met. -
endifcloses the conditional block.
Example: personalize a marketing greeting
{% if data:firstname %}
Hello [[data:firstname]]!
{% else %}
Hello there!
{% endif %}This checks whether the recipient has a first name value. You can also check for a specific value:
{% if data:country == "France" %}
Discover our latest news from France.
{% endif %}The text appears only when the recipient's country property matches France. Make sure the contact properties used in your conditions exist in Mailjet.
Example: adapt a transactional email to an order status
Template:
{% if var:order_status:"" == "shipped" %}
Your order is on its way.
{% elseif var:order_status:"" == "processing" %}
We are preparing your order.
{% else %}
We will update you when your order status changes.
{% endif %}Send API v3.1 variables:
{
"Variables": {
"order_status": "shipped"
}
}Result:
Your order is on its way.
If order_status is missing from the API request, Mailjet uses an empty string. Since it matches neither "shipped" nor "processing", the template displays the else message: “We will update you when your order status changes.”
Combine conditions
Use comparison operators to compare values. Common operators include == (equal to), != (not equal to), < (less than), <= (less than or equal to), > (greater than), and >= (greater than or equal to). Use logical operators such as and and or to combine conditions, or not to reverse a condition. Use parentheses to show how the conditions are grouped.
In the following example, the member benefit appears only when both conditions are met:
- The order total is at least 100.
- The recipient is a member, meaning
is_memberistrue.
{% if (var:order_total:0 >= 100) and (var:is_member:false) %}
Your order qualifies for the member benefit.
{% else %}
Explore our membership benefits for your next order.
{% endif %}The values after the final colon are default values. Mailjet uses them when the corresponding variable is not supplied:
-
var:order_total:0uses the supplied order total, or0if it is missing. -
var:is_member:falseuses the supplied membership status, orfalseif it is missing. The:falsepart sets the fallback; it does not check whether membership is false or override a supplied value oftrue.
For example, provide the following values in your Send API v3.1 message's Variables object:
{
"Variables": {
"order_total": 150,
"is_member": true
}
}Both conditions are met, so the email displays: Your order qualifies for the member benefit.
If the order total is below 100, membership is false, or either variable is missing, the email displays: Explore our membership benefits for your next order.
true or false, without quotation marks. The text string "false" is not the Boolean value false. Because it is a non-empty string, it can satisfy the membership check and display the wrong content.Organize data with objects and arrays
Transactional emails can use structured JSON data. An object groups related values, while an array contains a list of items. Objects and arrays can be nested inside one another.
Access a value inside an object
Use a dot between each level of a nested object. For example, this JSON groups a clothing item under clothes, then winter:
{
"Variables": {
"clothes": {
"winter": {
"coat": "Winter parka"
}
}
}
}To display the coat's value, use:
{{var:clothes.winter.coat}}Result:
Winter parka
order_number, when you need a separator in a single name.Group several items in an array
An array lets you provide several items under one name, instead of creating separate variables such as product1, product2, and product3. Combine it with a loop to display each item.
{
"Variables": {
"products": [
{"name": "Winter coat", "quantity": 1},
{"name": "Wool hat", "quantity": 2}
]
}
}Repeat content with loops
A for loop repeats content for each item in an array or object. Use loops in transactional emails when your application supplies a list, such as the products in an order.
Supply the list through the Send API or SMTP relay and reference it with var:. Marketing campaigns do not support these loops.
Example: display the products in an order
In your Send API v3.1 message, add a products array to Variables. Each item contains the product's name, quantity, and color. The color is stored inside a nested details object.
{
"Variables": {
"products": [
{
"name": "Winter coat",
"quantity": 1,
"details": {
"color": "Navy"
}
},
{
"name": "Wool hat",
"quantity": 2,
"details": {
"color": "Gray"
}
}
]
}
}In your template, loop through var:products to display each product's name, quantity, and color.
{% for product in var:products %}
Product: {{product.name}}
Quantity: {{product.quantity}}
Color: {{product.details.color}}
{% endfor %}Result
Product: Winter coat Quantity: 1 Color: Navy Product: Wool hat Quantity: 2 Color: Gray
var:products identifies the array supplied with the email. Each time the loop runs, product refers to the current item. Use product.name and product.quantity to read fields directly from that item.
For a nested field, add a dot between each level. In this example, product.details.color reads color from the current product's details object.
If the array contains simple values, such as ["Winter coat", "Wool hat"], use {{product}} inside the loop to display each value directly.
Example: display items grouped by category
If each category contains its own list of items, place a second loop inside the first. The outer loop displays the category name, and the inner loop displays the items in that category.
Send API v3.1 variables:
{
"Variables": {
"categories": [
{
"name": "Coats",
"items": ["Winter parka", "Raincoat"]
},
{
"name": "Hats",
"items": ["Wool hat", "Beanie"]
}
]
}
}Template:
{% for category in var:categories %}
{{category.name}}
{% for item in category.items %}
- {{item}}
{% endfor %}
{% endfor %}Result:
Coats - Winter parka - Raincoat Hats - Wool hat - Beanie
Close each loop with its own {% endfor %}. Make sure the source for each loop is an array or object. In this example, var:categories and category.items are both arrays.
Where you can use conditions and loops
| Template type | Conditions | Loops |
|---|---|---|
| Marketing | Use contact properties (data:) in a Text block. |
Unavailable in marketing campaigns. |
| Transactional | Use contact properties (data:) or variables supplied at send time (var:) in a Text or Template Language block. |
Use an array or object supplied at send time through var: in a Text or Template Language block. |
Add templating language in the Email Editor
Choose a block based on the content you want to create. You can also add templating language directly to an HTML or MJML template.
| Block | Recommended use |
|---|---|
| Text | Add a placeholder within a sentence or a simple text condition. |
| Template Language | Add control instructions around other design blocks, such as a condition that shows an image, button, or section. |
| HTML | Keep raw HTML and the templating instructions that control it together, such as a table containing repeated product rows. |
In a transactional template, you can use Template Language blocks to show a group of design blocks only when a condition is met. Place the opening and closing instructions in separate blocks:
- Add a Template Language block containing
{% if data:country == "France" %}. - Place the text, image, button, or other design blocks you want to show below it.
- Add another Template Language block containing
{% endif %}after that content.
Assign and format values
Functions let you transform values, format numbers, change text capitalization, or encode strings. The examples below cover assigning a template value with set and formatting a number with FormatNumberLocale.
Assign a value with set
Use set to assign a value directly in your template, then print that value or use it in a condition. You do not need to supply this local variable through the API or SMTP.
{% set store_name = "Winter Store" %}
Welcome to {{store_name}}.Result:
Welcome to Winter Store.
Reference the assigned variable by its name, without a var: prefix. You can assign a new value later in the same template:
{% set delivery_status = "Preparing your order" %}
{{delivery_status}}
{% set delivery_status = "Ready for dispatch" %}
{{delivery_status}}Result:
Preparing your order Ready for dispatch
set in the template. If the value should come from your application, use a var reference instead.Format numbers with FormatNumberLocale
Use FormatNumberLocale to display numbers with the decimal and thousands separators used in a specific locale. For example, the same number can appear as 3 500,00 in French or 3,500.00 in British English.
The function takes three arguments in this order.
- Format is the pattern that controls which digits and separators appear.
- Number is a number or a variable that contains a number.
-
Locale is a locale code such as
fr_FRoren_GB.
| Pattern symbol | Meaning |
|---|---|
0 |
A required digit. |
# |
An optional digit. |
, |
The position of the thousands separator. |
. |
The position of the decimal separator. |
Use these symbols in the pattern. The locale determines which separators appear in the result.
| Expression | Result |
|---|---|
{{FormatNumberLocale("#,###.00", 3500, "fr_FR")}} |
3 500,00 |
{{FormatNumberLocale("#,###.00", 3500, "en_GB")}} |
3,500.00 |
{{FormatNumberLocale("0.##", 0.666666, "en_GB")}} |
0.67 |
To format a value supplied at send time, use the variable as the second argument. Write var:price directly, without quotation marks or an extra pair of curly braces.
{{FormatNumberLocale("#,###.00", var:price, "fr_FR")}}For this example, include price in your Send API v3.1 message.
{
"Variables": {
"price": 3500
}
}Send 3500 as a JSON number without quotation marks. Quotation marks turn the value into a string, which can cause a formatting error. With the pattern and locale above, the result is 3 500,00.
Other functions support rounding, changing text to uppercase or lowercase, URL encoding, and HTML escaping. See the full function reference for the available options.
Use Mailjet's predefined variables
Mailjet provides reserved variables for information about the current message. Variables in the mj: namespace use double curly braces.
| Variable | Displays |
|---|---|
{{mj:contact.ID}} |
The recipient's Mailjet contact ID. |
{{mj:contact.email}} |
The recipient's email address. |
{{mj:sender.email}} |
The sender's email address. |
{{mj:template.ID}} |
The template ID, when a template is used. |
Other predefined variables provide sharing links for the online version of a newsletter. See the predefined variable reference for the full list and supported uses.
[[PERMALINK]] for the online version and [[UNSUB_LINK]] for the unsubscribe link use double square brackets. Keep their documented syntax; do not convert them to curly-brace expressions.When you create a marketing template in Mailjet's Email Editor, Mailjet automatically adds an unsubscribe link to the footer. If you create your marketing email in HTML, you can add the link manually:
<a href="[[UNSUB_LINK_EN]]">Unsubscribe</a>
For other languages and sending methods, see How to add an unsubscribe link to your newsletter.
Use variables in links and images
Variables can also appear in hyperlinks, button links, and the image URL of an Image block. For example, a transactional button can use {{var:account_url}} as its destination when your application supplies the complete URL.
In raw HTML, always put quotation marks around the attribute value:
<a href="{{var:account_url}}">View your account</a>Corresponding Send API v3.1 variables:
{
"Variables": {
"account_url": "https://www.example.com/account"
}
}Default values in editor URL fields
-
Hyperlinks and buttons: Default values are supported. In these URL fields, use an unquoted default without an
http://orhttps://prefix inside the expression, such as{{var:Link:www.mailjet.com}}. - Image blocks: The editor removes default values from variables in the image URL field. Supply the image URL in your data rather than relying on a default in that field.
Syntax rules
The templating updates introduced in October 2025 tightened syntax validation and improved processing performance. Use the following rules when creating or reviewing a template.
-
Close every control block. Each
{% if %}needs an{% endif %}, and each{% for %}needs an{% endfor %}. Unclosed blocks cause validation errors. - Check variable definitions. A known variable without a supplied value may resolve to empty or false where applicable, while a reference to a completely undefined variable can produce an error. Use explicit defaults for optional values.
- Match names exactly. Check capitalization, spelling, and every level of a nested object.
- Separate arithmetic from names. Write spaces around an operator when you want to perform a calculation.
-
Use quotes around link URLs in HTML. If a variable supplies the URL, write
href="{{var:url}}". -
Check unsubscribe placeholders. Make sure your template includes the correct unsubscribe placeholder, such as
[[UNSUB_LINK]], and verify that it becomes a working link in a test email.
Example: a subtraction and a variable name are different expressions.
{{var:price - 1}}This subtracts 1 from price.
{{var:price-1}}This refers to a variable whose name is literally price-1.
Manage errors and test your template
By default, a templating error prevents a transactional email from being delivered and the message is marked as blocked. Common causes include undefined variables, unclosed conditions or loops, malformed expressions, and data supplied in the wrong format.
Receive templating error reports
Configure an error-reporting address to receive information that helps you identify and fix rendering problems. The setting depends on your sending method.
| Sending method | Error-reporting setting |
|---|---|
| Send API v3.1 | "TemplateErrorReporting": {"Email": "reports@example.com", "Name": "Template reports"} |
| Send API v3 | "MJ-TemplateErrorReporting": "reports@example.com" |
| SMTP relay | X-MJ-TemplateErrorReporting: reports@example.com |
Control delivery when a templating error occurs
You can change the default error-delivery behavior. The formats differ between Send API versions and SMTP:
| Sending method | Setting | Values |
|---|---|---|
| Send API v3.1 | TemplateErrorDeliver |
false blocks delivery on an error; true allows delivery despite an error. |
| Send API v3 | MJ-TemplateErrorDeliver |
"0" blocks delivery on an error; "deliver" allows delivery despite an error. |
| SMTP relay | X-MJ-TemplateErrorDeliver |
0 blocks delivery on an error; deliver allows delivery despite an error. |
Example: Send API v3.1 error-management configuration:
{
"TemplateLanguage": true,
"TemplateErrorReporting": {
"Email": "reports@example.com",
"Name": "Template reports"
},
"TemplateErrorDeliver": false
}Troubleshoot common problems
| Problem | What to check |
|---|---|
| The email displays templating code as text. | Check that templating is enabled for your sending method. |
| A variable is undefined or has no value. | Check the name, namespace, capitalization, nesting, supplied data, and any default value. |
| A condition shows unexpected content. | Check comparison values, parentheses, and JSON types, especially false versus "false". |
| A loop cannot process its source. | Provide an array or object matching the structure expected by the loop. |
| An error mentions a variable you no longer use. | Check both the HTML and plain-text versions. An older reference may remain in the plain-text content. |
| A block or expression is invalid. | Check closing tags, matching delimiters, and spacing around operators. |
Before sending
- Test with representative data, including missing optional values.
- Check every conditional branch, including
elsecontent. - For loops, test an empty list, one item, and several items.
- Review both the HTML and plain-text versions.
- Verify links, images, the online version, and unsubscribe links where applicable.
- Check error reports and resolve rendering errors before sending to your audience.
Related resources
- Template Language Reference — Explore supported variables, operators, functions, conditions, and loops.
- Use templating language with Send API v3.1 — Review the request format and sending examples.
- Use templating language with SMTP — Configure the custom headers for transactional emails.
- Template Error Management — Learn more about error reporting and common rendering errors.