Skip to content

0050. Every action that can start sends is confirmed on the server: a preview with an exact count and a token, then a committing call

  • Status: Proposed. That every action that can start sends needs a server-side preview-then-confirm in every workspace, including where approval is off, is the maintainer’s decision of 2026-11-19, Accepted and not reopened.
  • Date: 2026-11-19
  • Amends: ADR 0005 (a server-side confirmation of sending actions exists in every workspace), ADR 0016 (a confirmation token returns, on the committing action), ADR 0019 (actions declare startsSends and a preview), ADR 0031 (meets the confirmation precondition of “No real mail yet”), ADR 0044 (where approval is off, a sending version goes live on the confirming call), ADR 0033 (every action that creates a send approval is confirmed first)

The maintainer decided on 2026-11-19 that any action that can start real sends needs a server-side preview and confirmation, even in workspaces where send approval is off, so that everything can be done from Claude Code without the AI committing something it never previewed.

Facts:

  • ADR 0005 requires user confirmation of sending actions, enforced on the server, because MCP clients may ignore tool annotations. ADR 0016 first used a preview token; ADR 0033 replaced it with a human approval through a mailed link; ADR 0044 made approval optional and off by default and amended ADR 0005 so that “elsewhere there is no server-side confirmation”.
  • ADR 0031: until the server-side confirmation exists, apps/workers refuses every email provider but the fake one (assertEmailProviderAllowed). ADR 0044 adds that on the managed service no workspace with approval off sends real mail until plan-limit budgets, sender protection, pause, and rollback are built.
  • The server cannot tell whether a person read a preview: the credential that asks for it can confirm it. Only a channel the credential does not reach (ADR 0033’s mailed link) proves a person decided.
  • invokeApiAction (core/src/actions/invoke.ts) admits the caller, checks scope and role, and runs the handler; defineApiAction declares inputs, outputs, and ErrorCodes (ADR 0019, ADR 0041).
  • Audience counts above AUDIENCE_SYNC_COUNT_LIMIT are jobs, not request-time answers (ADR 0045).

