Transactional Email API

Transactional emails are one-off messages triggered by a user action – password resets, order confirmations, account notifications, and similar. Unlike broadcasts, transactional emails are sent to a single recipient immediately.

Base URL

https://app.sendbroadcast.com/api/v1

Authentication

Transactional email endpoints require a Bearer token with transactional read and/or transactional write permissions. See Authentication for details.

When to Use Transactional Email

Use this endpoint when you need to send a single email to a single recipient in response to an event. For bulk campaigns, use the Broadcasts API instead.

Common use cases:

  • Password reset emails
  • Order confirmation receipts
  • Account activation emails
  • Notification digests
  • Two-factor authentication codes

Send a Transactional Email

Send a single email to one recipient. The email is queued and processed immediately.

POST /api/v1/transactionals.json

Request Body

Parameters are sent at the top level (not nested).

Parameter Type Required Description
to string Yes Recipient email address.
subject string Yes Email subject line.
body string Yes Email body content.
reply_to string No Reply-to email address.
include_unsubscribe_link boolean No Whether to include an unsubscribe link. Defaults to false.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/transactionals.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your order has shipped",
    "body": "<h1>Order Shipped!</h1><p>Your order #12345 is on its way.</p>",
    "reply_to": "[email protected]"
  }'

Response

Status: 201 Created

{
  "id": 789,
  "body": "<h1>Order Shipped!</h1><p>Your order #12345 is on its way.</p>",
  "preheader": null,
  "queue_at": "2025-03-15T10:30:00.000Z",
  "recipient_email": "[email protected]",
  "recipient_name": null,
  "reply_to": "[email protected]",
  "sent_at": null,
  "subject": "Your order has shipped",
  "include_unsubscribe_link": false,
  "created_at": "2025-03-15T10:30:00.000Z",
  "updated_at": "2025-03-15T10:30:00.000Z",
  "status_url": "https://app.sendbroadcast.com/api/v1/transactionals/789.json"
}

The status_url field provides a direct link to check the delivery status of this email.

Error Response

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

Status: 422 Unprocessable Content

Get Transactional Email Details

Check the delivery status and details of a previously sent transactional email.

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

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/transactionals/789.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "id": 789,
  "body": "<h1>Order Shipped!</h1><p>Your order #12345 is on its way.</p>",
  "preheader": null,
  "queue_at": "2025-03-15T10:30:00.000Z",
  "recipient_email": "[email protected]",
  "recipient_name": null,
  "reply_to": "[email protected]",
  "sent_at": "2025-03-15T10:30:05.000Z",
  "subject": "Your order has shipped",
  "include_unsubscribe_link": false,
  "created_at": "2025-03-15T10:30:00.000Z",
  "updated_at": "2025-03-15T10:30:05.000Z",
  "status_url": "https://app.sendbroadcast.com/api/v1/transactionals/789.json"
}

The sent_at field will be populated once the email has been delivered to your email server.

The Transactional Email Object

Field Type Description
id integer Unique identifier.
recipient_email string The recipient’s email address.
recipient_name string The recipient’s display name (if set).
subject string Email subject line.
body string Email body content.
preheader string Preview text.
reply_to string Reply-to address.
include_unsubscribe_link boolean Whether an unsubscribe link is included.
queue_at datetime When the email was queued for sending.
sent_at datetime When the email was delivered to the mail server. null if still pending.
created_at datetime When the record was created.
updated_at datetime When the record was last updated.
status_url string URL to check the delivery status of this email.

Delivery Behavior

Transactional emails are delivered to all recipients with two exceptions:

  1. Redacted subscribers – If the recipient’s email has been redacted via GDPR, the email will not be sent.
  2. Global suppression – If the recipient’s email is on a global suppression list (e.g., due to a hard bounce), the email will not be sent.

Unlike broadcast emails, transactional emails are not blocked by the subscriber’s is_active status or unsubscribed_at timestamp. This ensures that critical transactional emails (password resets, receipts, etc.) are always delivered.

Error Responses

Status Code Description
401 Unauthorized Missing or invalid API token, or token lacks transactional permissions.
404 Not Found Transactional email with the given ID does not exist in your channel.
422 Unprocessable Content Validation errors (e.g., missing recipient or subject).

Next: Sequences API - Manage automated email sequences via API.