Understanding Transactional Messaging

Understanding Transactional Messaging
Home Page

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

  1. Triggered by User Actions: Transactional messages are usually triggered by specific user actions or events.
  2. 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.
  3. Personalization: Transactional messages are often highly personalized to the individual user and the specific action they took.
  4. Informational or Action-oriented: These messages are designed to convey important information or call the user to take a specific action.
  5. 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

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

  2. 
      <!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>
                          
                        
  3. 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.

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

  1. 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:

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

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

  3. 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"

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

  5. 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"
    }
}          
        

TOP


Comments

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

    ReplyDelete
    Replies
    1. If 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

Post a Comment

Most Viewed

CLOUD PAGE ENABLEMENT - PART 1

EMAIL NOT SENT IN JOURNEY BUILDER

CONSIDERATIONS FOR JOURNEY BUILDER

Preference Center Demystified


Knowledge Article

Popular Posts

CLOUD PAGE ENABLEMENT - PART 1

EMAIL NOT SENT IN JOURNEY BUILDER

CONSIDERATIONS FOR JOURNEY BUILDER

Preference Center Demystified

Journey Builder REST API Documentation

Share with Friends

Disclaimer:

The information provided on this technical blog is for general informational purposes only. As a SFMC (Salesforce Marketing Cloud) Technical Architect, I strive to offer accurate and up-to-date content related to SFMC and its associated technologies. However, please note that technology is constantly evolving, and the information provided may become outdated or inaccurate over time.

The content published on this blog represents my personal views and experiences as a SFMC Technical Architect and does not necessarily reflect the official views or opinions of any organization or employer I may be affiliated with.

While I make every effort to ensure the accuracy and reliability of the information presented, I cannot guarantee its completeness, suitability, or applicability to your specific circumstances. Therefore, it is essential to verify any information provided and make your own independent assessments or seek professional advice if needed.

Furthermore, any actions taken based on the information provided on this blog are at your own risk. I shall not be held liable for any damages, losses, or inconveniences arising from the use of the information presented here.

Please keep in mind that SFMC and its associated technologies are complex and require technical expertise for proper implementation and management. It is recommended to consult with qualified professionals or official SFMC documentation for comprehensive guidance.

Finally, please note that any product or company names mentioned on this blog are trademarks or registered trademarks of their respective owners. The mention of these trademarks or registered trademarks does not imply any endorsement or affiliation with the blog.

By accessing and using this blog, you agree to the terms of this disclaimer. If you do not agree with any part of this disclaimer, please refrain from using this blog.