This guide contains conceptual and procedural information that you can use in preparing to use the Engage API for triggered sending of emails via Automated Campaigns. It discusses API calls you can use to trigger automated emails created in advance via the Engage application. Detailed information on the Engage API and on specific endpoints can be found at https://api.questline.com.


What is a Triggered Email?

A triggered email is an email communication sent to a subscriber in response to a subscriber action or a system-generated event. For example, sending a confirmation message after a customer enrolls in a campaign or triggering an email notifying customers their electronic bills are ready to view, are both triggered emails.


What is an Automated Campaign?

An Engage Automated Campaign (formerly 'automated program') is a pre-defined set of automated actions or steps that can be triggered and performed on a particular subscriber. The actions are triggered simply by adding subscribers to the campaign. Possible action steps include sending emails, waiting a specified period of time, or updating subscriber attribute values. Automated Campaigns can be used for the most basic of tasks, such as triggering an email to a subscriber as well as more complex marketing automation tasks. In this guide, we will only discuss the basic functionality of Automated Campaigns necessary for triggered emails.


Automated Campaign Setup

The initial setup of the email content, email from/reply to name and address, and series frequency is handled by Questline based on your company’s need and product level. After all this is set up, you will be able to trigger Automated emails via the Engage API. Once a Campaign has been created, details on the campaign, including the required AutomatedCampaignId, can be retrieved via:

GET v3/automatedcampaigns
GET v3/automatedcampaigns/{automatedCampaignId}

The first of these gets a list of all Automated Campaigns on your account. The second, when used with the ID of a specific Automated Campaign, gets a list of the steps within the campaign.


Multi-pass Automated Campaigns

By default, Automated Campaigns in Engage do not allow an individual subscriber to pass through the campaign multiple times. This ensures a subscriber is not accidentally sent duplicate emails or taken through complex marketing automation campaigns repeatedly. However, in some triggered sending scenarios, you may intend for the subscriber to pass through the campaign multiple times. A billing notification message that the subscriber receives each month is a good example of this. To allow a subscriber to receive multiple messages from a campaign over time, the Multi-pass option must be enabled via the Engage application when creating the campaign.


Including Dynamic Personalization Data in Email Content

Engage dynamic scripting can be used to include personalized information within an email on a subscriber-by-subscriber basis. This is useful in cases where subscriber attribute values must be included in the outgoing email and is often used to personalize the content with information such as the customer’s name, a subscriber-specific link, or a portion of the subscriber’s account number.


First-level subscriber properties

First-level subscriber properties such as Firstname, Lastname, and Email can be referenced in your email content using the following syntax.

|*Subscriber.Firstname*|


Subscriber attributes

Subscriber attribute information can be referenced using the following:

|*Subscriber.Attributes.AccountNumber*|

In this example, AccountNumber is a custom attribute previously created to hold Susbcriber data.


Conditional statements

"If" statements can also be used to check the value of an attribute and adjust the output accordingly. For example, you can check whether a subscriber has a first name recorded, and either display it in the email, or use an alternative greeting if it is blank. The following syntax can be used for this:

|* if Subscriber.Firstname <> "" *|    
    |*Subscriber.Firstname*|
|* else *|    
    Dear Valued Customer,
|* endif *|


Additional details on Engage dynamic scripting capabilities and syntax can be found in this section of the Questline help portal.


Triggered Email Send Process

The following diagram illustrates the process for an email already created via the Engage application.



 


Create a Subscriber

Prior to adding a new subscriber to a campaign, the subscriber must be created or updated in the Engage system. Add subscribers to Engage by using the following endpoint:

POST v3/subscribers


This endpoint allows for the inclusion of strings to create subscriber values such as the Subscriber Key, email address, SMS or fax numbers, first name, last name, and attributes.


Update Subscriber Attribute Information

Subscriber attributes allow you to define your own metadata for individual subscribers (for example, address information such as city, state, zip code). Attribute data can then be used for segmentation and personalization of email content. In the case of a triggered email, it is often the case that you will want to include dynamic content representing the subscriber’s address, billing date, account number, and more. To do this, use the following endpoint and create or update attributes with the desired name and value for each subscriber:

PUT v3/subscribers/{subscriberId}


Add a Subscriber to an Automated Campaign

Once a subscriber exists in the system and has been updated with proper attribute data, they can be added to the pre-defined Automated Campaign. Adding a subscriber to the Automated Campaign will trigger the first automation step in that campaign. In the Body of the request, place the proper AutomatedCampaignID.

POST v3/subscribers/{subscriberId}/automatedcampaigns


Retrieve Behavioral Events

After a subscriber is sent an email, the Engage system will begin recording any behavioral events associated with the send. This includes send events, bounces, opens, and clicks.

Retrieve all events for an automated campaign or campaign Send Email step with the following endpoint:

GET v3/automatedcampaigns/{automatedCampaignId}/events
GET v3/automatedcampaigns/{automatedCampaignId}/steps/{automatedCampaignStepId}/events


 Or retrieve events for an individual subscriber using the following endpoint:

GET v3/subscribers/{subscriberId}/events