There are many occasions when you want to trigger an email without the need to reference the contact (or any other) database, because all the content required in the email can be captured at the point of interaction that triggers it.

Contents

Introduction

Triggered emails with transaction-specific content are not part of the Automation Center but are individual on-event emails of the type On External Event. These types of emails contain two important functions which greatly improve the workflow of users when setting up transactional emails:

  • Content can be pulled from the transaction sent directly via the API and inserted via placeholders
  • Dummy sections can be created which are set to duplicate

This second point means that you do not need to know how products are involved in the transaction, for example, as the section is repeated as many times as its content appears in the API call.

This means that transactional emails can be created from integrated applications such as Magento and sent with content from that application, without that content ever having to be stored by Emarsys.

The following transaction-specific content can be contained in the API call:

  • Plain text, to be inserted anywhere in the email via the placeholders.
  • A link URL, to overwrite the section link (template-based emails only).
  • An image URL, to replace the section image with an externally-hosted one (template-based emails only).

Please note that the launch time for of this sort of email can be affected by the number of sections which have to be created.

Creating an On External Event email

Create your email and set the Recipient source to Generated through an event. Then select On External Event and below that select the event that will trigger the email.

Suite_API_Transactional_Page_07_Image_0002

Once you have set up the framework of the email you can decide which sections you want to contain the transaction-specific content. For each of these sections you must enter an external identifier.

Suite_API_Transactional_Page_07_Image_0003

The external identifier is used to create a new JSON object for this section. If multiple sections use the same identifier, then their placeholders will all have the same values. You can now add the placeholders and place them wherever you want in the email.

You can add a placeholder wherever text input is possible, for example in the section header, body text, link name, image name and the alternative text for images.

Testing the email in the preview

Once you have created the email with all the static content and all the placeholders for the dynamic content, you can test how this will look in the preview.

In the example below, an email has been created with three section groups:

Suite_API_Transactional_Page_08_Image_0002

An example dummy repeating section

  • Recommended products – This contains one dummy section which will repeat to display all the recommendations for the contact. It contains an external identifier, as well as placeholders for the name, price and description of the recommended products.

Suite_API_Transactional_Page_08_Image_0003

One of two static sections for special offers

  • Special offers – These are two fixed sections which will display special offers for that day. They also contain external identifiers, and details of the products on special offer at the time.

  • Images – There are three fixed sections which display the images of the day. The preview for this email looks like this:

Suite API Transactional Page 09 Image 0002.png

The three images below can be replaced by using the system placeholders, and can display additional products according to whatever recommendation system you are using on your side.

When you click Edit Placeholders (a new button on the top right of the pop-up), you can see all of the email content which can be added via the API. Sample values are provided for all placeholders by Emarsys.

Suite API Transactional Page 10 Image 0002.png>

This pop-up has the following information and controls:

  • Global placeholders
    These are placeholders that are present in more than one section. The values defined here will be used if the checkbox Use global is checked for a placeholder or if no alternative values are defined.
  • Section placeholders
    These are the placeholders in each section, as entered by you.
  • System placeholders
    Placeholders which begin with an underscore, e.g. _url_name, are system placeholders which can be used to overwrite the section image and link. In this way you can link to an external image for each section and change these images whenever you like. These placeholders are not used in the section itself, but can be added to the JSON if you want to replace the values in the section.

Note: If you use an external link to overwrite the section link, this does not use the Emarsys link redirect function and therefore these links cannot be tracked. Furthermore, if you use external images, these are not uploaded to the Emarsys Media Database and therefore Emarsys has no control over how they are displayed.

  • Use global
    If a section contains a global placeholder, you can use this checkbox to take the global value, or leave it empty and manually define a different value.
  • Use section default
    This checkbox defines whether a system placeholder takes the section default link or image, or uses an external one.
  • Duplicate section (+)
    This icon duplicates the section so that you can test how this will look with multiple entries.
  • Show JSON
    This button creates a JSON object for the section according to the way you have previewed it. This can be copied and passed on to your API developer to give them an idea of the way you want your API call structured.

Following the above example, we have entered some test values to our preview and repeated the recommended products section (1). One special offer has a defined value (2), the other is set to take the global values (3):

Suite API Transactional Page 12 Image 0002.png

The email preview now shows the new values for the recommended products and special offers:

Suite API Transactional Page 13 Image 0002.png

If you click the Show JSON button in the Edit Placeholders dialog, you will get the corresponding code example:

Suite API Transactional Page 13 Image 0003.png

Note the single "global" object containing all the other data, and the arrays for each section. At the bottom I have manually added another object to the "recommended_products" array. This would create a third such section in the email.

This JSON viewer is very useful for Emarsys users to be able to pass over a detailed description of how they want their content supplied by the API. You can copy and paste the example into an email for your developer to use as the basis of the API calls.

Activating the email

Emails with transaction-specific content are activated like any other on-event email. In the Scheduling page the delay is specified (if so desired), the personalization variables are checked and the email is activated.

Note: As described above, the personalization variables can only be in the permanent section content and not in the JSON object.

Setting up the API Call

Once the email has been tested and activated, you need to set up the API call to provide the contact ID, email ID and the requisite content. See: Capturing Transactional Content. Once this is done, the email is ready and will trigger to every contact that is returned by the API call.