Broadcast API

The Broadcast API provides full CRUD (Create, Read, Update, Delete) operations for managing email broadcast campaigns. You can create, list, view, update, delete, and send broadcasts programmatically.

Required Permissions

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

  • Read Permission: Required for GET endpoints (list, show)
  • Write Permission: Required for POST, PATCH, DELETE endpoints and send operations

Broadcast Object

The broadcast object contains the following fields:

Field Description
`id` The unique identifier of the broadcast
`subject` The subject line of the email
`preheader` Preview text that appears in email clients
`body` The content of the email
`name` The internal name of the broadcast
`track_opens` Whether open tracking is enabled for this broadcast
`track_clicks` Whether click tracking is enabled for this broadcast
`status` Current status of the broadcast (draft, scheduled, sending, sent, etc.)
`html_body` Whether the body contains HTML content
`reply_to` Reply-to email address
`total_recipients` Total number of recipients
`sent_at` Timestamp when the broadcast was sent
`scheduled_send_at` Timestamp when the broadcast is scheduled to send

List Broadcasts

GET /api/v1/broadcasts

Retrieve a list of all broadcasts for the authenticated broadcast channel.

Query Parameters

  • limit (optional): Maximum number of broadcasts to return
  • offset (optional): Number of broadcasts to skip for pagination

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/broadcasts

Response

{
  "data": [
    {
      "id": 1,
      "name": "Weekly Newsletter",
      "subject": "Your Weekly Update",
      "status": "draft",
      "total_recipients": 0,
      "sent_at": null,
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 1
}

Get Broadcast

GET /api/v1/broadcasts/:id

Retrieve details of a specific broadcast.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/broadcasts/123

Response

{
  "id": 123,
  "name": "Weekly Newsletter",
  "subject": "Your Weekly Update",
  "body": "<p>Newsletter content here</p>",
  "status": "draft",
  "track_opens": true,
  "track_clicks": true,
  "total_recipients": 150,
  "sent_at": null,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Create Broadcast

POST /api/v1/broadcasts

Parameters

  • subject (required): Subject line of the email
  • body (required): Content of the email, which can be either a simple string or HTML
  • name (optional): Internal name of the broadcast
  • preheader (optional): Preview text that appears in email clients
  • html_body (optional): Whether the body contains HTML (default: false)
  • reply_to (optional): Reply-to email address
  • track_opens (optional): Whether open tracking is enabled (default: false)
  • track_clicks (optional): Whether click tracking is enabled (default: false)
  • scheduled_send_at (optional): ISO 8601 datetime for scheduled sending
  • scheduled_timezone (optional): Timezone for scheduled sending
  • segment_ids (optional): Array of segment IDs to target
  • email_server_ids (optional): Array of specific email server IDs to use

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast": {
      "subject": "Test Subject",
      "preheader": "Test Preheader",
      "body": "<p>Test Body</p>",
      "name": "Test Name",
      "track_opens": true,
      "track_clicks": true
    }
  }' \
  http://your-domain.com/api/v1/broadcasts

Take note that the body field should be a valid HTML string. If it is not a valid HTML string, the broadcast’s rendered body will be malformed.

When you edit a draft broadcast, the application will attempt to fix any malformed HTML, but this is not always possible.

In general, line breaks should be represented as <br> tags, and paragraphs should be wrapped in <p> tags. If you reference images, you must ensure that the image URL is valid.

You do not need to include the head or body tags in the body field. Broadcast will automatically wrap the content of your body during the outbound mail processing.

Response

{
  "id": 123
}

Update Broadcast

PATCH /api/v1/broadcasts/:id

Update an existing broadcast. Only broadcasts in draft or scheduled status can be updated.

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast": {
      "subject": "Updated Subject",
      "body": "<p>Updated content</p>"
    }
  }' \
  http://your-domain.com/api/v1/broadcasts/123

Response

{
  "id": 123,
  "name": "Updated Newsletter",
  "subject": "Updated Subject",
  "body": "<p>Updated content</p>",
  "status": "draft",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:30:00Z"
}

Delete Broadcast

DELETE /api/v1/broadcasts/:id

Delete a broadcast. Only broadcasts in draft or scheduled status can be deleted.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/broadcasts/123

Response

{
  "message": "Broadcast deleted successfully"
}

Send Broadcast

POST /api/v1/broadcasts/:id/send_broadcast

Queue a broadcast for immediate sending. The broadcast must be in draft or failed status and must be sendable (have required content).

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/broadcasts/123/send_broadcast

Response

{
  "id": 123,
  "message": "Broadcast queued for sending",
  "status": "queueing"
}

Broadcast Status Values

  • draft: Being composed, can be edited
  • scheduled: Scheduled for future sending, can be edited
  • queueing: Being prepared for sending
  • sending: Currently being sent
  • sent: Successfully sent
  • failed: Failed to send
  • partial_failure: Some recipients failed
  • aborted: Manually stopped
  • paused: Temporarily paused

Error Responses

If the request is invalid, the response will include an appropriate HTTP status code and error message:

400 Bad Request

{
  "error": "Broadcast is not ready to send"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Broadcast not found"
}

422 Unprocessable Entity

{
  "error": "Subject can't be blank, Body can't be blank"
}