Broadcasts

DM Broadcasts let you send a message to a segmented list of contacts across supported social platforms. Broadcasts are queued and delivered asynchronously in batches.

Agency plan required. Broadcasts use the dm_broadcasts feature flag, which is only available on Agency plan. Requests on lower-tier plans return 403 with error code PLAN_UPGRADE_REQUIRED and message “DM Broadcasts require an Agency plan”.

Base URL


https://api.voxburst.io/v1/broadcasts

Broadcast Statuses

Status	Description
`DRAFT`	Created but not yet sent or scheduled
`SCHEDULED`	Scheduled to send at a future time
`SENDING`	Currently being delivered to contacts
`SENT`	All deliveries enqueued
`PAUSED`	Paused mid-delivery
`FAILED`	Delivery failed unrecoverably

Broadcast Object


{
  "id": "bc_abc123",
  "workspaceId": "ws_01hwxyz",
  "name": "May Newsletter",
  "messageTemplate": "Hi there! Check out our latest update.",
  "platforms": ["TWITTER"],
  "segmentRules": {
    "tags": ["newsletter"],
    "platforms": ["TWITTER"],
    "hasInteraction": true
  },
  "status": "DRAFT",
  "totalContacts": 0,
  "scheduledFor": null,
  "sentAt": null,
  "createdAt": "2026-05-01T10:00:00Z",
  "updatedAt": "2026-05-01T10:00:00Z"
}

Broadcast Fields

Field	Type	Description
`id`	string	Broadcast ID
`workspaceId`	string	Workspace this broadcast belongs to
`name`	string	Human-readable name
`messageTemplate`	string	Message text (max 1,000 chars)
`platforms`	string[]	Platform constants to send on
`segmentRules`	object	Audience filtering rules — see Segment Rules
`status`	string	Current broadcast status
`totalContacts`	integer	Total contacts targeted (populated at send time)
`scheduledFor`	string \| null	ISO 8601 scheduled send time
`sentAt`	string \| null	ISO 8601 timestamp when sending started
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last-updated timestamp

Segment Rules

The segmentRules object filters which contacts receive the broadcast. All conditions are ANDed together.

Field	Type	Description
`tags`	string[]	Only include contacts with ALL of these tags
`platforms`	string[]	Only include contacts on these platforms
`hasInteraction`	boolean	If `true`, only contacts with a recorded interaction (`lastSeenAt` is not null)

Only contacts with lastSeenAt set (i.e., contacts who have previously interacted) are eligible for broadcast delivery, regardless of segmentRules. This is enforced server-side as an opt-in safeguard.

List Broadcasts

GET /v1/broadcasts

List broadcasts with optional status filter. Uses page/limit pagination.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `DRAFT`, `SCHEDULED`, `SENDING`, `SENT`, `PAUSED`, `FAILED`
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)


curl "https://api.voxburst.io/v1/broadcasts?status=DRAFT&limit=20" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "broadcasts": [ { ... } ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Get Broadcast

GET /v1/broadcasts/:id

Retrieve a single broadcast with delivery statistics.


curl https://api.voxburst.io/v1/broadcasts/bc_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "broadcast": { ... },
  "deliveryStats": {
    "PENDING": 12,
    "SENT": 88,
    "FAILED": 2
  }
}

Create Broadcast

POST /v1/broadcasts

Create a new broadcast in DRAFT status.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable name (1–255 chars)
`messageTemplate`	string	Yes	Message text (1–1,000 chars)
`platforms`	string[]	Yes	At least one platform constant
`segmentRules`	object	No	Audience filtering — see Segment Rules
`scheduledFor`	string	No	ISO 8601 datetime to automatically send


curl -X POST https://api.voxburst.io/v1/broadcasts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May Newsletter",
    "messageTemplate": "Hi! Check out our latest update.",
    "platforms": ["TWITTER"],
    "segmentRules": { "tags": ["newsletter"] }
  }'

Response (201)


{
  "broadcast": { ... }
}

Update Broadcast

PATCH /v1/broadcasts/:id

Update a broadcast. Only DRAFT or SCHEDULED broadcasts can be updated.

Request Body

All fields are optional.

Field	Type	Description
`name`	string	New name
`messageTemplate`	string	New message template
`platforms`	string[]	Replacement platform list
`segmentRules`	object	Replacement segment rules
`scheduledFor`	string \| null	New scheduled time, or `null` to remove


curl -X PATCH https://api.voxburst.io/v1/broadcasts/bc_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Newsletter" }'

Response


{
  "broadcast": { ... }
}

Send Broadcast

POST /v1/broadcasts/:id/send

Enqueue a DRAFT or SCHEDULED broadcast for immediate delivery. Contacts matching the segment rules are resolved and queued for DM delivery.


curl -X POST https://api.voxburst.io/v1/broadcasts/bc_abc123/send \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "broadcast": { "status": "SENDING", ... },
  "enqueuedContacts": 102,
  "batches": 3
}

enqueuedContacts is the number of contacts that were matched by segment rules and enqueued. batches is the number of SQS message batches created.

List Deliveries

GET /v1/broadcasts/:id/deliveries

List individual delivery records for a broadcast.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 50, max: 100)


curl "https://api.voxburst.io/v1/broadcasts/bc_abc123/deliveries?page=1&limit=50" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "deliveries": [
    {
      "id": "del_xyz789",
      "broadcastId": "bc_abc123",
      "contactId": "contact_abc123",
      "platform": "TWITTER",
      "status": "SENT",
      "contact": {
        "id": "contact_abc123",
        "displayName": "Alice Example",
        "username": "alice",
        "platform": "TWITTER"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 102,
    "totalPages": 3
  }
}

Delete Broadcast

DELETE /v1/broadcasts/:id

Delete a broadcast. Only DRAFT status broadcasts can be deleted.


curl -X DELETE https://api.voxburst.io/v1/broadcasts/bc_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{ "success": true }