Understanding Transactional Messaging
Transactional messaging refers to the process of sending automated messages to users in response to specific actions or events. These messages are typically triggered by user interactions or system events and are often personalized and time-sensitive. The primary goal of transactional messaging is to provide relevant and timely information to users based on their actions.
Key Characteristics of Transactional Messaging
- Triggered by User Actions: Transactional messages are usually triggered by specific user actions or events.
- Real-time or Near-real-time Delivery: Transactional messages are sent in response to specific events, and they are often delivered in real-time or shortly after the triggering event to be most effective.
- Personalization: Transactional messages are often highly personalized to the individual user and the specific action they took.
- Informational or Action-oriented: These messages are designed to convey important information or call the user to take a specific action.
- Transactional vs. Promotional: Transactional messages are distinct from promotional or marketing messages.
Common Examples of Transactional Messages
- Order Confirmation: Sent after a user makes a purchase to confirm the details of the order.
- Password Reset Emails: Triggered when a user requests a password reset for their account.
- Account Activation: Sent when a user creates a new account to confirm and activate their account.
Transactional messaging plays a crucial role in enhancing user experience, building trust, and ensuring that users are informed and engaged with the services or products they interact with.
Capabilities of the Transactional Messaging API
The Transactional Messaging API leverages a high-throughput, highly scalable messaging platform designed to send messages as quickly as possible. Notably, for transactional email messages, the traditional selection of high, medium, or low priority in a send definition isn’t necessary.
One notable feature is the ability to track each message through Marketing Cloud Engagement from the
client’s host system. This includes utilizing the messageKey
attribute, enabling
seamless
integration with the Event Notification Service.
This high-performance API empowers developers to streamline the delivery of transactional messages without the need for prioritization, ensuring efficient and reliable communication with end-users.
Considerations for the Transactional Messaging API
When working with the Transactional Messaging API, it's important to consider the following points:
- Single Send Requests: Single send requests using the recipient object attribute
must
provide a unique
messageKey
as an ID. - Suppression Lists and Exclusion Scripts: The API doesn’t support suppression lists or exclusion scripts.
- Send Logging: The API supports send logging only if your account is configured to log automatic sends. If logging automatic sends, configure a data retention policy for your send log to ensure high performance.
- Deduplication at Send Time: To deduplicate messages at send time, use the
messageKey
. Avoid using a primary key on the triggered send data extension. - Maximum Send Definitions: You can create a maximum of 500 email transactional send definitions and triggered send definitions in a 7-day period for 1 business unit. This limit applies to send definitions created in the Marketing Cloud Engagement application and through the API.
These considerations are crucial for ensuring the effective and efficient use of the Transactional Messaging API within the Salesforce Marketing Cloud environment.
Getting Started with Transactional Messaging API
A. Transactional Emails
-
Create an email message content:
Start by designing and creating the content for your transactional email. Ensure that it's relevant and personalized for your users.
-
Define a list or leverage All Subscribers:
Decide whether you want to use an existing subscriber list or leverage the All Subscribers list for sending your transactional emails.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Transaction Confirmation</title>
<style>
body {
font-family: Arial, sans-serif;
background-color: #f4f4f4;
margin: 0;
padding: 0;
}
.container {
max-width: 600px;
margin: 20px auto;
background-color: #ffffff;
padding: 20px;
border-radius: 5px;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
h2 {
color: #333333;
}
p {
color: #555555;
}
.otp {
font-size: 24px;
font-weight: bold;
color: #007BFF;
}
.button {
display: inline-block;
padding: 10px 20px;
font-size: 16px;
text-align: center;
text-decoration: none;
background-color: #007BFF;
color: #ffffff;
border-radius: 5px;
}
.footer {
margin-top: 20px;
text-align: center;
color: #888888;
}
</style>
</head>
<body>
<div class="container">
<h2>Transaction Confirmation</h2>
<p>Your transaction was successful. Here are the details:</p>
<p>Transaction ID: <strong>%%TRANSACTION_ID%%</strong></p>
<p>Amount: <strong>%%AMOUNT%%</strong></p>
<p>OTP: <span class="otp">%%OTP%%</span></p>
<a class="button" href="%%VIEW_TRANSACTION_URL%%">View Transaction</a>
<p class="footer">If you did not make this transaction, please contact support immediately.</p>
</div>
</body>
</html>
B. Create a Triggered Send Data Extension
Follow the steps outlined in the Salesforce Marketing Cloud documentation to create a triggered send data extension from a template. Reference: Create a Triggered Send Data Extension
C. Install Packages
-
Create an API Integration:
Set up an API integration, choosing between a server-to-server or public/web integration. Retrieve the client ID and Client Secret for authentication.
Reference: API Integration Guide
D. Transactional Send Journeys
Transactional Send Journeys empower you to effortlessly create and manage transactional API messages within the familiar Journey Builder workspace.
This journey type is specifically designed to allow non-technical users to configure a Transactional API entry source without the need for developer assistance. It streamlines the process, making it accessible to a broader audience within your marketing team.
Furthermore, you have the ability to monitor the performance of your Transactional Send Journeys directly from the Journeys Dashboard. Key metrics, such as error counts and queue depth, provide valuable insights into the journey's effectiveness and any potential issues that may need attention.
E. Send an email message via send definition
Sends a message to a single recipient via a send definition using a messageKey path parameter.
API
https://{{et_subdomain}}.rest.marketingcloudapis.com/messaging/v1/email/messages/{{$guid}}
Payload
{
"definitionKey": "Example1",
"recipient": {
"contactKey": "b2.shashi@gmail.com",
"to": "b2.shashi@gmail.com",
"attributes": {
"TRANSACTION_ID": "12345gsg213",
"AMOUNT": "1234.80",
"OTP":"123456",
"VIEW_TRANSACTION_URL":"www.example.com"
}
}
}
F. Message Status for Recipient
API
https://{{et_subdomain}}.rest.marketingcloudapis.com//messaging/v1/email/messages/44d5dddf-f232-4fe0-b489-df8a0da9443f
Response
{
"requestId": "99403981-4547-4650-b99e-cbbd16de4d75",
"eventCategoryType": "TransactionalSendEvents.EmailSent",
"timestamp": "2024-01-17T03:28:59.78",
"compositeId": "54E54216-18B5-EE11-B85B-48DF37DC164A.986393.10280.1.185587328",
"info": {
"messageKey": "44d5dddf-f232-4fe0-b489-df8a0da9443f",
"contactKey": "b2.shashi@gmail.com",
"to": "b2.shashi@gmail.com"
}
}
Deep Dive
Considerations for Transactional Sends
When delving into the intricacies of Transactional Sends, it's crucial to keep the following considerations in mind:
-
Transactional Sends are not Triggered Sends:
It's important to understand that Transactional Sends operate differently from Triggered Sends. While they share similarities, they serve distinct purposes and have unique behaviors.Triggered Sends are native to SOAP API whereas Transactioanal Sends are more driven by REST API
-
Features and Configurations Similar to Triggered Sends:
Despite the differences, many features and configurations in Transactional Sends are similar to Triggered Sends. Familiarity with Triggered Sends can provide a foundation for working with Transactional Sends.For Triggered Sends, TriggeredSends Data Extensions are not mandatory while creating a defintion whereas when you create a Transactional Journey Sends, Triggered sends data extensions is mandatory
-
Challenges in Troubleshooting Transactional Journey Sends:
Transactional Journey Sends introduce a newly constructed canvas, and troubleshooting can be challenging. Understanding the intricacies of this canvas is essential for efficiently addressing issues and optimizing performance. If you are defining the transactional defintion via API, make sure your payload are well strucutred, MCMS_UTM validations are not well defined. If you try to reconstruct the the payload and fix the validation issues, it would throw another validation error "DefinitionKey or Name already exists"
-
Significance of Email Activity Configurations:
The configurations related to Email Activity play a crucial role in the success of Transactional Sends. Paying close attention to these settings ensures that emails are sent and tracked accurately.Your send classification has to be Transactional Send Classification and the sender profile should be verified and authenticated.
-
Delivery Options Similar to Triggered Sends:
Delivery Options for Transactional Sends share similarities with Triggered Sends. Familiarize yourself with these options to fine-tune the delivery process and enhance the overall effectiveness of your email communications. Subscriptions and AutoAdd/Update plays a vital role, we would dig deeper into this very soon.
Exploring these considerations will provide a comprehensive understanding of Transactional Sends and contribute to the successful implementation of your messaging strategy.
Email Send Definition JSON Properties
Name | Type | Description |
---|---|---|
definitionKey |
string | Required. Unique, user-generated key to access the definition object. |
name |
string | Required. Name of the definition. Must be unique. |
content.customerKey |
string | Required. Unique identifier of the content asset. |
status |
string | Operational state of the definition: active, inactive, or deleted. A message sent to an active definition is processed and delivered... |
description |
string | User-provided description of the send definition. |
classification |
string | Marketing Cloud external key of a sending classification defined in Email Studio Administration... |
subscriptions.list |
string | Required. Marketing Cloud external key of the list or all subscribers. Contains the subscriber keys and profile attributes. |
subscriptions.dataExtension |
string | Marketing Cloud external key of the triggered send data extension... |
subscriptions.autoAddSubscriber |
boolean | Adds the recipient’s email address and contact key as a subscriber key to subscriptions.list. Default is true. |
subscriptions.updateSubscriber |
boolean | Updates the recipient’s contact key as a subscriber key with the provided email address and profile attributes to subscriptions.list. Default is true. |
options.trackLinks |
boolean | Wraps links for tracking and reporting. Default is true. |
options.cc |
array | Include CC email addresses with every send. To CC dynamically at send time, create a profile attribute and use the %%attribute%% syntax. |
options.bcc |
array | Include BCC email addresses with every send. To BCC dynamically at send time, create a profile attribute and use the %%attribute%% syntax. |
options.createJourney |
boolean | A value of true updates the send definition to make it available in Journey Builder as a Transactional Send Journey. |
Payload Structure
{
"definitionKey": "Example5",
"status": "Active",
"name": "Example5",
"description": "Created via REST",
"classification": "Default Transactional",
"content": {
"customerKey": "a128e1f4-0c53-4232-be79-7e2f9f13a7ce" // Email customer key
},
"subscriptions": {
"list": "All Subscribers - 653241", // List or all subscribers external key
"dataExtension": "CF2F5C60-65C3-43E7-8ACD-AD68667F133C", // Trigerred Send Definition External Key
"autoAddSubscriber": true, // Add subscriber to the List
"updateSubscriber": false // Don't update email address/subscriber proerties during send
},
"options": {
"trackLinks": true,
"cc": [
"cc_address@example.com"
],
"bcc": [
"bcc_address@example.com"
],
"createJourney": true
}
}
Use Case : Create a email send defintion via Transactioanal API
API Endpoint :Create Email Send Definition
https://{{et_subdomain}}.rest.marketingcloudapis.com/messaging/v1/email/definitions
Payload Structure
{
"definitionKey": "Example5",
"status": "Active",
"name": "Example5",
"description": "Created via REST",
"classification": "Default Transactional",
"content": {
"customerKey": "7516062c-e902-40e2-b816-1eeae3121438" // Email customer key
},
"subscriptions": {
"list": "All Subscribers - 31840", // List or all subscribers external key
"dataExtension": "F3363DC5-10F9-427E-A18C-4D17E89629A8", // Trigerred Send Definition External Key
"autoAddSubscriber": true, // Add subscriber to the List
"updateSubscriber": false // Don't update email address/subscriber proerties during send
},
"options": {
"trackLinks": true,
"createJourney": true
}
}
Response
{
"requestId": "eb223af4-7842-4b33-b849-ad8d5d53d6b1",
"name": "Example5",
"definitionKey": "Example5",
"description": "Created via REST",
"classification": "Default Transactional",
"status": "Active",
"createdDate": "2024-01-17T06:02:00",
"modifiedDate": "2024-01-17T06:02:00",
"content": {
"customerKey": "7516062c-e902-40e2-b816-1eeae3121438"
},
"subscriptions": {
"dataExtension": "F3363DC5-10F9-427E-A18C-4D17E89629A8",
"list": "All Subscribers - 31840",
"autoAddSubscriber": true,
"updateSubscriber": false
},
"options": {
"trackLinks": true
},
"journey": {
"interactionKey": "e6079abb-22bd-44fa-b53e-5a5b7792bb19"
}
}
Aanalysis
If your email message has personalization that leverages triggeredsend data extension attributes, make sure all the persoanlization attributes are present in the sendable data extension. If not, MCMS UTM ContentBuilder Validation error will be caught.
The Transactional Journey sends would append timestamp to the definition name as the Journey Name.
Section "journey": {
"interactionKey": "e6079abb-22bd-44fa-b53e-5a5b7792bb19"
}
helps you define to tie the defintion to a journey, once linked to a journey, it can't be
unlinked.
Use Case : Create a email send defintion via Transactioanal API
Create a Transactioanal Journey Send without a triggered send data extension
If you want to create a transactional journey send without attaching a triggered send data extension make sure you are leveraging profile attributes for personalization and not the custom attributes from the sendable data extension
Payload
{
"definitionKey": "Example6",
"status": "Active",
"name": "Example6",
"description": "Created via REST",
"classification": "Default Transactional",
"content": {
"customerKey": "d6181777-bd89-4223-82f2-a93f807810d6" // Email without personalization
},
"subscriptions": {
"list": "All Subscribers - 31840", // List or all subscribers external key
"autoAddSubscriber": true, // Add subscriber to the List
"updateSubscriber": false // Don't update email address/subscriber proerties during send
},
"options": {
"trackLinks": true,
"createJourney": true
}
}
Response
{
"requestId": "5f4382d0-8275-4f1f-b7fd-35c16c6644e2",
"name": "Example6",
"definitionKey": "Example6",
"description": "Created via REST",
"classification": "Default Transactional",
"status": "Active",
"createdDate": "2024-01-17T06:53:00",
"modifiedDate": "2024-01-17T06:53:00",
"content": {
"customerKey": "d6181777-bd89-4223-82f2-a93f807810d6"
},
"subscriptions": {
"list": "All Subscribers - 31840",
"autoAddSubscriber": true,
"updateSubscriber": false
},
"options": {
"trackLinks": true
},
"journey": {
"interactionKey": "e473af50-63ac-44fb-8107-1d01360e47fd"
}
}
Transactional Email Definition level error codes
1. Content Validation
2. Data Extension Validation
3. Duplicate Validation
4. Send Classification Validation
5. Subscription Validation
Fix all the validation issues via PATCH
API Endpoint
https://{{et_subdomain}}.rest.marketingcloudapis.com/messaging/v1/email/definitions/Example6
Payload Structure
{
"status": "Active",
"name": "Example6",
"description": "Created via REST",
"classification": "Default Transactional",
"content": {
"customerKey": "d6181777-bd89-4223-82f2-a93f807810d6" // Email without personalization
},
"subscriptions": {
"list": "All Subscribers - 31840", // List or all subscribers external key
"dataExtension": "F3363DC5-10F9-427E-A18C-4D17E89629A8",
"autoAddSubscriber": true, // Add subscriber to the List
"updateSubscriber": false // Don't update email address/subscriber proerties during send
},
"options": {
"trackLinks": true,
"createJourney": true
}
}
Response
{
"requestId": "5a947560-8574-42d7-8029-aa4272ba07b8",
"name": "Example6",
"definitionKey": "Example6",
"description": "Created via REST",
"classification": "Default Transactional",
"status": "Active",
"createdDate": "2024-01-17T06:53:00",
"modifiedDate": "2024-01-17T06:53:00",
"content": {
"customerKey": "d6181777-bd89-4223-82f2-a93f807810d6"
},
"subscriptions": {
"dataExtension": "F3363DC5-10F9-427E-A18C-4D17E89629A8",
"list": "All Subscribers - 31840",
"autoAddSubscriber": true,
"updateSubscriber": false
},
"options": {
"trackLinks": true
},
"journey": {
"interactionKey": "e473af50-63ac-44fb-8107-1d01360e47fd"
}
}
Thanks Shashi. This was very useful. Is there areason why you didn't selected Add and Update Contacts to All Subscribers list in Delivery Options
ReplyDeleteIf you are leveraging the Transactional API from a third party (outside SFMC), they most likely might not have the subscriber key. To maintain the integrity of the subscriber key definition, I showcased all the available options.
Delete