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.
Email template
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:
Messages > Email Messages Transactional Email.
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.
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.
Access the Integration Dashboard by navigating from the home menu to Integrations > Integrations Management.
Click New Integration.
Select the Email API card > click Integrate.
Click Setup Integration - on the bottom right side of the page.
Enter an Integration Name
Select at least one Access Level.
💡 The Client ID and Client Secret will be populated once the form is completed and saved.
Add the IP address(es) that are allowed to access this API integration (i.e. Whitelisting) by configuring the IP Address Type.
Select on the following options - Single IP Address, Wildcard Match, or IP Address Range.
Add IP Address(es).
(Optional) - Disable the IP Address(es) that have been whitelisted.
Check the box to disable any of the IP addresses whitelisted - entered in the IP Address Type table (see step 7).
💡 This will NOT delete the IP addresses listed. You can re-enable at any time by unchecking the box > click Save to apply changes.
Click Save to complete the setup/apply updates to IP Address Whitelist settings.
Example of the Integration Settings page:
Send a TransactionalMessage
Your request body will use the following format.
{
"emailAddress": "[email protected]",
"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.
Resending a Transactional Email
A transactional message can be resent to the same recipient or sent to a different email address, for example of the initial address was misspelled, using the Resend a TransactionalMessage request.
When resending a transactional message the original dynamic data specified in the profile field or order items block will be used in the resend message. Other properties such as fixed message creative will update during the new send. The only data parameter for the message that can be updated is the email address.
⚠️ Deleting or adding a profile field between the original send date and resend date will cause information to not display correctly in a contact's email. A new filed will render as <<fieldgroupname/fieldname>> because there is no data to display.
When resending an email the resendKey will need to be populated in the REST API call. When using the resendKey, you can specify an email address to use when resending the message. If no email address is provided, the message will be sent to the initial email address.
This resendKey can be found in the resource of a 201 success call of a SendTransactional call. The resendKey can also be found using the GetTransactional Message Activity call.
⚠️ resendKeys are available for 30 days after the initial send. If more than 30 days have elapsed, the message cannot be resent.
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.