0049. Broadcasts are one-off sends stored as generated workflows with a `once` trigger
- Status: Proposed
- Date: 2026-11-19
- Amends: ADR 0016 (a
oncetrigger at “now” fires at the nexttick)
Context
Section titled “Context”The maintainer said on 2026-11-19 that everything should be configurable from Claude Code: “send this email to this user today” or “send this email to this group of users tomorrow” should create the workflow on its own and set it up. Today the AI would write a definition with a time trigger, save it, and activate it, for what the user thinks of as one send.
Facts:
oncetriggers (ADR 0016) already send to an audience at one time, with a snapshot at the occurrence, a per-occurrence recipient cap, catch-up windows, and the usual rechecks, budget, and step logs.- Workflows have stop (ADR 0017), pause and rollback (ADR 0044), and reports (ADR 0047).
- Every action that can start sends goes through the preview-then-confirm of ADR 0050.
Decision
Section titled “Decision”What a broadcast is
Section titled “What a broadcast is”- A broadcast is a one-off send of one email to a set of customers at one time.
broadcasts.createstores it as a workflow withkind: "broadcast"andgeneratedBy: "broadcasts.create", and makes it live in the same call (after the confirmation of ADR 0050, and an approval where the workspace requires one). Its ID is the workflow’s ID; reports filter it byworkflowId. - Input:
- content:
from,subject,bodyinline, or a template reference once templates are their own resources; optionaltracking(ADR 0046); optionalexperiment(ADR 0048); - recipients, exactly one of:
customers(1 to 1,000 external IDs),audience(a saved audience ID), orcondition(ADR 0045); sendAt:"now", or{ at: local date-time, timezone: "project" | "customer" | IANA zone };- optional
goalandconversionWindow(ADR 0047),name, and a client idempotency key.
- content:
- The generated definition: a
oncetrigger atsendAtwhoseaudienceis{ customers },{ inAudience }, or the condition; onesend_emailstep; the optional goal; re-entryonce."now"is the time of the confirming call, and the occurrence fires at the nexttick. Withtimezone: "customer", each customer gets that local time, as ADR 0016 defines. - An experiment with a holdout is accepted only with a
goal, as in any workflow (ADR 0048); otherwisevalidation_errorexplains why. - “The same email to this one user” is a broadcast to
customers: ["that-id"]. It is marketing-stream mail with an unsubscribe link and every recheck. A transactional send API, which would not be, remains open.
Status
Section titled “Status”Derived from the workflow, its occurrence, and its messages, never stored separately:
| Status | When |
|---|---|
awaiting_approval |
a send approval is pending (ADR 0033) |
scheduled |
live, occurrence not yet fired |
sending |
fired, and some messages are still queued, waiting, or sending |
sent |
fired, and every message is final |
missed |
the occurrence did not fire: skipped:missed_window (for example an approval that came after the catch-up window) or skipped:recipient_cap |
cancelled |
stopped by broadcasts.cancel or workflows.stop. Terminal |
Workflow actions on a broadcast
Section titled “Workflow actions on a broadcast”| Action | On kind: "broadcast" |
|---|---|
workflows.get, workflows.list (marked kind and generatedBy), liveChanges.list, workflows.preview_triggers, reports |
as for any workflow |
workflows.upsert |
conflict: a broadcast cannot be edited; cancel it and create another |
workflows.activate |
conflict: broadcasts.create makes it live |
workflows.rollback |
conflict: a broadcast has one version |
workflows.pause, workflows.resume |
as for any workflow; resume is confirmed (ADR 0050) |
workflows.stop |
the same as broadcasts.cancel |
experiments.conclude |
as for any workflow |
Cancelling
Section titled “Cancelling”broadcasts.cancel { id } stops the broadcast (ADR 0017): before the occurrence fires, nothing is sent; after, messages not yet claimed are skipped (skipped:workflow_stopped) and those already sending follow the send state machine. It only reduces mail, so it needs no confirmation and is open to members, like workflows.pause. Cancelling a cancelled or sent broadcast changes nothing (idempotent).
Preview warnings specific to broadcasts
Section titled “Preview warnings specific to broadcasts”The confirmation preview (ADR 0050) adds:
budget_insufficientwheneligibleexceeds the workspace’s remaining plan budget for the period (ADR 0013) in cloud mode;already_receivedwith a count, when a broadcast with the same content hash reached some of these recipients in the last 7 days. Each broadcast storescontent_hash(SHA-256 of the RFC 8785 canonical JSON of itssubjectandbody, one per variant), indexed with its creation time; the check joins the recipients’ messages of the last 7 days on it. This catches a create repeated after a cancel or by mistake.
Actions
Section titled “Actions”api actions with full parity (ADR 0005), target: "project", principal: "any" (ADR 0041):
| Action | Scope, role | Annotations |
|---|---|---|
broadcasts.create |
send, admin |
destructive; startsSends (ADR 0050) |
broadcasts.list, broadcasts.get |
read, member |
read-only |
broadcasts.cancel |
write, member (reduce-only) |
idempotent |
Tool descriptions and llms.txt steer the assistant to broadcasts.create for one-off sends; workflows remain for delays, conditions, and event triggers.
Consequences
Section titled “Consequences”- “Send this to this user today” and “send this to this group tomorrow” are one tool call plus its confirmation, with the same logs, rechecks, budget, and reports as workflows.
- Broadcasts appear in the workflow list; the dashboard can filter them by
kind. - Open: a transactional send API; templates as their own resources.