Broadcasts

Every broadcast in the account, newest first. Not paginated — the envelope's next_cursor is always null and has_more always false — so narrow with the filters rather than expecting pages.

Rows are lean by default. Each row drops body_html, body_mjml, body_text and template_snapshot (30–100KB each) and reports has_body_html / has_body_mjml / has_body_text / has_template_snapshot instead, and it replaces variants with variant_count + variant_ids. ?full=true returns everything, for every row — reach for GET /api/broadcasts/{id} first if you only need one.

Archived broadcasts are excluded unless you ask for them, and retired triggered broadcasts never appear here at all; fetch those by ID.

Creates a broadcast in draft. Nothing is sent — scheduling is a separate, separately-scoped call (POST /api/broadcasts/{id}/schedule, broadcasts:schedule).

Name the dependencies by public key, not by UUID. email_type_key, mta_config_key, include_segment_keys, exclude_segment_keys, sending_identity_emails and content.template_slug are resolved server-side; an unknown key is rejected (INVALID_EMAIL_TYPE, INVALID_MTA_CONFIG, INVALID_SEGMENT, INVALID_SENDING_IDENTITY, INVALID_TEMPLATE) rather than silently ignored. The *_id variants also exist but they are the browser session's form; keys survive a re-sync, UUIDs do not.

email_type_key is required for API-key callers even though the JSON Schema does not mark it so — omitting it returns 400 INVALID_EMAIL_TYPE. content.subject is required, and so is one of content.body_html / content.body_mjml, unless you are in template mode (content.template_slug + content.template_binding), where the server renders the bodies at save time.

Variants must number at least two, each with id, name, a positive weight and at least one content_overrides field, or the call fails with INVALID_VARIANTS. Per-variant sending_identity_id or mta_config_id is rejected (VARIANT_DELIVERY_OVERRIDE_UNSUPPORTED), as is any split_test_config (ADVANCED_SPLIT_TEST_UNSUPPORTED) — holdout/winner workflows are console-only.

Retries. Send an Idempotency-Key header and a replay returns the original 201 body with idempotency-replay: true instead of creating a second broadcast. The key must match ^[A-Za-z0-9_-]{8,128}$ and is remembered for 24 hours; a key that does not match the pattern is ignored silently, so a malformed key gives you no protection and no error.

The complete broadcast — always the full shape, never the list endpoint's lean form.

Beyond the stored row this adds live send progress (total_recipients, sent, failed, progress_pct) and view_model, whose available_actions tells you which lifecycle calls are legal right now and whose schedule_readiness names, guard by guard, what a draft is still missing. Prefer reading those over inferring legality from status.

Drafts only. Once a broadcast has been scheduled the row is frozen and this returns 409 NOT_DRAFT; call POST /{id}/unschedule first to bring it back to draft.

A partial update: fields you omit are left alone. Fields you send REPLACE what is stored — tags and metadata are overwritten wholesale, not merged, which is the opposite of the contact upsert's behaviour. The same public-key reference fields work here as on create.

Sending sending_identity_ids: [] is rejected with NO_IDENTITY; send null to hand identity selection back to the allocator. split_test_config and per-variant delivery overrides are rejected here too.

Permanently removes the broadcast row. Irreversible — there is no undelete and no trash.

Drafts only: anything that has been scheduled or sent returns 409 NOT_DRAFT, deliberately, so a send's record survives for reporting. To get a finished broadcast out of the way use POST /{id}/archive, which is reversible.

Moves the draft to scheduled and commits it to send. This is the call that causes mail to go out, which is why it needs broadcasts:schedule rather than broadcasts:write.

Legal from draft only; anything else is 409 INVALID_TRANSITION. Four guards must pass first — at least one include segment, an MTA config, a content.subject, and a valid split-test config — and a failure names the guard. GET /api/broadcasts/{id} reports the same checks up front in view_model.schedule_readiness.

Three failures worth handling separately: 422 TRACKING_NOT_LIVE when a sending identity's tracking domain has not gone live (its unsubscribe and click links would be dead), 422 when the delivery window cannot be satisfied by the warming capacity available, and 402 when the account's plan does not permit sending yet. None of them are retryable without changing something first.

Set scheduled_at before you call this. Scheduling does not supply a default: the dispatcher picks up broadcasts whose scheduled_at has passed, and a null one never matches that comparison — the broadcast sits in scheduled indefinitely. A scheduled_at already in the past starts on the next tick.

