Additional features
Advanced personalization
MailerSend's Advanced personalization feature allows you to personalize email messages by generating dynamic content for each recipient when sending emails using the Email endpoint.
- Advanced personalization only compiles the template if
personalization
data is passed via Email API - Advanced personalization is available for
subject
,html
andtext
fields - It is cached server-side, but the hash is calculated based on content so it will reset with every change
A limited version of the Twig v3.x templating engine is used as a template language.
Template language
Example of advanced personalization passed to Email API:
{
"personalization": [
{
"email": "test@mailersend.com",
"data": {
"var": "value",
"boolean": true,
"object": {
"key" : "object-value"
},
"number": 2,
"array": [
1,
2,
3
]
}
}
]
}
Variables
Variables are used to print basic data. The variable should look like {{ var }}
. It starts with double curly brackets {{
, followed by the variable name and is closed with double curly brackets }}
.
Note
Variables are available in subject
, html
and text
fields.
General rules:
- Must be surrounded by double curly brackets
{{ var }}
- May contain alphanumeric characters and underscores (_)
- Must not start with a number or underscore
- Are case sensitive, meaning that
{{ VAR }}
is different from{{ var }}
Examples of combinations:
Syntax | Output | Details |
---|---|---|
{{ var }} | value | Display a simple variable (no array or object). |
{{ object.key }} | object-value | Display the key value of an object. |
{{ number + number }} | 4 | A simple calculation of two simple variables (no array or object). |
Conditional statement
A conditional statement (i.e. if/elseif/else) appears inside {%
%}
block. A conditional block always starts with the if
keyword followed by the statement that is being tested, and ends with the endif
keyword.
Note
Conditional statements are only available in html
and text
fields. Additional filters are also available in: escape
, default
, length
, lower
, upper
and keys
.
Example:
{% if boolean == true %}
Available
{% elseif number > 0 %}
Only {{ number }} left!
{% else %}
Sold-out!
{% endif %}
Output:
Available
Foreach
A collection of data (an array) can be printed by looping through all the items in this collection. A loop should appear inside the {%
%}
block. A loop block always starts with the for
keyword, and ends with the endfor
keyword.
Note
Foreach is only available in html
and text
fields. Additional filters are also available in: escape
, length
, lower
, upper
and keys
.
Example:
{% if array|length > 0 %}
<ul>
{% for value in array %}
<li>{{ value }}</li>
{% endfor %}
</ul>
{% endif %}
Output:
<ul>
<li>1</li>
<li>2</li>
<li>3</li>
</ul>
More details about iterating over keys, getting loop info, etc. can be found here.
Simple personalization
A simple personalization allows you to print basic data using variables in {$var}
format for each recipient when sending emails using the Email endpoint. It starts with a {$
, followed by the variable name and is closed with a }
. Rules for using simple personalization include:
- Must start with a dollar sign
- Must be surrounded by curly brackets
- May contain alphanumeric characters and underscores (_)
- Must not start with a number or underscore
- Is case sensitive, meaning that
{$VAR}
is different from{$var}
Note
Variables are available in subject
, html
and text
fields.
Template language
Example of simple personalization passed to Email API:
{
"variables": [
{
"email": "test@mailersend.com",
"substitutions": [
{
"var": "test",
"value": "value"
}
]
}
]
}
Example of combination:
Syntax | Output | Details |
---|---|---|
{$test} | value | Displays a simple variable (no array or object). |