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:

Field	Description
`id`	The unique identifier of the transactional email
`recipient_email`	The email address of the recipient
`recipient_name`	The name of the recipient (optional)
`subject`	The subject line of the email
`body`	The content of the email
`preheader`	Preview text that appears in email clients
`queue_at`	The scheduled time for sending the email
`sent_at`	The time when the email was sent
`created_at`	The time when the record was created
`updated_at`	The time when the record was last updated
`status_url`	URL to check the status of this transactional email

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.

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!"
  }' \
  https://your-broadcast-domain.com/api/v1/transactionals.json

Response

{
  "id": "123",
  "recipient_email": "[email protected]",
  "recipient_name": "John Doe",
  "subject": "Welcome to Our Service",
  "body": "Thank you for signing up!",
  "preheader": "Welcome to our amazing service",
  "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"
}

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": "John Doe",
  "subject": "Welcome to Our Service",
  "body": "Thank you for signing up!",
  "preheader": "Welcome to our amazing service",
  "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"
}

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.