List broadcasts
Returns the org's broadcasts, newest-first. A broadcast is a one-time,
point-in-time bulk send of a template version (or inline HTML) to a List
or Segment, with consent enforced at send. Create and send are available
under api.broadcasts.manage (POST /v1/broadcasts and
POST /v1/broadcasts/{id}/send); edit, reschedule, and cancel remain
dashboard-only. Cursors are opaque base64; stale or malformed cursors
silently fall back to page 1.
A broadcast sent without an opt-out topic degrades its unsubscribe link
to an account-wide opt-out (unsubscribe_all) — recipients can only leave
every send, not one stream. Prefer sending with a topic; the dashboard
requires acknowledging this before a topic-less send.
Query parameters
limit integer optional Page size (1–200). Default 50.
cursor string optional Opaque cursor returned from the previous page.
tag array optional Filter to entities carrying a tag with this full path name (repeatable; union/OR across values — the Gmail default). Pass untagged=true instead to return only entities with no tags. Applied before pagination.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
data array<object> required Each entry in data:
id string<uuid> required name string required content_mode string enum required The content source. template renders a pinned workspace template; inline sends caller-supplied raw HTML (not echoed back).
One of: template, inline
template_id string | null optional The template slug (file name) the broadcast renders — the same identifier GET /v1/templates exposes as slug, not an internal UUID. Null in inline mode.
template_version integer<int32> | null optional The pinned integer template version (null in inline mode).
audience_kind string enum required Whether audience_id references a List or a Segment.
One of: list, segment
audience_id string<uuid> required subject string required The broadcast owns the subject (overridable per send).
preview_text string optional from_identity string | null optional The explicit verified from-address, or null for the default no-reply@
default_template_data object optional DefaultTemplateData applied where a recipient lacks an attribute value.
topic_id string | null optional The topic name (the same identifier GET /v1/topics exposes), or null for a topic-less broadcast. Not an internal UUID.
schedule_at string<date-time> | null optional The scheduled UTC fire time, or null for a send-now broadcast.
state string enum required One of: draft, scheduled, sending, sent, partially_failed, cancelled
recipient_count integer<int64> | null optional Mailable snapshot size, stamped at send (null before send).
sent_count integer<int64> | null optional failed_count integer<int64> | null optional started_at string<date-time> | null optional completed_at string<date-time> | null optional created_at string<date-time> required updated_at string<date-time> required summary object | null optional The outcome rollup, present once a send has finalized the cached counts; null on a draft/scheduled broadcast that has never sent.
Fields of summary:
audience_size integer<int64> required Snapshot audience size before the consent filter.
mailable integer<int64> required Recipients that passed the consent filter (sent + failed).
sent integer<int64> required failed integer<int64> required filtered integer<int64> required Recipients dropped by the consent filter.
tags array<object> optional Org-side tags/folders applied to this broadcast (managed via the dashboard). Editable regardless of send state, so historical broadcasts stay organizable. Filter the collection with ?tag=.
Each entry in tags:
id string<uuid> required name string required Full folder path (e.g. Marketing/Newsletters).
key string required Normalized slug handle of the name.
color string optional Chip colour token (chart-1..chart-5), or empty.
description string optional created_at string<date-time> required updated_at string<date-time> required pagination object required Fields of pagination:
has_more boolean required next_cursor string | null optional code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json