An action is startsSends: true in the registry when it can start real sends: broadcasts.create (ADR 0049); workflows.activate (activation and publishing); workflows.rollback, workflows.resume, and sending.resume (ADR 0044); and experiments.conclude (ADR 0048). A registry test fails if an action that can start sends lacks the flag; each later ADR that adds one says so.

  • A startsSends action declares previewSends(ctx, input) → Preview | null. null means this call starts no sends (activating a version with no send step, concluding without ending a holdout), and the action runs at once.
  • defineApiAction derives, for every such action:
    • the optional input field confirmation (a token string);
    • the output union, discriminated by status: "confirmation_required" (preview, confirmation: { token, expiresAt }), "confirmation_pending" (preview so far, progress, no token), and the action’s own output with status: "done" (whose own result may say awaiting_approval);
    • the new ErrorCode confirmation_invalid (409), whose body carries a fresh preview and, when the count is exact, a new token.
  • invokeApiAction, after admit and the scope and role check:
    1. without confirmation: runs previewSends; if it returns a preview with exact counts, it stores a token and returns confirmation_required; if a count is still running, it returns confirmation_pending and the client calls again;
    2. with confirmation: runs the action’s command, which consumes the token in the same project-store transaction as the commit (look up by hash, check expiry, binding, and unused, mark used with the result reference). If the check fails, nothing is written and the call answers confirmation_invalid.
  • The preview needs the same scope and role as the commit, so a caller who cannot commit cannot preview.
  • cl_conf_ followed by 256 random bits from IdGenerator.secret(). Only its SHA-256 hash is stored, in the project store, in send_confirmations. cl_conf_ is added to CREDENTIAL_PREFIXES (ADR 0032).
  • It binds:
    • the credential identity: the API key’s ID, the grant’s ID, or the session’s user ID;
    • the action name;
    • the canonical input: the action’s zod-parsed input without confirmation and without the client idempotency key, serialized as RFC 8785 canonical JSON and hashed with SHA-256;
    • the workspace’s sendApprovalRequired value at preview time;
    • the preview’s bound values: for workflows, the version’s definition hash, the re-entry policy, and the live version; for broadcasts and time triggers, the exact eligible count; for workflows.resume and sending.resume, the number of held messages; for workflows.rollback, the target version and the number of runs and messages it withdraws. A commit whose recomputed bound values differ answers confirmation_invalid with a fresh preview.
  • Valid for SEND_CONFIRMATION_TTL (configuration, proposed 15 minutes), once.
  • Replays. The same call repeated with a consumed token and the same input returns the first call’s result, so a client retry does not commit twice. A consumed token with a different input answers confirmation_invalid.
  • Exact counts only. A token is issued only when every count it binds is exact. When a bound count is above AUDIENCE_SYNC_COUNT_LIMIT, so it runs as a count job (ADR 0045), the calls answer confirmation_pending with the job’s progress until it is done, whatever the sendAt. Within the limit the count is exact in the request and the token is issued at once.
  • Recount at commit applies only to sendAt: "now", when the project is within the sync count limit: a recount that differs from the bound count by more than SEND_CONFIRMATION_DRIFT (configuration) answers confirmation_invalid. Above the limit, the exact count at most SEND_CONFIRMATION_TTL old stands. Later occurrences of schedule and once triggers are bounded by ADR 0016’s per-occurrence recipient cap, not by the confirmed count.
  • Load. Previews and token issuance are rate-limited per project (SEND_CONFIRMATION_RATE_LIMIT), and tick deletes expired and consumed tokens after a grace period.
  • Recipients: matching, eligible, excluded counts by reason (including condition_unknown, with fullyKnownFrom, ADR 0045), exact, and up to 5 sample external IDs (ADR 0045). For an event-triggered workflow, the number of customers who performed the trigger event in the last 30 days, labelled an estimate and not bound.
  • Time triggers: what workflows.preview_triggers returns (next fires per timezone bucket, fallbacks, DST adjustments, past-due skips).
  • Content: each send step’s from, subject, and body rendered for the first sample recipient with variables substituted, and every experiment arm, as data a client shows as text.
  • Resumes and rollbacks: the held or withdrawn counts above.
  • Context: the send time in UTC and the given zone; the recipient cap and whether the count exceeds it; whether the workspace requires approval; warnings (sender_not_verified, recipient_cap_exceeded, budget_insufficient, already_received, a count much larger than the project’s usual sends).
  • The confirmation is server-side and cannot be skipped by a client that ignores annotations: no sends start without a preview of exactly what is committed, returned to the same credential minutes before.
  • It does not prove a person saw the preview: an AI can call twice. Tool descriptions and llms.txt instruct the assistant to show the preview and wait for the user’s answer, and Claude Code asks before a destructive tool; neither is enforced.
  • Where a workspace requires approval (ADR 0033, ADR 0044), the confirmation comes first, and the confirmed action creates the send approval as today; approval stays the only proof that a person decided, optional and off by default.
  • Where approval is off, a sending version goes live on the confirming call, without approval and without mail. This replaces ADR 0044’s “goes live when workflows.activate is called” with “goes live on the confirming call of workflows.activate”, at the maintainer’s decision of 2026-11-19, and replaces the “Elsewhere there is no server-side confirmation” of ADR 0044’s amendment of ADR 0005.
  • With this built, ADR 0031’s precondition is met: every action that starts sends is confirmed on the server, in every workspace.
  • assertEmailProviderAllowed is removed in the change that makes real sending go live, once the rest of B4’s deploy gate holds: on the managed service, plan-limit budgets (ADR 0013), sender protection (ADR 0024), pause and rollback (ADR 0044), and the SES go-live runbook.
  • One mechanism in the dispatcher covers every sending action on REST, MCP, and the dashboard, which shows the preview as its confirmation dialog.
  • Every sending action costs one more round trip, more while a large count runs. Tests use a core/testing helper that does both calls.
  • The confirmation protects against a commit that was never previewed, a stale preview, and a retried commit; it does not protect against an assistant that confirms without asking. Workspaces that need that turn approval on.
  • MCP OAuth, so claude.ai, ChatGPT, and Claude Code connect without an API key, is in the first release (the maintainer’s decision of 2026-11-20), Proposed in ADR 0051. The confirmation binds a grant’s ID like a key’s: a token previewed through a grant is confirmed only through the same grant, survives an access-token refresh, and a reconnect, which creates a new grant, needs a new preview.
  • Open: a published Customer.lite skill or instructions for Claude Code, with llms.txt and tool descriptions, that steer the assistant to broadcasts, saved audiences, and reports, and to showing previews; MCP elicitation where a client supports it.

