Broadcasts API

The Broadcasts API lets you create email campaigns, send them immediately or schedule them for later, and retrieve detailed performance statistics.

Base URL

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

Authentication

All requests require a Bearer token with broadcast read and/or write permissions. See Authentication for details.

The Broadcast Object

Field	Type	Description
`id`	integer	Unique identifier.
`name`	string	Internal name for the broadcast (not shown to recipients).
`subject`	string	Email subject line.
`preheader`	string	Preview text shown in email clients.
`body`	string	Email body content (rich text).
`html_body`	string	Raw HTML body (when using HTML content type).
`include_unsubscribe_link`	boolean	Whether to include an unsubscribe link.
`reply_to`	string	Reply-to email address.
`status`	string	Current status of the broadcast. See Status Values.
`track_opens`	boolean	Whether open tracking is enabled.
`track_clicks`	boolean	Whether click tracking is enabled.
`total_recipients`	integer	Number of subscribers who will receive (or received) the broadcast.
`broadcast_recipients_count`	integer	Number of recipient records processed so far.
`percentage_complete`	float	Sending progress from 0 to 100.
`scheduled_send_at`	datetime	Scheduled send time (for future-scheduled broadcasts).
`scheduled_timezone`	string	Timezone for the scheduled send time (e.g., `America/New_York`).
`sent_at`	datetime	When the broadcast finished sending.
`created_at`	datetime	When the broadcast was created.
`updated_at`	datetime	When the broadcast was last updated.
`tags`	array	Tag names assigned to the broadcast.
`segment_ids`	array	IDs of segments this broadcast targets.
`email_server_ids`	array	IDs of email servers to send through.

Status Values

Status	Description
`draft`	Not yet sent. Can be edited, deleted, sent, or scheduled.
`future_scheduled`	Scheduled to send at a future time. Can be cancelled.
`scheduled`	Queued and about to start sending.
`queueing`	Building the recipient list.
`sending`	Actively delivering emails.
`sent`	All emails delivered successfully.
`failed`	Sending failed. Can be retried.
`partial_failure`	Some emails failed to send.
`aborted`	Sending was stopped.
`paused`	Sending is paused.

List Broadcasts

Retrieve a list of broadcasts for your channel, ordered by most recently created.

GET /api/v1/broadcasts

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of broadcasts to return.
`offset`	integer	Number of broadcasts to skip (for pagination).

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/broadcasts?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": 15,
      "name": "March Newsletter",
      "subject": "What's new in March",
      "preheader": "Product updates and tips",
      "body": "Hello {{ subscriber.first_name }}...",
      "html_body": null,
      "include_unsubscribe_link": true,
      "reply_to": "[email protected]",
      "status": "sent",
      "track_opens": true,
      "track_clicks": true,
      "total_recipients": 5000,
      "broadcast_recipients_count": 5000,
      "percentage_complete": 100.0,
      "scheduled_send_at": null,
      "scheduled_timezone": null,
      "sent_at": "2025-03-01T14:00:00.000Z",
      "created_at": "2025-02-28T10:00:00.000Z",
      "updated_at": "2025-03-01T14:05:00.000Z",
      "tags": ["newsletter", "monthly"],
      "segment_ids": [3],
      "email_server_ids": [1, 2]
    }
  ],
  "total": 42
}

Get a Broadcast

Retrieve the details of a single broadcast.

GET /api/v1/broadcasts/:id

Example Request

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

Response

Returns the full broadcast object.

Create a Broadcast

Create a new broadcast in draft status.

POST /api/v1/broadcasts

Request Body

Parameters are nested under a broadcast key.

