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 and text 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).