Rewrites which days a multi-day spread send skips, then re-projects the remaining schedule immediately.

Despite the name this is not "change the send time". It only takes skipped_dates, and it applies only to a broadcast that is actively sending on a spread plan: any other status is 409 NOT_SENDING, and a send with no spread plan is 409 NO_SPREAD_PLAN. To move a send that has not started, unschedule it, set scheduled_at, and schedule it again.

skipped_dates is the complete replacement list, not a delta — days you leave out become sending days again. Only FUTURE days can be newly skipped; adding today or a past day returns 400 INVALID_SKIP. Un-skipping is always allowed. "Today" is the tenant's local day, not UTC.

Stops dispatching. Legal from sending only — 409 INVALID_TRANSITION otherwise, including from scheduled (use unschedule for one that has not started).

Queued jobs are drained, claimed recipients go back to pending, and a spread plan is held. Mail already handed to the provider is gone and cannot be recalled; pausing only affects what has not been dispatched. Warming day-bookings are released, so a long pause can mean the resumed send has to compete for capacity again.

A split test in its evaluation dwell phase cannot be paused.

Returns the broadcast to sending and re-enqueues everyone still pending. Legal from paused only.

Only a plan held because you paused is released; a plan the platform held for collapsed capacity or a paused domain stays held and recovers on its own once the underlying condition clears. If re-enqueueing fails the broadcast is rolled back to paused and the call errors, so a failed resume never leaves it stranded mid-state.

Stops the send for good. Legal from scheduled, sending or paused; a draft has nothing to cancel (delete it instead) and a completed broadcast cannot be undone.

This is the call that stops a send already in flight: it drains queued jobs, releases claimed recipients, and drops every spread batch that has not fired. Batches that already went out are kept for reporting. Mail the provider has already accepted is on its way and cannot be recalled.

A cancelled broadcast can be returned to draft from the console, but only while no recipient has been sent or failed — after the first send that door is closed.

Takes a broadcast out of the send queue and makes it editable again.

Legal from scheduled only. A broadcast that has started sending returns 409 INVALID_TRANSITION — this is not the call for stopping a live send; cancel is.

The preview delivery plan is discarded and warming day-bookings are released, so re-scheduling recomputes the audience and the day plan from scratch against whatever capacity is free then. A broadcast unscheduled and re-scheduled is not guaranteed the same delivery calendar.

Hides a finished broadcast from the default list. Housekeeping only — nothing is deleted, reporting keeps working, and POST /{id}/unarchive puts it back.

Only completed, failed and cancelled broadcasts can be archived (409 NOT_ARCHIVABLE); archiving one that already is returns 409 ALREADY_ARCHIVED. To see archived rows again pass ?archived=true or ?archived=only on the list endpoint.

Clears the archive flag and returns the broadcast to the default list. The lifecycle status is untouched — an unarchived broadcast is still completed or cancelled, not a draft. A broadcast that is not archived returns 409 NOT_ARCHIVED.

Archives up to 100 broadcasts in one call.

Partial success is the normal outcome, and it is reported as 200, not an error. Each ID is attempted independently; any that fails — wrong status, already archived, does not exist, belongs to another account — lands in skipped with no reason attached. Read the response arrays, not the status code, and archive individually if you need to know why something was refused.

Replays the broadcast's stored template binding against the template's CURRENT schema and returns what the binding would become. Nothing is written — despite being a POST this is a pure read. To keep the result, send merged_binding back through PUT /api/broadcasts/{id}.

Use it when a template has changed since the draft was authored and you need to know which parameters, sections or slots were added, removed or retyped before re-saving.

Only applies to template-mode broadcasts: one authored with inline HTML returns 400 NOT_TEMPLATE_MODE.

Sends the broadcast to a handful of your own addresses so a human can read it before it goes out. Real mail, hence broadcasts:schedule.

The cap is on addresses, not on messages. Every address receives one copy per variant per sending identity, so five addresses across three variants and two senders is thirty emails. Each subject is prefixed [TEST: <variant> · <sender>] so the copies are distinguishable in one inbox. That is the difference from seed-send, which sends a single version to a seed list for placement testing.

Like a seed send, it publishes no events and creates no recipient rows, so it never shows up in the broadcast's report.