Transactional Messaging API: real-time transactional email in Marketing Cloud

Order confirmation, verification code, password reset: these are messages that have to arrive now, one at a time, triggered by your own system. Marketing Cloud Engagement's Transactional Messaging API was built for exactly that. It is more direct than setting up a Triggered Send and it is the recommended API for new transactional flows.

Before you start

• A server-to-server OAuth 2.0 token. See the REST API authentication tutorial.
• In the Installed Package, the email permissions (read, write and send).
• An email ready in Content Builder, with its customer key noted down. Personalize it with attributes you will send in the call, such as %%=v(@OrderNumber)=%% or %%OrderNumber%%.

1. The send definition

The definition links the email to its send settings. You create it once and reuse it for every send.

curl -X POST "https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/messaging/v1/email/definitions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionKey": "order-confirmed",
    "name": "Order confirmed",
    "content": { "customerKey": "EMAIL_CUSTOMER_KEY" },
    "subscriptions": { "list": "All Subscribers" },
    "options": { "trackLinks": true }
  }'

• definitionKey is the name your system will use on every send. Pick something stable and readable.
• subscriptions.list points to the subscriber list. Check the list's customer key in your own account.

2. Sending

Each send has a messageKey that you generate. Use a unique identifier, such as a UUID, and keep it: that is how you look up the status later.

curl -X POST "https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/messaging/v1/email/messages/7f3c2a90-5b1e-4d3a-9a0f-1c2b3d4e5f60" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionKey": "order-confirmed",
    "recipient": {
      "contactKey": "customer-10021",
      "to": "ana@example.com",
      "attributes": {
        "OrderNumber": "10021",
        "OrderTotal": "189.90"
      }
    }
  }'

The API answers 202 Accepted: the request was accepted and queued for sending, which is processed in real time.

• contactKey is the contact's key in Marketing Cloud. Use the same key as the rest of your operation (usually the customer ID), not the email address, so you do not create duplicate contacts.
• attributes are the personalization data for that message.

3. Checking the status

curl "https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/messaging/v1/email/messages/7f3c2a90-5b1e-4d3a-9a0f-1c2b3d4e5f60" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response tells you whether the message was sent, or why it was not (for example, a bounced or unsubscribed address).

Good practices

• Reuse the OAuth token instead of requesting one per send.
• Handle 4xx errors on your side: a 400 is usually an invalid body or a definitionKey that does not exist.
• Pause the definition instead of deleting it when you need to stop a flow: the history stays available.
• Monitor messages that did not go out, by checking the status with the messageKey.

Summary

Create the definition once, send each message with a unique messageKey and the event's attributes, and follow up on the status with the same key. For confirmations and codes, the Transactional Messaging API is the simplest and fastest path inside Marketing Cloud.