G1 builds the confirmation for the one sending action that exists, workflows.activate. Where the build differs from the Decision above, this section records how and why. The other actions in Which actions get the declaration when they are built.

  • The declaration is an object, not a flag. An action declares startsSends: { preview, resultReference, replay }, and declaring it is what makes the action sending. preview is the previewSends above. resultReference takes the reference a retry is answered from out of the action’s output. replay answers a retry from that reference with the current view of what was committed, not with the first response, so one-time secrets such as approvalLink are not returned again. A startsSends action must have the project target, because its project store holds the tokens. invokeApiAction’s non-project path, run, refuses such an action, so no path runs its handler without the confirmation step.
  • The output is a flat object, not a union. It is { status: "confirmation_required" | "done", preview?, confirmation?, result? }, and the action’s own output is under result. MCP tool output schemas must be objects, and the workflow view has its own status, which would clash with the envelope’s. confirmation_pending and its progress come with the first count job (G6) and add a value to the status enum, which is a breaking change for clients that check the value exhaustively.
  • Bound values and display content are separate. The preview returns content, which is shown, and bound, which the token hashes. The committing command recomputes only bound, from the records it already reads. It does not repeat the preview’s queries, such as the 30-day trigger-event count.
  • Where the result reference is recorded: after the commit, in its own command. The token is used, conditionally and once, in the commit transaction. runConfirmed, which invokeApiAction runs for every credential’s project call, records the result reference after the action’s handler returns. If the commit succeeds but the handler then fails (for example, approval_delivery_failed when no approval link could be delivered), the token is used and nothing is recorded. A retry with that token is then refused with confirmation_invalid and a fresh preview, and confirming that preview requests the approval again. That re-mints only the links that were never delivered. Recording the reference in the commit transaction would instead replay a pending approval whose links nobody received. Both paths have contract tests. An output that used no token, such as a version that went live without sends, has a null reference, and nothing is recorded for it. The record step can also fail on its own after a successful commit, for example from a transient store error. The call then answers an internal error, and its retry is refused like any used token with no reference. Confirming the fresh preview requests the approval again, which ADR 0033’s request handles without starting a second approval.
  • Bound values for workflows.activate. The version, its definition hash, the workflow’s status, re-entry policy and live version, and approvalRequired.
  • Single use. The token is marked used with a conditional update (… WHERE used_at IS NULL). If the update changes no row, the command throws and its transaction rolls back. Like every command, the token check relies on the executor serialising a project’s commands. An executor over a store with concurrent transactions (Postgres) must keep that guarantee, for example with an advisory lock per project; the conditional update is defence in depth. The token is used after the approval request’s writes, in the same transaction. A request over the daily link cap writes nothing and leaves the token usable, and a failed use throws, so the request’s writes roll back with it.
  • The sweep runs when a token is issued, not in tick. Each issuance first deletes tokens that expired more than an hour ago, which keeps a used token for its replay grace period. The table therefore holds about an hour of issuance plus the TTL, without a scheduled job.
  • Rate limit. The limit is checked before the preview is computed, so a project over SEND_CONFIRMATION_RATE_LIMIT costs no preview queries. Over the limit, a call that starts no sends still runs, and one that would start sends answers rate_limited. A confirmation_invalid refusal then carries no fresh preview.
  • approvalRequired is the constant true. It stays constant until ADR 0044’s sendApprovalRequired setting exists. It is already among the bound values, so adding the setting changes no token format.
  • The registry test is a list. It lists the registry’s sending actions and fails if one of them lacks the declaration. It does not detect from code whether an action can start sends, so each later ADR that adds a sending action adds it to the list.
  • Credential identity. The token binds api_key:<key ID> or session:<user ID>. A key’s ID is its stored ID (ADR 0041’s key management amendment); before keys had one, it was derived from the key’s hash. An OAuth grant (ADR 0051) binds oauth_grant:<grant ID>, so a confirmation survives a token refresh and no other grant of the same user can use it; this is built.
  • The 30-day estimate. It is counted with an index on events (project_id, name, received_at, customer_id) that covers the query. Migration 10 builds that index in the migration’s transaction, which reads each project’s event rows once before the store serves commands.