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
startsSendsand 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)
Context
Section titled “Context”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/workersrefuses 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;defineApiActiondeclares inputs, outputs, andErrorCodes (ADR 0019, ADR 0041).- Audience counts above
AUDIENCE_SYNC_COUNT_LIMITare jobs, not request-time answers (ADR 0045).
Decision
Section titled “Decision”Which actions
Section titled “Which actions”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.
Enforced by dispatch, not by handlers
Section titled “Enforced by dispatch, not by handlers”- A
startsSendsaction declarespreviewSends(ctx, input) → Preview | null.nullmeans this call starts no sends (activating a version with no send step, concluding without ending a holdout), and the action runs at once. defineApiActionderives, 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"(previewso far,progress, no token), and the action’s own output withstatus: "done"(whose own result may sayawaiting_approval); - the new
ErrorCodeconfirmation_invalid(409), whose body carries a fresh preview and, when the count is exact, a new token.
- the optional input field
invokeApiAction, afteradmitand the scope and role check:- without
confirmation: runspreviewSends; if it returns a preview with exact counts, it stores a token and returnsconfirmation_required; if a count is still running, it returnsconfirmation_pendingand the client calls again; - 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 answersconfirmation_invalid.
- without
- The preview needs the same scope and role as the commit, so a caller who cannot commit cannot preview.
The token and what it binds
Section titled “The token and what it binds”cl_conf_followed by 256 random bits fromIdGenerator.secret(). Only its SHA-256 hash is stored, in the project store, insend_confirmations.cl_conf_is added toCREDENTIAL_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
confirmationand without the client idempotency key, serialized as RFC 8785 canonical JSON and hashed with SHA-256; - the workspace’s
sendApprovalRequiredvalue 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
eligiblecount; forworkflows.resumeandsending.resume, the number of held messages; forworkflows.rollback, the target version and the number of runs and messages it withdraws. A commit whose recomputed bound values differ answersconfirmation_invalidwith 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 answerconfirmation_pendingwith the job’s progress until it is done, whatever thesendAt. 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 thanSEND_CONFIRMATION_DRIFT(configuration) answersconfirmation_invalid. Above the limit, the exact count at mostSEND_CONFIRMATION_TTLold stands. Later occurrences ofscheduleandoncetriggers 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), andtickdeletes expired and consumed tokens after a grace period.
The preview
Section titled “The preview”- Recipients:
matching,eligible, excluded counts by reason (includingcondition_unknown, withfullyKnownFrom, 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_triggersreturns (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).
What it proves, and approval
Section titled “What it proves, and approval”- 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.txtinstruct 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.activateis called” with “goes live on the confirming call ofworkflows.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.
Lifting “No real mail yet”
Section titled “Lifting “No real mail yet””- With this built, ADR 0031’s precondition is met: every action that starts sends is confirmed on the server, in every workspace.
assertEmailProviderAllowedis 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.
Consequences
Section titled “Consequences”- 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/testinghelper 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.txtand tool descriptions, that steer the assistant to broadcasts, saved audiences, and reports, and to showing previews; MCP elicitation where a client supports it.
As built (G1, 2026-11-20)
Section titled “As built (G1, 2026-11-20)”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.previewis thepreviewSendsabove.resultReferencetakes the reference a retry is answered from out of the action’s output.replayanswers a retry from that reference with the current view of what was committed, not with the first response, so one-time secrets such asapprovalLinkare not returned again. AstartsSendsaction must have theprojecttarget, 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 underresult. MCP tool output schemas must be objects, and the workflow view has its ownstatus, which would clash with the envelope’s.confirmation_pendingand itsprogresscome with the first count job (G6) and add a value to thestatusenum, 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, andbound, which the token hashes. The committing command recomputes onlybound, 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, whichinvokeApiActionruns 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_failedwhen no approval link could be delivered), the token is used and nothing is recorded. A retry with that token is then refused withconfirmation_invalidand 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, andapprovalRequired. - 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_LIMITcosts no preview queries. Over the limit, a call that starts no sends still runs, and one that would start sends answersrate_limited. Aconfirmation_invalidrefusal then carries no fresh preview. approvalRequiredis the constanttrue. It stays constant until ADR 0044’ssendApprovalRequiredsetting 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>orsession:<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) bindsoauth_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.