Broadcasts

Marketing campaigns sent to an audience or segment (`publiq.broadcasts`).

The broadcasts resource covers a campaign lifecycle: create in draft from a template, targeting an audience or a segment, check its status, list history and dispatch (now or scheduled).

Method reference

`broadcasts.create`

broadcasts.create(params) → Promise<Broadcast>

Creates a broadcast in draft, from a versioned template, targeting either a whole audience or a segment. Nothing is sent until you call broadcasts.send.

Parameters

Parameter	Type	Description
`fromEmail`Required	`string`	Sender email. The domain must be verified. See Domains & DNS.
`templateId`Required	`string`	The versioned template to send. See Templates.
`audienceId`Optional	`string`	Targets the whole audience. Use `audienceId` or `segmentId` — never both. See Audiences.
`segmentId`Optional	`string`	Targets a segment of an audience. Use `segmentId` or `audienceId` — never both. See Segments.

Returns: The created broadcast — { object: "broadcast", id, status: "draft", ... }. Keep the id to review and send later.

const broadcast = await publiq.broadcasts.create({
fromEmail: 'news@yourdomain.com',
templateId: 'tpl_summer_sale',
audienceId: 'aud_123',
});
console.log(broadcast.id, broadcast.status); // "bc_...", "draft"

You must pick exactly one target: audienceId or segmentId. Passing both (or neither) → 400 validation_error. Every broadcast uses a saved template. See Audiences, Segments and Templates.

`broadcasts.get`

broadcasts.get(id) → Promise<Broadcast>

Fetch a broadcast details by id: current status and, if scheduled, scheduled_at.

Parameters

Parameter	Type	Description
`id`Required	`string`	Broadcast ID (returned by `broadcasts.create`).

Returns: The broadcast with its status and, when scheduled, scheduled_at. 404 if it does not exist in the organization.

const broadcast = await publiq.broadcasts.get('bc_123');
console.log(broadcast.status); // "scheduled"

`broadcasts.list`

broadcasts.list({ limit?, after? }) → Promise<BroadcastList>

List the organization broadcasts, newest first, cursor-paginated.

Parameters

Parameter	Type	Description
`limit`Optional	`number`	Items per page (default 20, max 100).
`after`Optional	`string`	Cursor: `id` of the last item on the previous page.

Returns: List envelope { object: "list", data: Broadcast[] }. Use the last item id as after on the next call.

const { data } = await publiq.broadcasts.list({ limit: 50 });
// next page:
const next = await publiq.broadcasts.list({ after: data[data.length - 1].id });

Listing is cursor-paginated: iterate by passing the last item id in after until data comes back empty. See Errors & pagination.

`broadcasts.send`

broadcasts.send(id, { scheduledAt? }) → Promise<Broadcast>

Dispatches a draft broadcast. Without scheduledAt, sending starts immediately; with scheduledAt, it schedules for a future UTC instant.

Parameters

Parameter	Type	Description
`id`Required	`string`	ID of the broadcast to send (path parameter).
`scheduledAt`Optional	`string`	ISO-8601 UTC instant, in the future, to schedule the send. Omit to send immediately.

Returns: The broadcast with status: "sending" (immediate) or status: "scheduled" (scheduled).

// send now
await publiq.broadcasts.send('bc_123');

// schedule for a future date
await publiq.broadcasts.send('bc_123', { scheduledAt: '2026-08-01T09:00:00Z' });

Creating and sending are two steps (create → review → send), which lets you schedule before dispatching. Suppressed recipients are skipped automatically. See Suppressions.

Examples show Node, Python and PHP. In Python methods are snake_case (e.g. cancel_run, from_spec) and take a dict; in PHP they are camelCase and take an associative array. Body keys are always camelCase (templateKey, firstName, scheduledAt) — API responses come back in snake_case.