MailerSend Developers

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 Twigopen in new window 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:

SyntaxOutputDetails
{{var}}valueDisplay a simple variable (no array or object).
{{object.key}}object-valueDisplay the key value of an object.
{{number + number}}4A 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 filtersopen in new window 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 filtersopen in new window 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 hereopen in new window.

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:

SyntaxOutputDetails
{$test}valueDisplays a simple variable (no array or object).

Email Survey Templates

Using our drag-and-drop email builderopen in new window, you may create email templates with a survey block to ask questions and reviews to your recipients. When your recipient receives an email with a survey, they can preview the email and answer your survey questions. Then the responses are sent to your webhook if available.

When a recipient answers all available survey questions the responses are immediately sent to your webhook(if available). However, when a recipient doesn't completely answer all available questions, after an idle time of 30 minutes, the responses would be sent.

Rules and steps for sending an email with a survey include:

  • You cannot use the following variables {$url}, ${survey}, {$survey_last_question}, as they are reserved.
  • You must enable content_tracking on your domain by selecting your domain and enabling the setting under tracking details. Content tracking is a premium feature.
  • Add a webhook with the activity.survey_submitted event to receive the survey answers.
  • You can also include the activity.survey_opened event in your webhook to know when a recipient has opened an email containing a survey at least once.

Payloads

Example of activity.survey_submitted data sent to your webhook:

{
  "email": {
    "object": "email",
    "id": "643e785e1ad4b461a307e5d2",
    "created_at": "2023-04-18T11:00:46.609000Z",
    "from": "test@domain.com",
    "subject": "Test email",
    "status": "sent",
    "tags": null,
    "preview_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2",
    "template": {
      "object": "template",
      "id": "83gwk2j7zqz1nxyd",
      "url": "http://app.mailersend.com/templates/83gwk2j7zqz1nxyd"
    },
    "message": {
      "object": "message",
      "id": "643e785d4d8189e0ef046aa2",
      "created_at": "2023-04-18T11:00:45.398000Z"
    },
    "recipient": {
      "object": "recipient",
      "id": "6410951922b6316e210cb2e2",
      "email": "reciepient@email.com",
      "created_at": "2023-03-14T15:39:05.608000Z"
    }
  },
  "surveys": [
    {
      "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
      "survey_id": "4",
      "question_id": "5",
      "question_index": 0,
      "question_type": "intro",
      "question": "We value your feedback.",
      "next_question_index": 1,
      "answers": [
        {
          "answer": "1",
          "answer_id": "1"
        }
      ],
      "rules": [
        {
          "$$hashKey": "object:3113",
          "answered": "answered_specific",
          "collapsed": true,
          "question_index": 1,
          "specific_answer": 1,
          "specific_answer_value": "Very Unsatisfied",
          "action": "skip_to_question",
          "action_question_index": 2
        }
      ],
      "correct_answers_rate": 0,
      "is_last_question": false
    },
    {
      "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
      "survey_id": "4",
      "question_id": "6",
      "question_index": 1,
      "question_type": "satisfaction_scale",
      "question": "How would you rate our new product line?",
      "next_question_index": 2,
      "answers": [
        {
          "answer": "5",
          "answer_id": "5",
          "image": "https://assets.mlcdn.com/ml/images/editor/survey/faces/color/5.png"
        }
      ],
      "rules": [
        {
          "$$hashKey": "object:3113",
          "answered": "answered_specific",
          "collapsed": true,
          "question_index": 1,
          "specific_answer": 1,
          "specific_answer_value": "Very Unsatisfied",
          "action": "skip_to_question",
          "action_question_index": 2
        }
      ],
      "correct_answers_rate": 0,
      "is_last_question": false
    },
    {
      "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
      "survey_id": "4",
      "question_id": "7",
      "question_index": 2,
      "question_type": "rating_scale",
      "question": "How likely are you to recommend our new products to a friend or colleague?",
      "next_question_index": 3,
      "answers": [
        {
          "answer": "2",
          "answer_id": "2"
        }
      ],
      "rules": [
        {
          "$$hashKey": "object:3113",
          "answered": "answered_specific",
          "collapsed": true,
          "question_index": 1,
          "specific_answer": 1,
          "specific_answer_value": "Very Unsatisfied",
          "action": "skip_to_question",
          "action_question_index": 2
        }
      ],
      "correct_answers_rate": 0,
      "is_last_question": true
    }
  ]
}
Last Updated: