Using Act-On's Event-Triggered Email API

  • Updated

Event-Triggered Email connects your application to Act-On’s email delivery engine so you can send real-time transactional or commercial messages on demand. Marketers design reusable templates in the Email Composer, and developers trigger each send through the API with the required personalization values.

You can use the API for messages that must be sent immediately in response to an event (for example, a password reset or booking confirmation), whether they are transactional or commercial, by setting the correct parameter in your request.

Quick Reference – Using Event-Triggered Email (ETE)

Marketer / Act-On user

  • Design or reuse an Email Template in the Email Composer.
  • Add clear, self-explanatory Personalization fields that your developer will populate via the API.
  • In Settings > Event Triggered Email, select Make this template available in API calls.
  • Use Send API details to Developer to share the Template ID, example payload, and notes.

Developer

  • Obtain an OAuth access token, the Account ID, and the Template ID.
  • Send a POST request to the ETE endpoint with an EmailDetails JSON payload.
  • Provide all required personalizationDataMap keys expected by the template.
  • Set metadata.transactional correctly (true for transactional, false for commercial) to comply with your sending use case.

For REST API reference, see the Event-Triggered Email endpoint documentation.

Use Cases

Event-Triggered Email is intended for one-to-one messages that are sent as a direct result of an event or transaction, rather than part of a bulk marketing campaign.

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 main workflows for using the Event-Triggered Email API: the Marketer / Act-On user workflow and the Developer workflow. Both roles work together to ensure the template is designed correctly and the API calls are made with the right data.

Marketer / Act-On User

  • Create an email template and save it as an Event-Triggered Email (ETE) API email.
  • Define clear, self-explanatory Personalization fields for the developer to use in their API calls. Important: Once shared with the developer, these keys should not be changed.
  • Modify the default footer if needed to include an opt-out link in commercial emails (opt-out links are not needed for transactional emails).
  • Save the template and send its details (including Template ID and personalization keys) to your developer.
  • You can finalize personalization keys and send them to your developer before you complete the rest of the email copy and formatting.

Developer

  • Ensure that all Personalizations used in the template are specified in the personalizationDataMap when calling the API.
  • Respect the cap of 20 transactions per second. If your system can exceed this, throttle requests or handle retries when throttling responses are returned.
 Screen_Shot_2022-05-18_at_3.00.32_PM.png

Event-Triggered Email Templates

What Makes a Good Template?

Event-Triggered Email (ETE) is intentionally flexible so you can support many different use cases. However, a few best practices will make your templates easier and safer to use with the API.

Make Personalizations Clear for Your Developers

Because ETE personalizations are supplied by your application (not a Marketing List), it’s important to make each Personalization field name self-explanatory. This reduces back-and-forth and helps ensure the correct data is passed in every API call.

Example: You’re working on a hotel confirmation email where the template’s input will be a billing confirmation. You want the developer to add a confirmation table with taxes, rates, HTML formatting, and a total.

Instead of using a generic personalization like {{confirmation}}, you could use a more explicit key such as {{html formatted confirmation table with total}}. This helps your developer understand exactly what data and formatting should be included in the personalization value.

Know Your Personalization Data Source

Personalizations for Event-Triggered Emails do not have access to list or account data. For example, when sending a standard email via the Act-On website, a personalization like {{First Name}} can be supplied from an Act-On Marketing List. When sending an ETE via the API, however, the application calling the API must provide the value for {{First Name}}.

As in the example above, we recommend specifying an alternative text when using Personalizations in case some details are missing, for example: {{={{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 Event-Triggered Email.

Create a New Email Template

  1. Go to Content > Catalog.
  2. On the Messages tab, select a template 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-Triggered Email. Add any Personalization fields that the API should populate.
  6. 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.

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, 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.

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

Send Template Details to Your Developer

After your template is ready, send your developer the information they need to call the Event-Triggered Email API using that template.

  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), and ensure Make this template available for API calls is enabled.
  3. Click Send API details to Developer.
  4. Enter your developer's email address (double-check the spelling).
  5. Under Note, provide any additional context that the developer might need, including explanations for Personalization fields and how you intend to use this template.
  6. Under Email payload (JSON), click Show more to view a formatted payload. This is useful if you or your developer want to see the structure of the data to send.
    • Click Copy to manually send API details to your developer. (This does not copy the note text above.)
  7. Click Send for Act-On to email these API details directly to your developer.

Using Act-On's Event-Triggered Email API 02.png

Developer Resources

Using the REST API

The Basics

API calls to send an Event-Triggered Email are made via an HTTP POST request to the 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 the API via our gateway in the EU can use:

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 Act-On Account ID
  • The Template ID of the email template to use for your ETE
  • The EmailDetails JSON payload for your message
Requirement Details
OAuth Access Token

  1. Use a curl request to generate an access_token using the same process as for our currently published APIs, documented here.

    For Act-On admins only, the API Access Keys for ETE are here: Settings > Other Settings > Custom Account Settings > API Access Keys.
  2. Pass this access_token in the Authorization header via the Authorization HTTP header. Select OAuth 2.0 as the authorization type.
Account ID
  • Your Act-On Account ID.
Template ID
  • This is the Template ID generated when you save an Event-Triggered Email template marked as available for API calls.
  • See above for more information on enabling a template for ETE.
EmailDetails
  • This is the POST body for the request. It provides the data needed to turn your email template into a message. The content type is application/json.

The Details

The body of the POST request is an EmailDetails JSON object. It is composed of four sections: envelope, content, metadata, and actions.

The following tables describe each section and field:

envelope Contains fields needed to address the message.
toAddress Required – The email address that the message will be sent to.
ccAddressList Optional – A list of email addresses to be carbon copied on this email. Limited to five.
fromAddress Optional – Defaults to the address selected in the template composer. If none was 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 this address.
fromDisplayName Optional – Display name of the sender. If nothing is provided, this defaults to the name associated with the fromAddress.
replyToAddress Optional – Replies to your message will be sent to this address. Defaults to the 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 payload, the message template has keys such as 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 (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 marketing mail or marked past mail as spam will still receive this message. Your account must have purchased transactional sending to send transactional emails.
externalId Required – An identifier from your system to identify the email message sent via this API call (for example, an order number or booking confirmation). This identifier is stored with the record of your sent message. Limited to 128 characters.
tagList Optional – A label used to tag the message. With tagging, you can view reports of similarly labeled messages for a given template. For example, use the same template for both order and shipping confirmations, but tag them with order_confirmation and shipping_confirmation to report on them separately. Maximum length of 48 characters. Only one tag is allowed per message at this time.

 

actions Contains fields instructing the Event-Triggered Email service how to process this send.
trackOpens Optional – true or false. true indicates that this message should attempt to track opens. Defaults to true.
trackClicks Optional – true or false. true indicates that this message has links that should be replaced with click-tracking links. These 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