Broadcasts API

A one-off send: its own email, a segment, and a time. Membership is resolved when it sends, not when it's scheduled.

Method & path	What it does
`GET /api/v1/broadcasts`	All of them. Filter with `?status=`.
`POST /api/v1/broadcasts`	Compose one. Body: `name`, `segment_id`, `email_source`, `email_id`, `delivery`.
`GET /api/v1/broadcasts/:id`	One, with its email, segment and stats.
`PATCH /api/v1/broadcasts/:id`	Update `name`, `segment_id`, `delivery`.
`DELETE /api/v1/broadcasts/:id`	Only a draft or a canceled one. `409` otherwise.
`POST /api/v1/broadcasts/:id/replace_email`	Swap the email, while it's still a draft or scheduled.
`POST /api/v1/broadcasts/:id/schedule`	Body: `send_at`.
`POST /api/v1/broadcasts/:id/send_now`	Send it. Answers with the recipient count.
`POST /api/v1/broadcasts/:id/cancel`	Cancel it and everything it has queued.

A broadcast never shares its email

email_source is required and accepts only scratch or copy. shared is refused with 422, on the server, rather than trusted to whichever client is asking.

POST /api/v1/broadcasts
{ "email_source": "copy", "email_id": 42, "segment_id": 3, "name": "July announcement" }

What one broadcast sent should stay what it sent. If a broadcast pointed at a shared library row, editing a sequence step months later could silently rewrite the record of a send that already went out — so every broadcast gets a row of its own, blank or copied. This is also why emails/ in a definitions repo fills up with rows that exist for one send: expected, not drift, and the used-in filter is how you tell them apart.

The email can only be swapped or forked while the broadcast is still a draft or scheduled. Once it's sending or sent, its email is history.

Delivery

Value	What happens
`mimeo`	Fans out through the ordinary paced queue. Guards, send windows and tracking all apply, and the broadcast gets a full report. Works with any adapter.
`provider`	Hands off to the provider's own bulk pipeline, where offered — it arrives as an unapproved draft to review and send there. Because the provider does the sending, it records opens and clicks, so this broadcast's report here stays empty.

Only offered when the configured adapter declares broadcast_send. An adapter without a bulk pipeline isn't a limitation — the fan-out path is the one with the better reporting anyway.

Audience

Resolved at send time from the segment's live rules, not stored when you schedule. A segment that grows between now and Friday means more recipients on Friday. Unsubscribed people are excluded, and the standing suppression guard checks again for every individual send.

Broadcasts are runtime rather than authoring, so they don't appear in a definitions repo — though the emails they mint do.