Below is a description of how you can capture content for an email message at the point of interaction with your customer. This means that you do not have to reference the Emarsys (or any other) database before you trigger the email.

If you do want to update the Emarsys database with this content, you will have to do that in a separate call after the email has been triggered.

Contents

An example API call

Here is an example for a JSON payload that can be used to trigger external events.

    {
     "key_id": "3",
     "external_id": "test@example.com",
     "data":
     {
      "global":
      {
       "itemName": "keyboard",
       "itemPrice": "123",
       "<placeholder_name>": "<placeholder_value>",
       …
      }
     }
   }

Passing data with the API call

This section explains the various ways you can work with the data parameter.

JSON transmits data as <placeholder>:<value> pairs. Wherever the placeholder is located in the email, the corresponding value is substituted.

These pairs are grouped in one of two ways, in an object or in an array. An object defines where in the email to apply them (i.e. globally or only in a particular section), by grouping them in a set of curly brackets: { }. There are two levels of objects:

  • The first-level objects – These are the "global" object, which contains only "placeholder:value" pairs and applies to the entire email, and those for the section external identifiers, which contain an array of second-level objects and apply only to that specific section.
  • The second-level objects – These are contained within the arrays of the section external identifiers and contain more "placeholder:value" pairs.

First-level objects can only occur once in the JSON. If they are repeated, the values in the last object will overwrite those from the earlier ones. Here is an example of a JSON API call containing just two first-level objects and one second-level object:

    "data": {
     {
      "global": {
       "header": "default header",
       "item": "default item"
      },
      "single_section": [
       {
        "header": "sample header",
        "item": "sample item"
       }
      ]
     }
    }

The advantage of placing the placeholder pairs in an array for the second object is that their values can ignore the global values. This means that you can define different values for the same placeholder in different sections.

Here is an example of another API call which contains multiple second-level objects inside an array:

    "data": {
     {
      "global": {
       "header": "default header",
       "item": "default item"
      },
      "repeating_section": [
       {
        "header": "Header 1",
        "item": "Item 1"
       },
       {
        "header": "Header 2",
        "item": "Item 2"
       }
      ]
     }
    }

In this case, Emarsys will repeat the section with the external identifier "repeating_section" as many times as there are objects within that array. In this way, for example, you can add as many products as you like to an email without having to create a separate section for each one.

About the placeholders and their values

The placeholders are added to the email using the format: %%placeholder_name%%. This applies both to custom HTML and template-based emails. You can give them whatever name you like but can only use standard (latin1) alphanumeric characters (a-z, A-Z) and the underscore ( _ ). You cannot use blank spaces. The same character restrictions apply to the section external identifiers.

It is therefore important for customers who work in UTF-8 environments and use other character sets that the placeholders and identifiers must be formatted correctly, otherwise this feature will not work.

The values that are returned by the JSON object may be encoded in UTF-8 without a problem. Depending on whether you are using a custom-HTML or template-based email, these values may also contain HTML formatting (see below).

If a placeholder exists in an email but does not exist in the JSON object, it will be displayed as plain text in the email (e.g. ‘%%placeholder%%’). However, you can give an empty string as a value, in which case the placeholder will effectively be stripped out.

There are also some system placeholders which can be used in the JSON, but are not included in the sections themselves. These start with an underscore, e.g. the _url placeholder in the example above. These can be used to overwrite the default image or link in a section (see Testing the email in the preview).

Custom-HTML vs template-based emails

The placeholders can be used in both custom-HTML and template-based emails.

In custom HTML there are certain limitations, namely:

  • You can only use a single JSON object (the "global"), containing just "placeholder:value" pairs. These pairs should not be repeated in the object, otherwise the final pair will overwrite the previous instances.
  • You cannot use any arrays. If the JSON contains an array, this feature will not work and the content will not be added to the email.

However, there is also a major advantage, in that you can include an entire HTML block in one single value, which will be inserted whole into the placeholder. This means that you can display a table with product information for multiple products in the same way that the sections in a template can be duplicated (i.e. add the required number of rows with content to the table in the HTML code).

In template-based campaigns you can use placeholders in both advanced and standard mode. The main differences to custom-HTML emails are:

  • You can use arrays to duplicate sections.
  • You can apply different values to the same placeholder in different sections.

Because the functionality for template-based campaigns is so much more extensive than for custom-HTML campaigns, the rest of this document will refer only to them.