Broadcasts tools
Schedule a one-time send to an audience and read its results.
create_broadcast
Schedule a ONE-TIME broadcast: a single email sent once, at an absolute time, to the targeted audience's active non-suppressed contacts (omit audience_key/audience_id to send to everyone). Membership timing: contacts who ENTER the audience before it fires are included (additions freeze at fire time); contacts who LEAVE — or whose data stops matching a dynamic audience's rule — are excluded live as it sends. Provide template_key or template_id (from list_templates) + scheduled_for (ISO 8601 with offset, e.g. 2026-09-01T09:00:00-04:00) which MUST be in the future. Use this for seasonal/calendar marketing; use create_sequence for relative drip cadences.
template_keystring- Template to send, by key. Provide exactly one of template_key or template_id.
template_idstring- Template to send, by id. Provide exactly one of template_key or template_id.
scheduled_forstringrequiredaudience_keystring | null- Target audience by slug (or the literal 'everyone'). Provide at most one of audience_key/audience_id; omitted or null = everyone.
audience_idstring | null- Target audience by uuid (XOR with audience_key).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
update_broadcast
Reschedule a broadcast (scheduled_for — ISO 8601 with an explicit offset, e.g. 2026-09-01T09:00:00-04:00 or …Z, in the future), swap its template (template_key or template_id), and/or retarget its audience (audience_key XOR audience_id; null resets to everyone). Allowed ONLY while the broadcast is still 'scheduled' — once it starts sending it is frozen, and TARGETING is frozen once it has ever fired (the recipient snapshot): cancel and re-create to send to a different audience.
broadcast_idstringrequiredtemplate_keystring- Swap to this template by key (optional). Provide at most one of template_key/template_id.
template_idstring- Swap to this template by id (optional). Provide at most one of template_key/template_id.
scheduled_forstringaudience_keystring | null- Retarget by slug/'everyone' (XOR with audience_id; null resets to everyone).
audience_idstring | null- Retarget by uuid (XOR with audience_key; null resets to everyone).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
delete_broadcast
Cancel a broadcast. While 'scheduled' it never sends; while 'sending' the rest of the list is never sent (emails already sent can't be recalled). A 'sent' or 'canceled' broadcast can't be canceled.
broadcast_idstringrequiredteamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
list_broadcasts
List the team's broadcasts (upcoming + past) with status + scheduled_for — the forward calendar of one-time sends. Each row carries its target `audience` ({id, name, kind, member_count}; kind 'default' = everyone). Pass status to return only one lifecycle state.
statusenum- scheduled | sending | sent | canceled
Filter to one lifecycle state (default: all statuses). teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
get_broadcast
Fetch one broadcast by id: status, scheduled_for, template_id, fired_at, and timestamps. Use get_broadcast_stats for delivery/engagement aggregates.
broadcast_idstringrequiredteamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
get_broadcast_stats
Aggregate stats for one broadcast over an optional date range (default all-time): recipients, sent, delivered, opens/unique_opens, clicks/unique_clicks, bounced, complained, unsubscribed, plus replied/failed + channel for SMS broadcasts.
broadcast_idstringrequiredrangestring- Preset window for the volume/engagement metrics + Trend sparkline (recent | today | yesterday | last_7d | last_30d | this_month | last_month | this_year | last_year | all; default 'recent'). Point-in-time KPIs (active now / completed) are never windowed. For a custom window pass from/to instead of range.
fromstring- Custom window start, ISO 8601 (overrides range). Optional open lower bound.
tostring- Custom window end, ISO 8601 (overrides range). Optional open upper bound.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.