Event-Triggered Email is a service for sending email to a recipient in response to a specific event or transaction (and not as part of a bulk marketing campaign). You can use the API for transactional or commercial messages that need to be immediately sent by using the correct parameter.

Use Cases

Workflows

There are two workflows for using Event-Triggered Email API: the Marketer/Act-On User’s workflow and the Developer's workflow. See the below diagram for more information about each of these workflows:

Marketer/Act-On User Creating a template and Saving it as an ETE Email API email Creating the personalizations for the developer to use in their Call to Act-On (Once sent to the developer these should not be changed!) Modify Default Footer if needed to include an opt-out link in commercial emails (opt-out link not needed for transactional emails) Saving and Sending the details to the developer for use. Note: You can make the personalizations as you want them, and send them right away before working on the rest of the copy/formatting Developer All Personalizations must be specified in the call There is a cap of 20 Transactions Per Second, make sure to throttle the incoming calls if your system can bypass that to throttle messages or be ready to retry once a retry message is received

Event Trigged Email Templates

What Makes a Good Template?

Event-Triggered Email (ETE) was intentionally made to facilitate a variety of use cases. That said, there are a few things that can make an ETE template easier to use. 

Make Personalizations Clear For Your Developers  

Since you're not bound by the data in a marketing list (and instead are asking for information from developers), making your email's Personalization fields self-explanatory will help facilitate the hand-off. 

Example: You're working on a hotel confirmation email, where the template's input will be a bill confirmation. You want the developer to add a confirmation table with taxes and rates, including HTML formatting, pricing, and a total. Instead of using {{confirmation}} for your email template's personalization, you can use a more robust and specific personalization like  {{html formatted confirmation table with total}} to help the developers know exactly what to pull into the personalization value.

Know Your Personalization Data Source

Personalizations for Event-Triggered Emails do not have access to list or account data. For example, if the existing Email Template references {{First Name}} when sending email via the Act-On website, the recipient's first name will be supplied from the associated Act-On Marketing List. However, when sending an Event-Triggered Email via the API, the application calling the API must provide the value {{First Name}}.

As above, we recommend specifying an alternative text when using Personalizations in the event that some details are missing, e.g. {{={{First Name}},|Valued Customer}}.

Creating an Event-Triggered Email Template

You can create a new email template from the Act-On Content Catalog or reuse one of your existing email templates for your Event-Triggered Email.

Create a New Email Template

1. Go to Content > Catalog.
2. Select a template from the Messages tab and click Download.
3. Click Edit Template.
   OR
   Go to Content > Email Templates to find your downloaded template.
4. Hover over your new template in the Default Folder and click  Edit.
5. Set up and design your Event-Based Email.
6. To make sure that your template is available for API calls, in the Settings tab under Event Triggered Email, select Make this Template available in API calls.

Use this template when creating and sending your new ETE.

Reuse an Existing Email Template

1. Go to Content > Email Templates, hover over the email template you want, and click  Edit.
2. In the Email Composer, go to the Settings tab (the General tab for legacy emails).
3. Under Event Triggered Email (on the right), select Make this Template available in API calls.

Use this template when creating and sending your new ETE.

Send Template Details to Your Developer

Send your developer the information needed to use the Event-Triggered Email template via an API. To do this:

1. Go to Content > Email Templates, hover over an existing template, and click  Edit.
2. To find the Template ID, go to the Settings tab (the General tab for legacy emails), & open Event Triggered Email (on the right), & ensure Make this template available for API calls is enabled.
3. Click Send API details to Developer.
4. Enter your developer's email address (please check your spelling).
5. Under Note, provide any additional context that the developer might need for them to code, including any explanations for Personalization fields:
6. Under Email payload (JSON) click Show more for a formatted payload if you or your developer would like to see the details of the package they need to send
   • Copy to manually send API details to your developer. This does not copy the notes above.
7. Click Send for Act-On to send these API details to your developer:

Developer Resources

Using the REST API

The Basics

API calls to send an email are made via an HTTP POST request to our Event-Triggered Email endpoint. The URL for making these requests is:

https://api.actonsoftware.com/ete/v1/email/{Account ID}/{Template ID}

Customers wanting to access our API via our gateway in the EU can use this link: 

https://api-eu.actonsoftware.com/ete/v1/email/{Account ID}/{Template ID}

There are four pieces of information that you must provide to call this endpoint:

• An OAuth access token for authenticating your request
• Your Account ID
• The ID of the email template to use for your ETE
• The EmailDetails for your message

The Details

The body of the POST request is an EmailDetails JSON object. EmailDetails is composed of four sections: Envelope, Content, Metadata, and Actions. Let's look at an example payload and then what each field means: