Transactional Email API

The Transactional Email API allows you to programmatically send individual, personalized emails triggered by specific events in your application.

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

• View transactional email details (Read)
• Send transactional emails (Write)

Transactional Email Object

The transactional email object contains the following fields:

Send Transactional Email

POST /api/v1/transactionals.json

Parameters

• to (required): Email address of the recipient
• subject (required): Subject line of the email
• body (required): Content of the email, which can be either a simple string or HTML. In either case, Broadcast will wrap the content in the appropriate html and body tags. If you want to incorporate an entire HTML design, just send the contents within the body tag.
• reply_to (optional): Reply-to email address for this transactional email

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "to": "[email protected]",
    "subject": "Welcome to Our Service",
    "body": "Thank you for signing up!",
    "reply_to": "[email protected]"
  }' \
  https://your-broadcast-domain.com/api/v1/transactionals.json

Response

{
  "id": "123",
  "recipient_email": "[email protected]",
  "recipient_name": null,
  "subject": "Welcome to Our Service",
  "body": "Thank you for signing up!",
  "preheader": null,
  "reply_to": "[email protected]",
  "queue_at": "2024-03-21T10:00:00Z",
  "sent_at": null,
  "created_at": "2024-03-21T09:00:00Z",
  "updated_at": "2024-03-21T09:00:00Z",
  "status_url": "https://your-broadcast-domain.com/api/v1/transactionals/123.json"
}

Note: The recipient_name field is populated from subscriber data if the email matches an existing subscriber. The preheader field is reserved for future use.

If the request is invalid, the response code will be 422 (Unprocessable Entity). The error message will be returned in the response body:

{
  "errors": {
    "recipient_email": ["can't be blank"],
    "subject": ["can't be blank"],
    "body": ["can't be blank"]
  }
}

Get Transactional Email Details

GET /api/v1/transactionals/:id.json

Parameters

• id (required): The ID of the transactional email

Request

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/transactionals/123.json

Response

{
  "id": "123",
  "recipient_email": "[email protected]",
  "recipient_name": null,
  "subject": "Welcome to Our Service",
  "body": "Thank you for signing up!",
  "preheader": null,
  "reply_to": "[email protected]",
  "queue_at": "2024-03-21T10:00:00Z",
  "sent_at": "2024-03-21T10:00:05Z",
  "created_at": "2024-03-21T09:00:00Z",
  "updated_at": "2024-03-21T10:00:05Z",
  "status_url": "https://your-broadcast-domain.com/api/v1/transactionals/123.json"
}

Unsubscribe Behavior

Transactional emails bypass unsubscribe status. Unlike marketing emails (broadcasts and sequences), transactional emails will be delivered even if the recipient has unsubscribed from your mailing list.

This is by design and follows industry standards (CAN-SPAM, GDPR) which distinguish between marketing communications and essential service-related messages like:

• Password reset emails
• OTP/verification codes
• Account confirmation emails
• Order receipts and shipping notifications

Exceptions: Transactional emails will still be blocked if:

• The recipient is a redacted subscriber (GDPR data deletion request)
• The recipient is on the global suppression list (typically due to hard bounces)

Notes

• When sending a transactional email, if no specific queue time is provided, the email will be queued immediately.
• If the recipient’s email matches an existing subscriber in your database, the transactional email will be automatically associated with that subscriber’s record.
• All API requests must include a valid API token with the appropriate permissions in the Authorization header.