Parameter	Type	Required	Description
`broadcast[subject]`	string	Yes	Email subject line. Supports Liquid variables (e.g., `{{ subscriber.first_name }}`).
`broadcast[body]`	string	No	Rich text email body.
`broadcast[html_body]`	string	No	Raw HTML email body. Use this for fully custom HTML emails.
`broadcast[name]`	string	No	Internal name.
`broadcast[preheader]`	string	No	Email preview text.
`broadcast[reply_to]`	string	No	Reply-to address.
`broadcast[track_opens]`	boolean	No	Enable open tracking (default: channel settings).
`broadcast[track_clicks]`	boolean	No	Enable click tracking (default: channel settings).
`broadcast[include_unsubscribe_link]`	boolean	No	Include unsubscribe link.
`broadcast[segment_ids]`	array	No	Target specific segments. If empty, sends to all active subscribers.
`broadcast[email_server_ids]`	array	No	Send through specific email servers.
`broadcast[use_any_email_server]`	boolean	No	Use any available email server.
`broadcast[scheduled_send_at]`	datetime	No	Schedule for future sending.
`broadcast[scheduled_timezone]`	string	No	Timezone for the scheduled time (e.g., `America/Chicago`).
`broadcast[email_headers]`	array	No	Custom email headers. Each element: `{ "key": "X-Custom", "value": "..." }`.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/broadcasts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast": {
      "subject": "March Product Update",
      "name": "March 2025 Newsletter",
      "body": "Hi {{ subscriber.first_name }},\n\nHere is what we shipped this month...",
      "preheader": "New features and improvements",
      "reply_to": "[email protected]",
      "track_opens": true,
      "track_clicks": true,
      "segment_ids": [3, 7],
      "email_server_ids": [1],
      "email_headers": [
        {"key": "X-Campaign-ID", "value": "march-2025"}
      ]
    }
  }'

Response

Status: 201 Created

{
  "id": 16
}

Error Response

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

Status: 422 Unprocessable Content

Update a Broadcast

Update a broadcast that is in draft or future_scheduled status. Broadcasts that have started sending cannot be updated.

PATCH /api/v1/broadcasts/:id

Request Body

Same parameters as Create a Broadcast. Only include the fields you want to change.

Example Request

curl -X PATCH "https://app.sendbroadcast.com/api/v1/broadcasts/16" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast": {
      "subject": "Updated: March Product Update",
      "preheader": "Fresh off the press"
    }
  }'

Response

Returns the full updated broadcast object.

Error Response

{
  "error": "Broadcast cannot be updated in current status"
}

Status: 422 Unprocessable Content

Delete a Broadcast

Delete a broadcast that is in draft or future_scheduled status. Broadcasts that have started sending cannot be deleted.

DELETE /api/v1/broadcasts/:id

Example Request

curl -X DELETE "https://app.sendbroadcast.com/api/v1/broadcasts/16" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "message": "Broadcast deleted successfully"
}

Error Response

{
  "error": "Broadcast cannot be deleted in current status"
}

Status: 422 Unprocessable Content

Send a Broadcast Immediately

Queue a draft or failed broadcast for immediate sending.

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

Prerequisites

The broadcast must be in draft or failed status.
Your channel must have at least one configured email server.
The broadcast must be ready to send (has a subject and body).

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/broadcasts/16/send_broadcast" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 16,
  "message": "Broadcast queued for sending",
  "status": "scheduled"
}

Error Responses

Status	Body	Cause
422	`"Broadcast is not ready to send"`	Missing subject or body.
422	`"Broadcast can only be sent from draft or failed status"`	Broadcast is already sent or sending.
422	`"SMTP settings are not configured, please check your settings"`	No email server configured for the channel.

Schedule a Broadcast

Schedule a broadcast to send at a specific future date and time.

POST /api/v1/broadcasts/:id/schedule_broadcast

Request Body

Parameter	Type	Required	Description
`broadcast[scheduled_send_at]`	datetime	Yes	When to send. ISO 8601 format.
`broadcast[scheduled_timezone]`	string	Yes	IANA timezone (e.g., `America/New_York`, `Europe/London`).

If the broadcast already has scheduled_send_at and scheduled_timezone set (from create/update), you can call this endpoint without parameters to confirm the schedule.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/broadcasts/16/schedule_broadcast" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast": {
      "scheduled_send_at": "2025-04-01T09:00:00",
      "scheduled_timezone": "America/New_York"
    }
  }'

Response

{
  "id": 16,
  "message": "Broadcast scheduled for future sending",
  "status": "future_scheduled",
  "scheduled_send_at": "2025-04-01T09:00:00.000Z",
  "scheduled_timezone": "America/New_York"
}

Cancel a Scheduled Broadcast

Cancel a future-scheduled broadcast, returning it to draft status.

POST /api/v1/broadcasts/:id/cancel_schedule

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/broadcasts/16/cancel_schedule" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 16,
  "message": "Scheduled broadcast cancelled",
  "status": "draft"
}

Error Response

{
  "error": "Broadcast is not scheduled"
}

Status: 422 Unprocessable Content

Get Broadcast Statistics

Retrieve summary performance statistics for a broadcast.

GET /api/v1/broadcasts/:id/statistics

Example Request

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

Example Response

