Broadcasts
A Broadcast is an organizer-composed email to a segment of the organization — the whole org, one registration, one contest, or one division — sent to team managers only or everyone (managers plus rostered players). Sending is asynchronous: the API enqueues a fan-out and delivery counts are written back onto the broadcast document, which doubles as the send history.
All admin routes require an admin session and organization membership.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/broadcasts/d/preview | Resolve a segment’s audience without sending: { organization, segment } → { recipientCount, sample } |
| POST | /api/v1/broadcasts/d | Create a draft: { organization, segment, subject, body, bodyFormat? } |
| GET | /api/v1/broadcasts/d?organization=<id> | Send history, newest first (max 100) |
| GET | /api/v1/broadcasts/d/:id | One broadcast — poll while status is queued/sending |
| POST | /api/v1/broadcasts/d/:id/send | Enqueue the fan-out (202); 503 when the background worker is unavailable |
The segment object:
{ "scope": "division", "targetId": "<divisionId>", "audience": "managers" }scope is one of organization, registration, contest, division
(targetId required for all but organization); audience is managers or
everyone. Division and contest scopes match both confirmed and requested
placements, so teams awaiting admin confirmation are included.
bodyFormat is "html" for rich-text bodies (the admin compose editor sends
this) or omitted/"text" for plain text, which is escaped and rendered as
paragraphs.
status progresses draft → queued → sending → sent (or failed), with
recipientCount / sentCount / failedCount updated as delivery proceeds.
Sending is capped at 2,000 recipients per broadcast (400) and 10
sends per organization per day (429); an empty resolved audience also
returns 400. Teams marked withdrawn by an admin are excluded from the
audience.
Unsubscribe
Every broadcast carries a signed unsubscribe link and a List-Unsubscribe
header. GET /api/v1/unsubscribe?token=<signed> (public) records the opt-out;
suppressed addresses are excluded from every later broadcast for that
organization. Transactional email (receipts, waiver requests) is unaffected.