The following guide will provide instructions to integrate with our REST API to send transactional emails.

Examples of transactional emails include:

  • Order confirmation

  • Shipping confirmation

  • Password reset


Anatomy of Transactional Emails in Listrak

There are 2 primary components for transactional emails in Listrak.

  1. Email template

  2. Your transactional service

Email Template

Typically, transactional emails will be built on a list separate from your master marketing list.

A new transactional email can be create by:

Authoring > Transactional Messages > Create Message.

This will create an email that can be triggered by your transactional service using our REST API.

💡 If you are onboarding with the Professional Services team, the emails included in the scope of your project will be created by the Professional Services team on your behalf.

Fixed Data

The email template in Listrak will contain all of the fixed data such as the header/footer, titles, and other design components that are not dynamic.

Dynamic Data

Additionally, profile fields are used as placeholders for the dynamic user data that needs to be populated by your transactional service.

Order numbers, other order details, and the customer's name are examples of dynamic user data.

💡 If you are onboarding with the Professional Services team, a template will be built by our designers for each of your transactional emails included in the scope of your project.

Your Transactional Service

Your transactional service will handle triggering the email and providing the dynamic data that will populate the placeholders in the email template.

Click here to view our full REST API documentation.

Sending a transactional messages utilizes 2 endpoints.

  1. OAuth 2.0 Authenticaton

  2. Send a TransactionalMessage

OAuth 2.0 Authentication

Our REST API utilizes Bearer tokens to authenticate your requests. Prior to triggering a transactional message, first authenticate using your API integration credentials so you can include the Bearer token in your send request.

If you do not have API integration credentials yet, follow these steps.

Manage > Integrations > New Integration > Email API > Setup Integration

Send a TransactionalMessage

Your request body will use the following format.

{
"emailAddress": "john@example.com",
"segmentationFieldValues": [
{
"segmentationFieldId": 5101, // Order Number
"value": "1004827"
},
{
"segmentationFieldId": 5102, // Order Total
"value": "52.95"
},
{
"segmentationFieldId": 5103, // Customer First Name
"value": "John"
}
]
}

To access your segmentationFieldIDs (profile field IDs), navigate to:

Support > API > API ID Information

The Field IDs section will outline the API IDs for the profile fields that may be used in the email template. Note that this API IDs will not change unless the field is deleted and recreated.

💡 If you are onboarding with the Professional Services team, confirm with your Listrak Project Manager which fields will be used in each email.

The profile fields must be referenced by API ID as we cannot parse the data using key names.

Order Items

If the email displays a repeating portion of dynamic length such as the customer's order items in an Order Confirmation email, that data must be sent to us as escaped HTML.

💡 If you are onboarding with the Professional Services team, a template for this will be built by our designers for each of your transactional emails included in the scope of your project that require it.

This is an example template for the order items section in an Order Confirmation email.

<!-- Item -->
<table width="100%" cellpadding="0" cellspacing="0" border="0" role="presentation">
<tr>
<td class="pad-lr-10" style="">
<table class="stack" width="100%" cellpadding="0" cellspacing="0" border="0" role="presentation">
<tr>
<th class="cart-img pad-t-10" align="center" width="140" style="width:151px;">
<img src="{Product Image}" width="140" border="0" style="display:block;">
</th>
<th class="center pad-t-10 pad-l-0 full-width" width="111" align="center" style="font-family:Georgia, Times, 'Times New Roman', serif; font-size:16px; line-height:20px; color:#402020; text-align:left; width:111px; padding-left:15px;">
{Title}
<br>
QTY {#}
</th>
<th class="center pad-l-0 pad-b-30 full-width" width="199" align="center" style="font-family:Georgia, Times, 'Times New Roman', serif; font-size:16px; line-height:20px; color:#402020; text-align:left; width:199px; padding: 0 0 0 30px;">{Price}
</th>
</tr>
</table>
</td>
</tr>
</table>
<!-- Item END -->

<!-- Place Next Item Here -->

Your transactional service should repeat the item block for each item in the order, populate the product data where { } are placed, escape the HTML, and send it through a segmentationFieldID in the request body.


Testing

Testing the email itself can be done in Listrak within the authoring tool by clicking the 'SEND TEST' button at the bottom of the authoring page. The application will prompt you to enter in an email address and fill in data for each profile field.

We recommend thoroughly testing your transactional service to ensure that the connection between your website and the service are working properly and the API requests are successful.

💡 If you are onboarding with the Professional Services team, ask your Listrak Project Manager for the Listrak testing email address. When our team is ready to test, you will send the transactional emails to this email address and our team will proceed with testing.

Did this answer your question?