{
  "broadcast_id": 15,
  "broadcast_name": "March Newsletter",
  "broadcast_subject": "What's new in March",
  "status": "sent",
  "total_recipients": 5000,
  "sent_at": "2025-03-01T14:00:00Z",
  "begin_send_at": "2025-03-01T13:55:00Z",
  "created_at": "2025-02-28T10:00:00Z",
  "tracking": {
    "track_opens": true,
    "track_clicks": true
  },
  "delivery": {
    "sent": 4980,
    "failed": 20,
    "delivery_rate": 99.6
  },
  "engagement": {
    "opens": {
      "count": 2100,
      "rate": 42.0
    },
    "clicks": {
      "count": 680,
      "rate": 13.6
    },
    "unique_links_clicked": 12
  },
  "issues": {
    "bounces": {
      "count": 15,
      "rate": 0.3
    },
    "complaints": {
      "count": 2,
      "rate": 0.04
    },
    "unsubscribes": {
      "count": 30,
      "rate": 0.6
    }
  }
}

Get Broadcast Timeline

Retrieve time-series engagement data for a broadcast, useful for building charts.

GET /api/v1/broadcasts/:id/statistics/timeline

Query Parameters

Parameter	Type	Description
`timeframe`	string	Duration to chart. Options: `60m`, `120m`, `3h`, `6h`, `12h`, `18h`, `24h` (default), `48h`, `72h`, `7d`, `14d`.
`metrics`	string	Comma-separated metric names to include. Options: `Processed`, `Delivered`, `Opens`, `Clicks`, `Bounces`. Defaults to all.

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/broadcasts/15/statistics/timeline?timeframe=24h&metrics=Delivered,Opens,Clicks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "broadcast_id": 15,
  "timeframe": "24h",
  "interval": "1h",
  "start_time": "2025-03-01T13:55:00Z",
  "end_time": "2025-03-02T13:55:00Z",
  "series": [
    {
      "name": "Delivered",
      "data": {
        "2025-03-01T14:00:00Z": 3200,
        "2025-03-01T15:00:00Z": 1780,
        "2025-03-01T16:00:00Z": 0
      }
    },
    {
      "name": "Opens",
      "data": {
        "2025-03-01T14:00:00Z": 800,
        "2025-03-01T15:00:00Z": 450,
        "2025-03-01T16:00:00Z": 210
      }
    },
    {
      "name": "Clicks",
      "data": {
        "2025-03-01T14:00:00Z": 120,
        "2025-03-01T15:00:00Z": 95,
        "2025-03-01T16:00:00Z": 48
      }
    }
  ]
}

Timeframe Intervals

Each timeframe uses a fixed interval for data points:

Timeframe	Interval
`60m`	1 minute
`120m`	2 minutes
`3h`	5 minutes
`6h`	10 minutes
`12h`	20 minutes
`18h`	30 minutes
`24h`	1 hour
`48h`	2 hours
`72h`	3 hours
`7d`	6 hours
`14d`	12 hours

Get Link Click Statistics

Retrieve per-link click statistics for a broadcast.

GET /api/v1/broadcasts/:id/statistics/links

Query Parameters

Parameter	Type	Description
`sort`	string	Sort by `total` (default) or `unique` clicks.
`order`	string	`desc` (default) or `asc`.
`limit`	integer	Number of links to return (default: 100, max: 500).

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/broadcasts/15/statistics/links?sort=unique&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "broadcast_id": 15,
  "total_links": 5,
  "total_clicks": 680,
  "links": [
    {
      "id": 101,
      "identifier": "abc123",
      "url": "https://example.com/new-feature",
      "clicks": 340,
      "total_clicks": 340,
      "unique_clicks": 290,
      "click_rate": 5.8,
      "first_clicked_at": "2025-03-01T14:02:00Z",
      "last_clicked_at": "2025-03-05T08:30:00Z"
    },
    {
      "id": 102,
      "identifier": "def456",
      "url": "https://example.com/pricing",
      "clicks": 210,
      "total_clicks": 210,
      "unique_clicks": 180,
      "click_rate": 3.6,
      "first_clicked_at": "2025-03-01T14:05:00Z",
      "last_clicked_at": "2025-03-04T19:15:00Z"
    }
  ]
}

Error Responses

Status Code	Description
`401 Unauthorized`	Missing or invalid API token, or token lacks broadcast permissions.
`404 Not Found`	Broadcast with the given ID does not exist in your channel.
`422 Unprocessable Content`	Validation errors, invalid status transitions, or missing configuration.

Next: Transactional Email API - Send one-off transactional emails via API.