Broadcasts API

A broadcast sends the same SMS message to a large audience at once. You can send immediately, schedule for later, set up recurring sends, or run A/B tests.

Create a broadcast

POST /broadcasts

Request body

{
  "name": "Weekend Promo",
  "message": "50% off this weekend! Shop now at store.example.com",
  "contactListId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "senderId": "MyStore",
  "scheduledAt": null,
  "isRecurring": false,
  "abVariantBMessage": null,
  "abSplitPercent": null
}

Field	Type	Required	Description
`name`	`string`	Yes	Internal label for the broadcast
`message`	`string`	Yes	SMS message body
`contactListId`	`UUID`	No	List of contacts to send to
`senderId`	`string`	No	Registered Sender ID
`scheduledAt`	`ISO 8601`	No	Schedule for a future datetime
`isRecurring`	`bool`	No	Enable recurring sends (default: `false`)
`recurrenceType`	`string`	No	`daily`, `weekly`, `monthly`
`recurrenceInterval`	`int`	No	Interval between recurrences
`recurrenceEndDate`	`ISO 8601`	No	When the recurrence stops
`abVariantBMessage`	`string`	No	Variant B message for A/B test
`abSplitPercent`	`int`	No	% of audience receiving variant B (e.g. `30`)

Response `201`

Returns the new broadcast ID (UUID).

Code sample

curl -X POST https://api.castbrick.co/broadcasts \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Promo",
    "message": "50% off this weekend!",
    "contactListId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "senderId": "MyStore"
  }'

List broadcasts

GET /broadcasts

Query parameters

Parameter	Default	Description
`pageNumber`	`1`	Page number
`pageSize`	`50`	Results per page (max 100)
`search`	—	Filter by name
`status`	—	Filter by status

Response `200`

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Weekend Promo",
      "message": "50% off this weekend!",
      "status": "draft",
      "senderId": "MyStore",
      "contactListId": "list-uuid",
      "scheduledAt": null,
      "createdAt": "2026-05-01T09:00:00Z"
    }
  ],
  "totalCount": 12,
  "pageNumber": 1,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false
}

Broadcast status values

Status	Meaning
`draft`	Created, not yet sent
`scheduled`	Will send at `scheduledAt`
`sending`	Currently dispatching
`sent`	Fully dispatched
`cancelled`	Cancelled before sending
`failed`	Dispatch failed

Get a broadcast

GET /broadcasts/{id}

curl https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Update a broadcast

PUT /broadcasts/{id}

Only draft broadcasts can be updated. Same fields as the create request.

curl -X PUT https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Promo — Final",
    "message": "Last chance! 50% off ends tonight.",
    "contactListId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scheduledAt": "2026-06-07T10:00:00Z"
  }'

Send a broadcast

POST /broadcasts/{id}/send

Sends the broadcast immediately, or queues it if scheduledAt is set.

curl -X POST https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6/send \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Cancel a broadcast

POST /broadcasts/{id}/cancel

Cancels a scheduled or sending broadcast. Already-sent messages cannot be recalled.

curl -X POST https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Duplicate a broadcast

POST /broadcasts/{id}/duplicate

Creates a copy of the broadcast in draft status. Returns the new broadcast ID.

curl -X POST https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6/duplicate \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Delete a broadcast

DELETE /broadcasts/{id}

Permanently removes a draft broadcast. Returns 204 No Content.

curl -X DELETE https://api.castbrick.co/broadcasts/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

SDK examples

import { CastBrick } from 'castbrick-js';

const cb = new CastBrick({ apiKey: process.env.CASTBRICK_API_KEY! });

// Create and send immediately
const id = await cb.broadcasts.create({
  name: 'Weekend Promo',
  message: '50% off this weekend!',
  contactListId: 'list-uuid',
  senderId: 'MyStore',
});
await cb.broadcasts.send(id);

// Schedule for later
const id2 = await cb.broadcasts.create({ name: 'Flash Sale', message: 'Sale starts now!' });
await cb.broadcasts.update(id2, {
  name: 'Flash Sale',
  message: 'Sale starts now!',
  scheduleAt: '2026-06-07T10:00:00Z',
});
await cb.broadcasts.send(id2);

# Create and send immediately
broadcast_id = cb.broadcasts.create(
    name="Weekend Promo",
    message="50% off this weekend!",
    contact_list_id="list-uuid",
    sender_id="MyStore",
)
cb.broadcasts.send(broadcast_id)

# Schedule for later
broadcast_id = cb.broadcasts.create(name="Flash Sale", message="Sale starts now!")
cb.broadcasts.update(
    broadcast_id,
    name="Flash Sale",
    message="Sale starts now!",
    schedule_at="2026-06-07T10:00:00Z",
)
cb.broadcasts.send(broadcast_id)

// Create and send immediately
var id = await cb.Broadcasts.CreateAsync(new CreateBroadcastRequest
{
    Name = "Weekend Promo",
    Message = "50% off this weekend!",
    ContactListId = listId,
    SenderId = "MyStore",
});
await cb.Broadcasts.SendAsync(id);

// Schedule for later
var id2 = await cb.Broadcasts.CreateAsync(new CreateBroadcastRequest
{
    Name = "Flash Sale",
    Message = "Sale starts now!",
});
await cb.Broadcasts.UpdateAsync(id2, new UpdateBroadcastRequest
{
    Name = "Flash Sale",
    Message = "Sale starts now!",
    ScheduleAt = new DateTime(2026, 6, 7, 10, 0, 0, DateTimeKind.Utc),
});
await cb.Broadcasts.SendAsync(id2);

// Create and send immediately
final id = await cb.broadcasts.create(
  name: 'Weekend Promo',
  message: '50% off this weekend!',
  contactListId: 'list-uuid',
  senderId: 'MyStore',
);
await cb.broadcasts.send(id);

// Schedule for later
final id2 = await cb.broadcasts.create(name: 'Flash Sale', message: 'Sale starts now!');
await cb.broadcasts.update(
  id2,
  name: 'Flash Sale',
  message: 'Sale starts now!',
  scheduleAt: DateTime(2026, 6, 7, 10, 0),
);
await cb.broadcasts.send(id2);

Broadcasts API

On this page