Skip to content

0049. Broadcasts are one-off sends stored as generated workflows with a `once` trigger

  • Status: Proposed
  • Date: 2026-11-19
  • Amends: ADR 0016 (a once trigger at “now” fires at the next tick)

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:

  • once triggers (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.
  • A broadcast is a one-off send of one email to a set of customers at one time. broadcasts.create stores it as a workflow with kind: "broadcast" and generatedBy: "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 by workflowId.
  • Input:
    • content: from, subject, body inline, or a template reference once templates are their own resources; optional tracking (ADR 0046); optional experiment (ADR 0048);
    • recipients, exactly one of: customers (1 to 1,000 external IDs), audience (a saved audience ID), or condition (ADR 0045);
    • sendAt: "now", or { at: local date-time, timezone: "project" | "customer" | IANA zone };
    • optional goal and conversionWindow (ADR 0047), name, and a client idempotency key.
  • The generated definition: a once trigger at sendAt whose audience is { customers }, { inAudience }, or the condition; one send_email step; the optional goal; re-entry once. "now" is the time of the confirming call, and the occurrence fires at the next tick. With timezone: "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); otherwise validation_error explains 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.

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
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

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).

The confirmation preview (ADR 0050) adds:

  • budget_insufficient when eligible exceeds the workspace’s remaining plan budget for the period (ADR 0013) in cloud mode;
  • already_received with a count, when a broadcast with the same content hash reached some of these recipients in the last 7 days. Each broadcast stores content_hash (SHA-256 of the RFC 8785 canonical JSON of its subject and body, 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.

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.

  • “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.