Custom Transactional Emails

Transactional emails are non-marketing messages which are sent in response to a customer action, or as the result of a standard process in your store.  These messages should be informational, and the send should be expected or understood by your customers.  Examples of transactional emails include password resets, purchase confirmation, payment failures, and shipping confirmation messages. 

With Cortex's custom transactional stage, your brand can now organize all of its email messaging through Cortex. 

Transactional email timeline

Transactional email initial setup

Create a custom transactional email

Using merge tags in a custom transactional email

Custom transactional email reporting

Transactional email timeline

1. A user visits your website or mobile app and makes a transaction, such as a purchase.
2. Your store or application will then use an API call to trigger a transactional email from Cortex.
3. In the API call, your store will send a "payload" of information. This will be used to identify the specific email to send and will include dynamic content for the email.
4. ReSci's API will trigger Cortex's transactional stage, which will build and send the email immediately. This entire process will typically take seconds to complete.

Transactional email initial setup

Before you begin: If you have not already set up your API key for transactional emails during onboarding, request an API key from help@retentionscience.com. The help team will provide further instructions for activation.

Developers on your team will need to build API calls that send to ReSci for each transactional email.  When it's time to send a transactional email, this API call will contain both the email information and dynamic content for the email.  Cortex's normal merge tags are not available in transactional emails.

Coordinate with your developer to make sure any content you need is available for your API call.  For example, a shipping confirmation may include the purchaser, shipping address, order ID, and ordered item names.  If you're not sure what content you will need, review your existing template or similar emails from other brands.

1. Give your developers a list of the data you need and the merge tags you will use. Do not use any of ReSci's reserved merge tag names.
2. Build your Custom Transactional email template, and include your merge tags.
3. Your developer will set up an API call for your email by following our documentation. They should test the API call thoroughly to ensure they are not getting any error responses.
4. After the template is complete and active, have your developer test the email using a payload of example data.
5. Important: Ensure you are passing an "accepts marketing flag" in any transactional emails that are potentially adding new users (such as an order confirmation). To be GDPR compliant, any forms that are collecting emails should also be collecting explicit consent to receive marketing. For more details, see our subscription options article.

Create a custom transactional email

1. Under the Cortex menu on the left, click Stages.
2. Select the "All Stages" tab.
   
   
   
   
3. Scroll to the bottom and select Custom Transactional in the Experiments section.
   
   
   
   
4. Click New email > Create new.
   
   

Follow these steps for setting up your new email.

Using merge tags in a custom transactional email

In transactional emails you will declare new merge tags for each specific email template. These merge tags are then filled with content included in the API call for each email.

Important: Ensure the tags you are using in your Custom Transactional emails are your own unique tags. Do not use any of ReSci's reserved merge tag names, since this can potentially cause issues, such as unexpected information being returned or the emails not sending.

When you are finished with your email, save and then send yourself a test send to ensure everything looks ok. Merge tags will not show true values, but will follow the example below:

Example email template and received test send:

In your transactional email, ensure all the merge tags used are present in the API call and spelled exactly the same as they appear in the email body.  For our example shown above, the body of the API call would need to appear in the following format:

{
"template_id": 256,
"email": "Johnny@retentionscience.com",
"merge_fields": {
 "first_name": "Johnny",
 "pass_reset_url": "https://www.supercoolbrand.com/accounts/reset/hjq23890fdasu"
}
}

Important: The transactional sends API has a rate limit of 25 requests/second. Please throttle your API calls accordingly.

Custom transactional email reporting

You can view the performance of your transactional emails in AI Stats, along with the rest of your campaign data.

Note: We already have a dedicated transactional "Welcome" stage to respond to account creations, which will work without needing your developer to set anything up, and you will not need to use the custom transactional stage. Simply use one of our integration partners, such as Privy, for email capture. Contact help@retentionscience.com for details.