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.

Email Lists

Mail-merge emails can be sent out as list emails by setting a listId property to the email structure. The listId value must look like a domain name, and the receivers will identify emails with the same listId as coming from the same mailing list.

If listId is set, then EmailEngine adds common mailing list headers, including the one-click unsubscribe link that email clients can use to identify mailing list emails and provide the one-click "unsubscribe" button.

Read more about virtual mailing lists from here