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
Transactional | Commercial |
|
|
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
Developer
|
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
- Go to Content > Catalog
- Select a template from the Messages tab and click Download
- Click Edit Template
OR
Go to Content > Email Templates to find your downloaded template - Hover over your new template in the Default Folder and click Edit
- Use the Email Composer to set up and design your Event-Based Email
- 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
- Click Save
- Use this template when creating and sending your new ETE
Reuse an existing email template
- Go to Content > Email Templates
- Hover over an existing template and click Edit
- In the Email Composer, go to the General tab
- Under Event Based Email, select Make this Template available in API calls
- Click Save
- 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:
- Go to the General tab of the Message Composer and find the Template ID on the right column.
-
Click Send to Developer
- This button will also appear when you save your template
- On the next screen, enter your developer's email address (please check your spelling)
- Under Note, you can provide any additional context that the developer might need for them to code, including any explanations for Personalization fields
-
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)
- 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
Requirement | Details |
OAuth Access Token |
|
Account ID |
|
Template ID |
|
EmailDetails |
|
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:
envelope |
Contains fields needed to address the message. |
toAddress |
Required – The email address that the message will be sent to. |
ccAddressList |
Optional – The list of email addresses that will be carbon copied on this email. Limited to five. |
fromAddress |
Optional – Default fromAddress is the address selected in the template composer. If one was not selected, the email address of the logged-in user who saved the template will be used. The account sending this email must have permission to use the address. |
fromDisplayName |
Optional – Display name of the sender. If nothing is provided, this will default to the name associated with the above fromAddress. |
replyToAddress |
Optional – Replies to your message will be sent to this address. Defaults to the above fromAddress. |
content |
Contains fields needed to prepare the message's content. |
subjectLine |
Optional – The subject line of your email message. Defaults to the subject line set in the template. Limited to 90 characters. |
personalizationDataMap |
Required (when your message template has personalization fields) – A key/value map of message personalization data. The keys are the personalization fields specified in the template and the values are strings to replace them. In the example above, the message template has personalization keys orderNumber, trackingLink, and name. |
previewText |
Optional – The email's preview text. This appears next to the subject line in the recipient's inbox. Defaults to the preview text in the template. Limited to 240 characters. |
metadata |
Contains metadata about the message. This metadata is not sent with the message. |
transactional |
Required – True or false. True indicates that your message conforms to the legal definition of transactional email. Contacts who have opted-out of your marketing mail or marked your past mail as spam will still receive this message. Your account must have purchased transactional sending to send transactional email. |
externalId |
Required – This field allows you to provide an identifier from your system to identify the email message sent via this API call. An example would be an order number from an online store or a confirmation number from an online booking system. We will store this identifier as part of the record of your sent message. Limited to 128 characters. |
tagList |
Optional – This field allows you to tag this message with a label. With tagging, you can view reports of similarly labeled messages for a given template. For example, you use the same template to send both order confirmation and shipping confirmation messages, but tag them with "order_confirmation" and "shipping_confirmation" so that you can view reporting on them separately. Maximum length of 48 characters. Only one tag allowed per message at this time. |
actions |
Contains fields instructing the Event Triggered Email service on how to process this send. |
trackOpens |
Optional – True or false. True indicates that this message should attempt to track message opens. Defaults to true. |
trackClicks |
Optional – True or false. True indicates that this message has links that should be replaced with click tracking links. Click tracking links record the click and write a tracking cookie before redirecting the recipient to your original URL. Defaults to true. |
deliveryWhenDelayed |
Ignored – One of TRUE, FALSE, or FIVE_MINUTES. This field is currently ignored. |