Transactional Messaging API Best Practices

When you use the transactional messaging API, several best practices can improve your application’s performance and functionality.

The API server automatically closes persistent connections that have no activity for 5 seconds or more. Configure your applications to use keep-alive values of less than 5 seconds. If you try to send a message using a connection that has been closed by the server but remains active in your application, you receive an error from the API.

When you send a message using the transactional messaging API, your request must include a message key. The message key must be unique across all sends from your Business Unit over the past 72 hours. If the message key isn’t unique, the API responds with an error message. For this reason, it’s a good idea to configure your application to generate a unique identifier for each message key. When you use a unique identifier for the message key, you can use it to retrieve delivery status and engagement metrics for the message in real time.

When you use a unique identifier as the message key, you can store request data payloads locally. Each request includes preliminary data collection and generation. You provide some of this data as attribute values in the data payload of the request. Some of this data describes the context of the triggering event, such as the source of the event and the date and time when it occurred.

You can store this data using a Data Extension that’s associated with the send definition, but doing so can have a negative impact on performance. Instead, store this data in your application. When you store data locally, use the message key as the primary key value to uniquely identify each stored payload.

Storing data payloads locally makes it possible to implement several common use cases.

1. Replay the request to handle errors.
2. Extract relevant data points for follow-on messaging campaigns.
3. Combine triggering event data with behavioral or engagement data.
4. Analyze error behavior or performance trends across triggering events.

Using a unique identifier value as the message key also works well with the webhook feature of the Event Notification Service. A listener service uses the message key value as the initial correlation data point between the local data and the events that ENS returns. For example, the Sent event contains the message key used in the original request and the jobId, batchId, listId, and subscriberId identifiers that Marketing Cloud Engagement generates.

When the listener service receives the Sent event, it can identify the locally stored data for the request. You can then update this data to include the jobId, batchId, listId, and subscriberId values. With a unique message key, you can correctly identify the request and its surrounding data across all business units.

Using a unique identifier value as the message key enables robust error handling capabilities in your application. We recommend that you pair the sending application with a listener service for ENS. Subscribe the listener to all transactional send event types: Sent, NotSent, and Bounced.

If an issue arises, ENS returns a NotSent event to the listener. NotSent events include the message key in the payload. The listener service can use this data to let the client application know which requests failed to send. The implementation depends on how you plan to process the various error states. For example, if the application incurs a short delay, then you can replay the message using the original data payload, or alert your team of the problem.

It’s a best practice to use ENS to gain visibility into request and message disposition. When you receive a Sent event, your application doesn’t need to perform any error handling. Similarly, if you receive a NotSent event, you can take an appropriate action to remedy it. However, keep in mind that latency and other unforeseen disruptions can occur. In situations where you expect a Sent or NotSent event but don’t receive one, you can issue a GET to the sending service for the appropriate channel to request the status of the request. These GET requests use the messageKey value in the URL to enable Marketing Cloud Engagement to return details about that request.

Because the messageKey value is only unique within your business unit for 72 hours, you must retrieve the message status within that time period. Continually polling this service by issuing a series of GET requests reduces performance. For this reason, the service is rate-limited for GET requests. For better results, use ENS for real-time visibility.

The Transactional Messaging Service offers the highest capacity relative to other solutions for API-based sending in Marketing Cloud Engagement. However, factors outside of Salesforce’s control can impact message delivery. For example, the time required from message request to delivery depends on the complexity of the content in the message. External factors, such as Internet latency and the architecture and performance of the email service provider that receives the message, can also impact delivery time.

Requests with multiple recipients per request take more time to process. In terms of performance, it’s better to send single messages to individual recipients. Similarly, including too many attribute values in a request can decrease performance. Tailor your send requests to only include the attribute values that you need for the message.