The Emarsys API provides easy and scalable functionality for setting up and launching time-critical and other triggered messages.

Contents

Introduction

A triggered message is a single message sent to a single recipient, which relates to a specific interaction (or transaction) between the recipient and the sender. It can be triggered by either party: the recipient typically triggers it via an action performed on a web page (e.g. a purchase or registration, password reset) and the sender typically triggers it by updating a database field (e.g. shipping confirmation).

In many cases a triggered message does not require an opt-in from the recipient, and consequently such messages may only contain information that is directly relevant to the original interaction.

Using the API to Trigger Messages

You can trigger messages via the External event endpoints.

Once these have been created and set up, you can link them to email, SMS and Mobile Engage messages, usually via an Automation Center program.

In the Automation Center you create programs with the entry point External event. When your API call matches a contact ID to the external event of the program, the contact enters the program and progresses along it according to the defined workflow.

The advantage of this type of message is that it can be the start of a more complex process, such as a new lead welcome program. You can also use the program summary function to track contact responses through the programs, and use the API to return email response data.

Note: The same external event can be used to trigger an On External Event email campaign as well as an Automation Center program. There is no exclusivity check between the two features, which means you can trigger a program and send an external event email at the same time. This may be desired behavior; this is just an advisory note.

Triggered programs are set up as follows:

  1. Create an external event in the B2C Cloud.
  2. Create the program in the Automation Center.
  3. Create the API call to match the contact to the program.

Creating the external event

To create an external source, go to the Automation menu, External Events. Here you can simply add a new source to the list.

The sources you create here are the connectors which link the contact to the email. They are available in the Automation Center for selection as the program entry points, and also as trigger events in API calls. You should therefore try to give them intuitive names that are easily understandable. Emarsys will assign each one a unique ID.

Creating the transactional program

To create the transactional program, you only need to select External Event as the entry point. The rest of the program can contain whatever actions or responses you want. In the External Event node, you select the source that you created in the External Events page as described above.

An external event may only be used by one program at any one time.

Creating the API call

When you have your transactional program set up, you will need an API call containing the Event and Trigger methods.

Once this call has been set up, and the program is active, every time a contact interacts with the API call, they will immediately enter the program. However, this is all that happens; the contact is matched to the program and no other data is transmitted. To include transaction-specific content in the API call you must set up a different type of email. See: Capturing Transactional Content.