Transactional Messaging API Service Architecture

In Marketing Cloud Engagement, transactional messages pass through four service layers. First, the API layer handles API requests from your application. Second, the service layer converts the inbound send request data payload into the format that’s required downstream. Third, the outbound message management (OMM) layer builds the message content based on the payload of the originating API request. Finally, the message transfer agent (MTA) layer sends the rendered message to its destination, such as an email server or an SMS messaging aggregator.

The API layer handles the create, read, update, and delete methods for email send definitions. Endpoints differ by channel. In other words, you use different sets of endpoints to work with transactional emails, transactional SMS messages, and transactional push notifications.

In REST API, some requests related to transactional messaging are synchronous, and some are asynchronous. Generally, endpoints for managing send definitions, retrieving send statuses and metrics, and managing queues are synchronous. Endpoints related to the action of sending a message to recipients are asynchronous.

A message key is required for all send requests. In a request to send a message to a single recipient, you must generate a message key and include it in the URL path of your request. In a request to send a message to multiple recipients, if you don’t provide a message key, Marketing Cloud Engagement automatically generates one for you. When you generate a message key, it must be unique among all requests issued over the preceding 72 hours.

For message-sending requests, a successful response confirms that the API received a well-formed request, but not that the recipients received the message. Message-sending requests return an error only when there’s an authentication or syntax error related to the request, or when the API is unavailable.

The service layer converts the request payload into a format that downstream layers expect. It also performs basic validation tests, such as confirming that the email address is valid in a transactional email request. Send definitions can optionally specify that the converted data be recorded in a Data Extension. This step also occurs in the service layer.

The service layer is asynchronous. When the API accepts a request, the service layer adds the request to a queue. Requests exit the queue as units of work. These work units are referred to as jobs, which consist of batches of subscribers. Each job has a unique JobId, each batch has a unique BatchId, and each subscriber has a unique SubscriberId. When you send messages using the Transactional Messaging API, you can identify a message sent to an individual recipient based on the combination of these IDs combined with the message key.

Errors that occur during data validation at this layer aren’t returned to the client application directly. You can use the Event Notification Service (ENS) or issue subsequent requests to obtain this information.

The OMM layer evaluates the content of the send definition against each subscriber’s attributes. After scripting, personalization, and other content finalization, it passes the rendered message to the MTA layer. Errors can occur during message construction. For example, logic error can occur in scripted message content. Marketing Cloud Engagement doesn’t return these errors to the client application. However, you can issue subsequent requests to obtain this information.

Performance at the OMM layer depends on the complexity of the message content, your tenant’s data environment, and the performance of external systems. For example, if a message uses an AMPscript function to sends HTTP GET requests to an external service, the capabilities of that external service influence the time needed to build each message.

The MTA layer is the final step in the process of sending a transactional message. This layer passes the rendered message to the appropriate downstream resource. Specifically, it sends email messages to the receiving email server, SMS messages to an SMS messaging aggregator, and push notifications to the appropriate push notification service. Next, the Event Notification Service raises any errors related to the delivery of the message.