Send outcomes (the Governed Email Effect)

A bare email transport delivers bytes and returns success. ReplyLayer tells your agent, on the same call, which of four things happened to an outbound message — and it never reports a refused send as a success:

• sent — accepted for delivery. Proceed.
• held_for_review — accepted into governance, awaiting a human. Releasable; do not retry.
• held_infrastructure — a transient infrastructure hiccup held it. The content was never judged. Retry-later.
• blocked — content policy refused it. Terminal. Edit or escalate — never retry as-is.

That four-way distinction is the contract. This page is the machine reference for consuming it.

email_effect is outbound-only. Inbound messages carry agent_safety_context instead (see /agents/security-model) and never email_effect.

The email_effect object

email_effect is a thin, derived view over fields the message already carries — not a new data model. It appears as a sibling of scan / hold_context on:

• POST /v1/messages/send (success body; and inside details on a strict non-2xx)
• POST /v1/messages/:id/reply (same)
• GET /v1/messages/:id (outbound rows)
• GET /v1/threads/:id and GET /v1/mailboxes/:id/messages (per-message outbound items — byte-identical to the detail view)

"email_effect": {
  "effect_status": "blocked",
  "releasable": false,
  "terminal": true,
  "retryable": false
}

Everything semantic — the verdict, categories, and per-finding failure_class / agent_instructions[] — stays on scan; email_effect does not duplicate it. Verdict and state vocabulary are defined at /agents/messages.

When email_effect is omitted

The field is absent (not null) when there is no determinate send-effect yet — a polling agent should keep polling:

• a still-transient row that is scanning, received, or dispatching; or
• a plain compose draft that has never been sent and carries no non-allow finding (its rescan rejection arrives synchronously as the draft-send 409, not here).

The four outcomes → what your agent does

¹ terminal becomes true once a delivery/bounce event proves the send.

The never-retry-a-block rule (the load-bearing invariant)

An infrastructure hold must never be mislabeled a content block, and a genuine content block must never be reported retryable. retryable: true fires only when a scan carries an infrastructure-failure finding and no genuine model-judgment block or quarantine.

The consequence agents must handle: a scan that carries both a genuine block and a co-occurring infrastructure-failure finding resolves to blocked / retryable: false / terminal: true. The infrastructure hiccup does not make a genuinely-rejected message retryable. Retrying it re-blocks.

Rule of thumb: branch on retryable for retry-vs-not, and treat blocked as final regardless of any other signal on the row.

Prefer: outcome=strict — honest HTTP status

By default, POST /v1/messages/send and /reply return HTTP 200 even on a block or a hold; the outcome is in the body. This is unchanged legacy behavior — existing callers are unaffected.

Opt into honest HTTP status with the request header Prefer: outcome=strict (RFC 7240). A non-sent outcome then maps to a non-2xx carrying the same governed fields (message_id, status, scan, hold_context, email_effect) inside details:

held_infrastructure is evaluated first: an infrastructure hold must map to 503/retryable, never to 422. Retry-After: 30 is a "retry no sooner than" floor, not a recovery guarantee — back off exponentially on repeated 503s.

The strict remap applies on the idempotent-replay serve path too, so a strict send that returned 422 returns 422 again on a same-key retry (never a 200), carrying the same email_effect. The read-only idempotency probe (below) is strict-exempt.

CLI / SDK / MCP: the strict mapping surfaces as typed SDK errors, MCP isError, and CLI --strict exit codes. The canonical exit-code table (including --strict 4/5/6) lives at /agents/cli; the full error-code catalog lives at /agents/errors.

Fail-closed on unknown enum values

effect_status is an open enum — new outcome members may be added additively. Treat any unrecognized value conservatively: an unknown effect_status must never be treated as sent. Assume held/blocked until you have taught your runtime the new value. Strict-mode CLI/MCP surfaces already fail closed on an unrecognized effect_status (a distinct non-zero exit / isError:true).

Idempotent sends

Any POST /v1/messages/send or /reply may carry an Idempotency-Key header (an arbitrary string). A repeated request with the same key replays the prior outcome — the same message_id, the same body, the same email_effect — instead of sending a second time. This is the retry-safety contract: a network retry on a request that already succeeded will not double-send or double-charge.

A same-key request resolves to one of:

A blocked send replays as blocked. A same-key retry of content that was blocked returns the block again — it is not a retry escape hatch. To resend, change the content (a different request) under a fresh key, or escalate.

The read-only replay probe

GET /v1/messages/idempotency is a side-effect-free probe that reports what a same-key send would replay, without sending. The key travels in the Idempotency-Key header.

Use it before rebuilding a request whose local state is gone (e.g. an attachment file that no longer exists locally): probe first, and if it replays, you are already done.

IDEMPOTENT_REQUEST_NOT_PROVEN_SENT (409)

This is the one idempotency case that needs human-ish judgment. It means a prior same-key send reached the provider but ReplyLayer could not confirm it was accepted, so a blind retry might duplicate. Do not auto-retry. Read GET /v1/messages/:id and inspect email_effect:

• If it now resolves to sent — the message went out; treat the task as done.
• If it resolves to held_infrastructure with retryable: true — the row is idempotency-keyed, so retrying replays (it does not duplicate); safe to retry.

Async dispatch (optimistic ack)

When asynchronous dispatch is available for your account, sending a draft with the request header Prefer: respond-async returns immediately with HTTP 202 and an echo header Preference-Applied: respond-async:

{
  "message_id": "<uuid>",
  "status": "queued_for_dispatch",
  "daily_limit": 200,
  "sends_remaining": 199
}

The synchronous pre-send gates, budget reservation, and enqueue all run before the 202; the scan and the actual provider send run in the background. When async dispatch is not available for your account, the same request falls through to the synchronous path and returns 200 — treat the 202-vs-200 status as the observable capability signal.

Poll to a terminal outcome. After a 202, poll GET /v1/messages/:id until its email_effect resolves (it is absent while the row is still queued_for_dispatch / scanning / dispatching). Then branch on email_effect exactly as for a synchronous send:

• resolves to sent → done;
• resolves to held_for_review → a human release is pending;
• resolves to blocked → edit or escalate (a background scan rejected it; your send budget is refunded);
• resolves to held_infrastructure (retryable: true) → the background dispatch hit an infrastructure failure and the message reverted — retry-later. The corresponding message.dispatch_failed webhook is described at /agents/webhooks.

Caveat: drafts that carry staged attachments must be sent synchronously (omit Prefer: respond-async). See /agents/attachments.

Verdict → action (the agent's branch table)

Self-contained against the real REST / MCP / webhook surface:

Stability

The field set of email_effect and the meaning of each field are frozen. The enum members of effect_status (and of scan.verdict / category / subtype) are open — new outcomes and findings add members, never new required fields or removed fields. Consume defensively: unknown effect_status is not sent; unknown verdict is not clean.

Known v1 limitation: a replayed idempotent send carries the same email_effect as the original with no already_applied marker. If you must tell a replay from a first send, track your own keys.

See also

• /agents/messages — message state machine and verdict vocabulary.
• /agents/send-gates — why a send was refused before it produced an outcome (suppression, containment, recipient policy).
• /agents/errors — the full error-code catalog and denial envelope.
• /agents/cli — --strict exit codes and the block-is-exit-0 asymmetry.
• /agents/attachments — staging lifecycle and the synchronous-send caveat.
• /agents/webhooks — the content-free effect webhook projection and delivery events.