Using Act-On's Event-Triggered Email API

  • Updated

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
  • Password reset
  • Fraud alert
  • Hotel booking confirmation
  • Account sign-up (introductory, password)
  • Form auto-responder
  • Webinar Reminders
  • Quarterly or annual financial filing information for investors
  • Unsubscribe confirmations
  • Subscription, double opt-in, or account creation confirmations
  • Purchase receipt emails
  • Account notification emails - security breach, completed in-app jobs/events, permission or activity changes, usage summary
  • Abandoned shopping cart reminder
  • Anniversary offers
  • Time-sensitive promotions
  • Product Recommendations
  • Website Browsing Remarketing
  • Loyalty Program Messaging
  • Personalized Digest Emails

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
Screen_Shot_2022-05-18_at_3.00.32_PM.png

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
Need more help creating and editing your email template? See our Email Composer User Guide.

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

Screen_Shot_2022-05-18_at_3.09.48_PM.png

Heads up! Reused email templates will carry over any existing list-based Personalizations. However, when sending an Event-Triggered Email (Transactional or Commercial Email) via the API, the application calling the API must provide the value used to replace the existing personalization. See our above recommendation for best practices related to ETE personalization.

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 templateScreen_Shot_2022-05-18_at_3.14.50_PM.png
  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 fieldsScreen_Shot_2022-05-18_at_3.14.59_PM.png
  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
    Screen_Shot_2022-05-18_at_3.15.10_PM.png

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
  • Requests to the Event-Triggered Email service require an access token be passed via the "Authorization" HTTP header.
  • The process for obtaining and refreshing an access token is the same as that for our currently published APIs. These are documented in detail here.
    Your API Access Keys for ETE can be found in your Act-On Account under Settings > Other Settings > Custom Account Settings > API Access Keys.
Account ID
  • Your Act-On Account ID.
Template ID
  • This is the template ID that is generated when you save an Event-Based Email template marked as available for API calls.
  • See above for more information.
EmailDetails
  • This is the POST body for the request. It provides the data needed to turn your email template into an email message. The content-type is application/json.


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:

Screen_Shot_2022-05-18_at_3.24.32_PM.png

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. 

 

Was this article helpful?

Have more questions? Submit a request