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 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 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 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. Use the Email Composer to set up and design your Event-Based Email
6. Before saving, make sure that your template is available for API calls:
   • Go to the General tab
   • Under Event Based Email, select Make this Template available in API calls
7. Click Save
8. Use this template when creating and sending your new ETE

Reuse an existing email template

1. Go to Content > Email Templates
2. Hover over an existing template and click Edit
3. In the Email Composer, go to the General tab
4. Under Event Based Email, select Make this Template available in API calls
5. Click Save
6. Use this template when creating and sending your new ETE

Send Template Details to Your Developer

You can send your developer the information they'll need to use the Event-Triggered Email template via an API. To do this:

1. Go to the General tab of the Message Composer and find the Template ID on the right column.
2. Click Send to Developer
   • This button will also appear when you save your template
3. On the next screen, enter your developer's email address (please check your spelling)
4. Under Note, you can provide any additional context that the developer might need for them to code, including any explanations for Personalization fields
5. Click Show message details for a formatted payload if you or your developer would like to see the details of the package they need to send
   • Click copy code to clipboard to copy and manually send API details to your developer (this will not copy any notes from the Note field)
6. 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://restapi.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: