Send Transactional Messages with Direct Email Send API

Use Direct Email Send API to send personalized email to one or more recipients in response to activity in your application. Messages are sent immediately through the High Scale Flow (HSF) messaging service. For example, you can use Direct Email Send API for welcome emails, order confirmations, password resets, and account notifications.

The API is available at https://api.salesforce.com/automation/actions360.

Use an OAuth Bearer token that has the sfap_api scope in your calls to Direct Email Send API. See Connect to Direct Email Send API.

The API uses send definitions to send messages. A send definition uses the ListEmail Salesforce object. It contains references to the email content, the sender identity, tracking options, and metadata for the message. You create a send definition once, then reference its ID in every send request with the sendDefinitionId query parameter. Before you send an email, the content that the send definition references must be published in your marketing CMS.

To create a send definition, use REST API to create a ListEmail object, and then deploy the object.

The API provides three operations, each relative to https://api.salesforce.com/automation/actions360.

OperationMethodPath
Send to a single recipientPOST/messaging/email/v1
Send to multiple recipientsPOST/messaging/email/v1/bulk
Preview a rendered emailPOST/messaging/email/v1/preview

Every operation requires the sendDefinitionId query parameter and an Authorization: Bearer header.

Review these considerations before you use Direct Email Send API.

  • High Scale Actions and Direct Email Send must be set up in your org. If these features aren’t set up, the API returns a 403 - feature not enabled for tenant response. Contact your account executive for information about setting up these features.
  • The OAuth token must be a JSON Web Token (JWT) with the sfap_api scope. You can’t use non-JWT tokens.
  • Individual send requests use the individualId attribute to identify the recipient. Bulk requests use the recipients array.
  • The attributes object is keyed by the Apex class name defined in your CMS content. The key must match the class name exactly, including case.
  • Publish all content referenced in the send definition. A send definition that references draft or missing content produces an empty message body. To confirm that the email renders correctly before you send it, use the preview operation.
  • The API enforces rate limits. When a request exceeds the limit, the API returns 429. If you encounter this error, implement an exponential backoff system and retry.