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); composed places a body (not echoed back) into layout.
One of: template, inline, composed
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 outside template mode.
layout string | null optional Composed mode — the layout the body is placed into: a layout template's slug, or builtin for the SendOps built-in. Resolved when the broadcast was created, so a later change of the org's default does not move it. Null outside composed mode, and when the layout template has since been deleted.
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 required The List or Segment id. Responses echo the id; either the id or the org-unique key is accepted on the way in.
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@Name <address> supplied at create is split on the way in.
from_name string | null optional The sender display name shown in the recipient's inbox, or null when the organization's name is used as the label.
reply_to string | null optional Where replies go, or null when the broadcast has none — then no Reply-To header is sent and replies reach the from-address. Stored normalized: a bare address, or Name <address> when a display name was supplied.
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 failed: the send could not start and nothing was sent; send it
again with POST /v1/broadcasts/{id}/send. paused: the send
stopped part-way on an SES account or configuration problem
(failure_reason says which) and is resumed from the dashboard once
it is fixed. partially_failed: the send completed, but some
recipients failed or their delivery could not be confirmed
(unknown_count).
One of: draft, scheduled, sending, sent, partially_failed, cancelled, failed, paused
failure_reason string | null optional Why a failed or paused broadcast stopped, as a plain-English sentence safe to show to people. Null in every other state.
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 unknown_count integer<int64> | null optional Recipients whose delivery could not be confirmed. They are never sent again automatically. Null for a broadcast sent before this count existed, and until a send completes.
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 or failed 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 and were attempted (sent + failed + unknown).
sent integer<int64> required failed integer<int64> required unknown integer<int64> required Recipients whose delivery could not be confirmed. 0 for a broadcast sent before this count existed.
filtered integer<int64> required Recipients dropped by the consent filter.
replies integer<int64> required How many distinct people replied to this broadcast, auto-replies excluded. The odd one out here: the other six are derived from the cached counts, this one is counted live from the inbound message log on every detail read, because replies keep arriving for days after a send is finalized. Requires inbound receiving; 0 without it.
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 requires array<object> optional Everything this definition still depends on, with each dependency's state. Present on the write responses and on the detail read (the polling surface); absent on the collection read. An empty array means nothing is outstanding — see V1Requirement.
Each entry in requires:
kind string enum required The namespace key is looked up in. Branch on this; never parse detail.
One of: template, segment, list, topic, identity, channel, attribute, activity_property, asset
key string required The identifier as the definition names it — a template name, a segment id or key, a from-address. Empty for a requirement about the ABSENCE of a reference: a send with no topic at all names no topic.
status string enum required ok — resolves and is usable now.
missing — nothing in this organization answers to that key. Correct
the reference, or create the thing.
not_ready — it exists, in a state that cannot be used yet. Usually
a wait, and retrying the identical request is the move. Treating this
as missing sends you hunting for a typo that is not there.
One of: ok, missing, not_ready
detail string required The state, in the words that say which state — deploy_state=pending, member_count=null (evaluation queued). For display and logs; do not parse it.
fix string required The call that clears this requirement, as an HTTP route where there is one and as a plain instruction where there is not (a template deploy is waited for, not called). Empty on an ok entry.
pagination object required Fields of pagination:
has_more boolean required next_cursor string | null optional validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json