Email templates

Email templating allows you to prepare and re-use email content. You can manage templates either by using the templates API or via the administration interface (look for the Email templates link on the side menu).

Basic usage

When sending emails using the submission API endpoint, do not set "subject", "html" and "text" properties. Instead, set the "template" property with the template ID value. EmailEngine will use the contents of that template to compile the email message.

$ curl "http://tttt.localtest.me:3000/v1/account/example/submit" \ 
  -H "Authorization: Bearer <token>" \ 
  -H "Content-type: application/json" \ 
  -d '{
    "from": {
      "name": "sender name",
      "address": "sender@example.com"
    },
    "to": [
      {
        "name": "recipient name",
        "address": "recipient@example.com"
      }
    ],
    "template": "AAABgUIbuG0AAAAE",
    "render": {
      "params": {
        "key": "value"
      }
    }
  }'

You can mix any regular properties that are valid for submission as well, e.g., "reference" or "replyTo".

Handlebars

EmailEngine supports Handlebars syntax in the templates. You have to set the "render" property with replacement parameters to use it.

Let's say your HTML content for the template looks like this:

<p>Hello {{params.name}}!</p>

Use the following "render" value to replace it:

"render": {
  "params": {
    "name": "John"
  }
}

Available values

• Use {{params.key_name}} for keys that are defined in the render.params object.
• Use {{account.key_name}} for sender account specific keys, for example {{account.name}} or {{account.email}}. These values are predefined and always available.
• Use {{service.key_name}} for EmailEngine specific values, for example {{service.url}} for the base URL of EmailEngine's instance.

Default values

Sometimes you do not have the required value for the template, e.g., the contact signed up with their email address only and did not provide a name. For these cases, you can use default substitution.

<p>Hello {{insert params.name "default=Customer"}}!</p>

In this case, if you have the name defined, the resulting message will look like this:

<p>Hello John!</p>

On the other hand, if it is not, then the resulting HTML code would look like this:

<p>Hello Customer!</p>

EmailEngine supports the Sendgrid flavored Handlebars as defined here.

Mail-merge

You can optionally send multiple emails with a single API call. Each recipient would get a separate message with only their address in the To: header, and you can optionally use recipient-specific templating variables.

The limitation is that you can not provide "to", "cc", and "bcc" fields when sending such an email.

To define the recipients, use "mailMerge" array. This value expects recipient objects with rendering options as array elements.

$ curl "http://tttt.localtest.me:3000/v1/account/example/submit" \ 
  -H "Authorization: Bearer <token>" \ 
  -H "Content-type: application/json" \ 
  -d '  {
    "from": {
      "name": "sender name",
      "address": "sender@example.com"
    },
    "template": "AAABgUIbuG0AAAAE",
    "mailMerge": [
      {
        "to": {
          "name": "recipient name 1",
          "address": "recipient1@example.com"
        },
        "params": {
          "name": "recipient name 1"
        }
      },
      {
        "to": {
          "name": "recipient name 2",
          "address": "recipient1@example.com"
        },
        "params": {
          "name": "recipient name 2"
        }
      }
    ]
  }'

When using such a request, each recipient would receive a customized email with their own name used in the template.