Why a send was refused (send gates)

Every POST /v1/messages/send, POST /v1/messages/:id/reply, and draft dispatch runs through a fixed stack of pre-send gates. A gate refusal is returned before any bytes leave — for the recipient-policy gates, no messages row is written and no send budget is consumed, so a refusal never counts against your abuse signals or your daily quota.

This page is the single source for the send-gate decision tree: for each gate, the exact error code, its response details, and who can lift it. For the full error catalog see /agents/errors; for tier and sandbox numbers see /docs/limits.

The decision tree

Gates are listed in the order that matters for diagnosis. The do-not-contact list is always evaluated and always wins on overlap — a recipient on both the do-not-contact list and an allowlist is refused with RECIPIENT_SUPPRESSED.

The continuity gate (§1b) is the one sender-side check, and where it sits relative to the recipient checks depends on the path:

Both are correct refusals of the same attempt. Branch on code, and never infer one gate's outcome from another's silence — the same message re-submitted through a different path can legitimately return the other code.

send(to, ...)
│
├─ on the account do-not-contact list?          → 403 RECIPIENT_SUPPRESSED
│
├─ hard-bounced across the platform (any account, any time)?
│    → 403 RECIPIENT_SUPPRESSED (details.scope: 'platform')
│    (skipped entirely for a delegated/self-hosted sending domain — see §1a)
│
├─ sending FROM a trial-era continuity mailbox?
│    recipient is a visible inbound sender in this thread+mailbox? → allow
│    otherwise                          → 403 ESTATE_CONTINUITY_REPLY_ONLY
│    (the only sender-side gate; evaluated BEFORE the checks above on
│     draft-send. Binds human and agent sends alike — see §1b)
│
├─ agent-origin send + mailbox contains agents?  ┐
│    a ReplyLayer test address?         → allow  │
│    on the mailbox allowlist?          → allow  │  (containment
│    a visible inbound thread participant? → allow│   overlay:
│    otherwise                          → 403 RECIPIENT_AGENT_CONTAINED
│
├─ agent-origin send + mailbox in allowlist mode?┐
│    a ReplyLayer test address?         → allow  │
│    on the mailbox allowlist?          → allow  │  (recipient
│    a visible inbound thread participant? → allow│   allowlist)
│    otherwise                          → 403 RECIPIENT_NOT_ON_ALLOWLIST
│    (strict-recipient ON → thread bypass suppressed for agent sends)
│
├─ recipient-quality checks (address syntax, typo, role, disposable, MX)?
│    → 422 RECIPIENT_ADDRESS_INVALID | RECIPIENT_DOMAIN_TYPO_SUSPECTED |
│         RECIPIENT_ROLE_ADDRESS | RECIPIENT_DISPOSABLE_ADDRESS | RECIPIENT_UNDELIVERABLE
│    (only when recipient verification is enforced for your account; a reply
│     or thread continuation only runs the address-syntax + MX checks;
│     uncertainty always fails open)
│
├─ sandbox tier, recipient not admitted?         → 403 SANDBOX_RECIPIENT_NOT_VERIFIED
│    (your own address, test-simulator addresses, replies to an
│     authenticated sender, and confirmed and account-added recipients
│     are admitted)
│
├─ sandbox trial send budget exhausted?          → 403 SANDBOX_TRIAL_BUDGET_EXHAUSTED
│
├─ sandbox recipient-domain 24h cap reached?     → 429 SANDBOX_RECIPIENT_DOMAIN_CAP_EXCEEDED
│
├─ daily send limit reached?                     → 429 RATE_LIMITED
│
└─ allow → scan → deliver

Runtime ordering interleaves budget checks with the recipient-policy checks, so the exact code you see first can differ from the diagnostic order above; the invariants that hold regardless are: do-not-contact wins on overlap, and agent-send containment is evaluated before the recipient-quality checks so a contained recipient never triggers a DNS lookup or a paid verification call.

Denial envelope

Capability refusals carry a machine-readable denial envelope in details so you can route on the response instead of parsing prose. The two fields you branch on:

• reason_axis — a closed enum naming why (for send gates: recipient_containment, sandbox_recipient, trust_capacity, account_state).
• remedy — a closed enum naming what to do (e.g. add_recipient_to_allowlist, add_paygo_credits_or_await_trust_ramp).

Monetary axes also carry cheapest_next_step (paygo | starter | pro | no_cost_remedy) and, when a dashboard link is configured, upgrade_url. Not every send-gate refusal is a full envelope: RECIPIENT_SUPPRESSED carries only a narrow details.reason: 'suppressed' disambiguator (an optional details.scope: 'platform' distinguishes a cross-account platform hit from your own do-not-contact list — see §1a). The full axis/remedy enum lives at /agents/errors.

1. Do-not-contact list — RECIPIENT_SUPPRESSED

HTTP/1.1 403 Forbidden
{ "code": "RECIPIENT_SUPPRESSED", "details": { "reason": "suppressed" } }

The account-wide do-not-contact list is checked on every send and short-circuits every other recipient check. One ordering caveat: on draft-send and the async dispatch worker the sender-side continuity gate (§1b) is evaluated before it, so a continuity mailbox sending to a suppressed address sees ESTATE_CONTINUITY_REPLY_ONLY there. Entries are auto-added from delivery signal (hard bounces, spam complaints, unsubscribes) and can be added by you. Bare-domain entries (@example.com) match every address at that domain.

details.reason: 'suppressed' is a fixed disambiguator, not a full denial envelope — it never carries the suppressed address or the reason it was suppressed. Branch on code === 'RECIPIENT_SUPPRESSED'.

Who can lift it: agent and admin keys can add to the list; only admin keys or a dashboard session can remove an entry. An agent that hits this cannot un-block the recipient itself. Manually-added entries are removable; bounce/complaint entries should generally stay. See /docs/guides/suppressions.

Preflight: GET /v1/suppressions (any account-scoped key) to check the list before sending.

A separate provider-side sync also refuses RECIPIENT_SUPPRESSED for addresses the delivery provider already marked as hard-bounced or complained. The reserved test-simulator address is exempt from both, so repeat onboarding test sends are never blocked.

1a. Platform-wide hard-bounce list — RECIPIENT_SUPPRESSED (scope: 'platform')

HTTP/1.1 403 Forbidden
{ "code": "RECIPIENT_SUPPRESSED", "details": { "reason": "suppressed", "scope": "platform" } }

Separate from your own do-not-contact list: when an address hard-bounces on any account's send — not just yours — ReplyLayer records it once, platform-wide, and every future send to that address from a ReplyLayer-managed sending domain (the shared platform domain, your <slug>.replylayer.net identity, or the sandbox estate) is refused before it can bounce again. This protects the shared sending reputation every customer's mail rides on. It never fires from a spam complaint or an unsubscribe — only a confirmed hard bounce.

This gate does not apply to a delegated (BYOD) or self-hosted sending domain. Your own domain's reputation is yours alone, so a platform-wide hard-bounce signal is informational only there — it is never enforced.

Same code as your own do-not-contact list (§1) — a caller branching only on code === 'RECIPIENT_SUPPRESSED' sees no difference. The optional details.scope: 'platform' is how you tell the two apart; its absence means the account-level list.

Who can lift it: this is not customer-manageable (there is no per-account entry to remove) — contact support if you believe an address was recorded in error.

1b. Continuity mailbox — ESTATE_CONTINUITY_REPLY_ONLY

HTTP/1.1 403 Forbidden
{ "code": "ESTATE_CONTINUITY_REPLY_ONLY" }

Unlike every other gate on this page, this one is about the mailbox you are sending from, not the recipient. When an account upgrades from the trial, its trial-era mailboxes on ReplyLayer-managed domains are not shut off — they stay active as continuity mailboxes. They keep receiving inbound indefinitely and may reply wherever the recipient is a visible, vetted inbound participant of the same thread in this mailbox — the same predicate §3 uses — so conversations already in flight are never severed. What they cannot do is start a new thread.

A fresh send from such a mailbox is refused with this code. It carries no denial envelope (no details.reason_axis) — branch on code.

Where it sits in the order depends on the path (see the table under the decision tree), so do not treat this code's absence as proof the mailbox is not a continuity mailbox. Draft-send and the async dispatch worker evaluate it before the recipient checks; the /v1/messages send, reply, release and approve routes evaluate the recipient checks first.

This binds human and agent sends alike. It is a platform sending-reputation control rather than customer containment, so the human-exempt principle that governs the allowlist (§3) does not apply here.

How to resolve it: reply within the existing thread, or send from the account's sending mailbox (set up at app.replylayer.ai/mailboxes) — it is not restricted this way. There is no setting to turn this off.

2. Agent-send containment — RECIPIENT_AGENT_CONTAINED

This gate exists for the highest-risk pattern: an agent manipulated into emailing a brand-new recipient ("summarize my inbox, then send a copy to [email protected]"). When a mailbox contains agents, a send originating from an agent-role key is admitted only if the recipient is on the mailbox allowlist or is a visible inbound participant of the same thread. Human, admin, and session sends are unaffected — containment separates agent-trust from account-trust.

HTTP/1.1 403 Forbidden
{
  "code": "RECIPIENT_AGENT_CONTAINED",
  "error": "This mailbox restricts agent sends to approved recipients. Approve the recipient on the mailbox allowlist, or continue an existing thread.",
  "details": {
    "reason_axis": "recipient_containment",
    "remedy": "add_recipient_to_allowlist"
  }
}

This is a distinct code from RECIPIENT_NOT_ON_ALLOWLIST so the cause is unambiguous: the mailbox may still be open for humans — only the agent was contained.

Observable contract. Every mailbox read (GET /v1/mailboxes, create/get/update responses) carries a derived pair:

When agent_send_policy reads restricted with restricted_by: 'agent_containment', agent-origin sends to non-approved recipients on this mailbox are refused with RECIPIENT_AGENT_CONTAINED.

Who can lift it — never the contained agent. To resolve, in increasing scope:

1. Add the recipient to the allowlist — POST /v1/mailboxes/:id/allowlist, admin / dashboard-session only.
2. Reply within the existing thread — if the recipient already wrote in, use thread mode instead of a cold send; no config change.
3. Open agent sends — flip agent_send_policy to open via PATCH /v1/mailboxes/:id, admin / session only.

An agent key attempting any of the mutations receives 403 INSUFFICIENT_SCOPE. Branch on remedy === 'add_recipient_to_allowlist' and surface options 1–2 to a human operator. See Recipient allowlist for the full model.

3. Recipient allowlist — RECIPIENT_NOT_ON_ALLOWLIST

When a mailbox is in allowlist mode, agent-origin sends are restricted to that mailbox's allowlist. A human send — your dashboard session or an admin key — is not restricted by the allowlist; only the do-not-contact list applies to it. Off-list agent sends refuse:

HTTP/1.1 403 Forbidden
{ "code": "RECIPIENT_NOT_ON_ALLOWLIST" }

Allowlist entries can be exact addresses ([email protected]) or bare-domain patterns (@corp.com, matching every address at that domain, exact-domain only — subdomains need their own entry).

ReplyLayer test addresses are always allowed. The four simulator scenario addresses (delivered@, bounced@, complained@ and [email protected], including +label forms) pass this gate and the gate-2 containment overlay with no entry, because a send to them never reaches anyone. On a Supervised mailbox they are never held as a first contact. Other local parts at that domain, subdomains and lookalike domains are contained normally, and the do-not-contact list still runs first. GET /v1/mailboxes/:id/allowlist lists the four in always_allowed. See the email simulator guide.

Thread-reply bypass. In allowlist mode, an off-list send is still admitted if and only if the recipient is a visible, vetted inbound participant of the same thread in this mailbox, recomputed from message history on every send (no standing grant is written). Constraints:

• A cold send to an address that never wrote into the thread stays blocked.
• Passing a new to against an existing thread_id → 422 RECIPIENT_NOT_IN_THREAD.
• A firewall-blocked, scanner-blocked, unvetted, or deleted inbound row is not a participant and never authorizes a reply (a blocked message still shows in the thread). A quarantined inbound does count.

Supply thread context via thread_id on send / draft, or by replying to a message. The bypass is gated by the mailbox's thread-reply toggle.

Who can lift it: allowlist add/remove and the mode flip are admin / session only (agent keys → 403 INSUFFICIENT_SCOPE); granting send permission to an agent would defeat the containment boundary. An agent that hits this can pick an allowlisted recipient or continue an existing thread.

Preflight: GET /v1/mailboxes/:id/allowlist — agents bound to the mailbox can list, so an agent can see what it is allowed to email before it tries (the entries, plus the always_allowed test addresses). recipient_policy_mode is on every mailbox read.

4. Strict-recipient (instruction-trust) toggle

A mailbox that has opted into trusted instruction sources can set a strict-recipient policy. When strict-recipient is effective (the mailbox's instruction-trust mode is enabled and strict-recipient is on) and the send is agent-origin, the thread-reply bypass in gates 2 and 3 is suppressed: a thread participant who is not also on the explicit allowlist is refused. Agent sends are held to the explicit allowlist only. Non-agent sends are unaffected.

The refusal reuses the gate-2/gate-3 code (RECIPIENT_AGENT_CONTAINED or RECIPIENT_NOT_ON_ALLOWLIST) — strict-recipient tightens which recipients pass, it does not introduce a new code.

Who can change it. Turning strict-recipient on (tightening) is agent-callable for fast incident response. Turning it off (loosening) requires a dashboard session with fresh re-authentication — an agent can never loosen instruction-trust posture for itself. See /agents/trusted-instructions.

5. Recipient verification — five 422 codes

When recipient verification is enforced for your account, every fresh send/reply/draft-send runs a permissive, fail-open recipient-quality check before provider hand-off. Only a confirmed violation refuses the send — any uncertainty (DNS timeout, verification-service outage) fails open and the send proceeds; the provider bounce path is the backstop.

HTTP/1.1 422 Unprocessable Entity
{ "code": "RECIPIENT_ROLE_ADDRESS" }

A reply or thread continuation is exempt from the typo / role / disposable checks — the recipient is a proven correspondent — so only RECIPIENT_ADDRESS_INVALID and RECIPIENT_UNDELIVERABLE are reachable on POST /v1/messages/:id/reply or a send --thread continuation. All five codes are skipped entirely for a test-simulator recipient or a recipient at one of your own ReplyLayer-managed sending domains.

On the scheduled-send, async-dispatch, and release paths these map to the matching message.dispatch_failed reason code.

Who can lift it: no auth change — fix the recipient address (or, for a typo false-positive, resend as-is). This is a data problem, not a permission one.

6. Sandbox gates

Sandbox accounts have additional gates. See /docs/limits for the sandbox model.

On the free Sandbox you can email your own address and anyone who confirms by link, reply to people who write to you from an authenticated address, and add up to 5 people you know, yourself or through your agent. Add $5 of pay-as-you-go credit or upgrade to email anyone.

Your agent can add people itself, or ask them to confirm by link, unless you restrict it to people you approve or to drafting only; then it asks you. If someone added without a click reports your email as spam, everyone added that way must confirm by link before you can email them again and your trial can no longer add people that way; a report from a second person suspends the Sandbox account.

Recipient not admitted — 403 SANDBOX_RECIPIENT_NOT_VERIFIED. A sandbox send is admitted only when its recipient is your account's own email address, an exact test-simulator scenario address, the sender of an inbound message you are replying to whose address was authenticated (sender-authentication verdict verified_aligned), a confirmed recipient on the account's list, or a recipient the account added as someone it knows. Recipients are added with POST /v1/recipients: without attest it emails them a confirmation link they must click; with attest: true they are sendable at once, with no email, up to 5 per trial (attestations_remaining in the envelope below says how many are left). A session or admin key can always add them; an agent key or app connection can when agent recipient writes are on and every mailbox it is bound to is open (not restricted to an allowlist) and set to Send and draft, and otherwise gets 403 INSUFFICIENT_SCOPE or 403 RECIPIENT_WRITE_AGENT_CONTAINED, meaning ask the account owner to add the person. Any other recipient is refused before any message row is written or any send budget is consumed, with a full denial envelope:

HTTP/1.1 403 Forbidden
{ "code": "SANDBOX_RECIPIENT_NOT_VERIFIED",
  "error": "Sandbox accounts can email this recipient only once they are on the account's recipient list. Add them with POST /v1/recipients so they can confirm by link, or add $5 of pay-as-you-go credit to remove the Sandbox recipient rule (a mailbox restricted to approved people still applies to agent sends).",
  "details": { "reason_axis": "sandbox_recipient", "remedy": "add_recipient_or_add_paygo_credits",
               "cheapest_next_step": "paygo", "upgrade_url": "https://app.replylayer.ai/settings/billing",
               "attestations_limit": 0, "attestations_remaining": 0 } }

A reply to a sender whose inbound message was not authenticated (or carries no verdict) is treated like any other recipient: it needs one of the other bases. On a draft send the send-time scan answers first with 409 DRAFT_REJECTED_BY_RESCAN, whose details.denial carries the same code and envelope; a scheduled send reports message.dispatch_failed with reason_code: SANDBOX_RECIPIENT_NOT_VERIFIED.

Test-simulator exemption. Sends to an exact simulator.replylayer.net scenario address (ReplyLayer's own first-party simulator — delivered@, bounced@, complained@, suppressed@, including +label forms) skip both the confirmed-recipient requirement and the Sandbox recipient-domain concentration cap, so one Sandbox account can exercise all four scenarios immediately. Daily and cumulative send allowances, the attempt ledger, authentication, API rate limits, scanning/review policy, and idempotency remain active. Other local parts, subdomains, and lookalike domains are not exempt. Scenario outcomes and accounting caveats are defined in the email simulator guide.

Recipient-domain cap — SANDBOX_RECIPIENT_DOMAIN_CAP_EXCEEDED. A Sandbox account can make at most 3 send attempts to one recipient domain in a rolling 24-hour window (a reply to an authenticated sender does not count). Confirmation requests and resends to an address at that domain (POST /v1/recipients, POST /v1/recipients/:id/resend) count toward the same 3. The fourth attempt returns a bare 429 error with this code. Wait until an earlier attempt leaves the window, or add pay-as-you-go credit or move to a paid plan; retrying unchanged before then refuses identically. The exact first-party simulator scenarios described above are the narrow exception because they make no network delivery; other recipients at any domain still follow this cap.

Trial budget exhausted — SANDBOX_TRIAL_BUDGET_EXHAUSTED. A sandbox account has a cumulative send budget across its trial. When exhausted:

HTTP/1.1 403 Forbidden
{
  "code": "SANDBOX_TRIAL_BUDGET_EXHAUSTED",
  "details": {
    "reason_axis": "trust_capacity",
    "remedy": "add_paygo_credits_or_await_trust_ramp",
    "cheapest_next_step": "paygo",
    "current_count": 250,
    "max_allowed": 250
  }
}

Who can lift it: add pay-as-you-go credits or upgrade — a billing action, so a dashboard session. Branch on reason_axis === 'trust_capacity'.

7. Daily quota / velocity — RATE_LIMITED

The effective daily send limit is trust- and tier-derived. When the day's budget is spent:

HTTP/1.1 429 Too Many Requests
{
  "code": "RATE_LIMITED",
  "details": {
    "daily_limit": 200,
    "sends_remaining": 0,
    "reset_at": "2026-05-30T00:00:00.000Z"
  }
}

reset_at is the next UTC-midnight budget rollover. Back off until reset_at — the same daily send retried before then refuses identically.

Preflight — do this before a burst. GET /v1/accounts/quota is agent-accessible (unlike the admin-only usage endpoint) and reports the effective limit the gate enforces:

{
  "today": { "count": 12, "limit": 200, "day": "2026-05-29" },
  "sends_remaining": 188,
  "reset_at": "2026-05-30T00:00:00.000Z",
  "scope": "agent",
  "bound_mailbox_ids": ["..."]
}

Who can lift it: wait for reset_at — your effective daily limit can rise over time as your account's sending history builds (check the current ceiling anytime via GET /v1/accounts/quota) — or upgrade the tier. See /docs/limits. New paid senders may see a temporary warm-up cap disclosed in the warmup block of the quota response.

Recommended agent flow

1. Preflight the cheap checks — read the mailbox (agent_send_policy, recipient_policy_mode), the allowlist if in a restricted mode, and GET /v1/accounts/quota before a burst.
2. Send, then branch on code first, details.reason_axis/remedy second. A 403 RECIPIENT_* is a policy refusal you resolve with data or a human; a 429 RATE_LIMITED is a timing refusal you resolve with reset_at.
3. Never retry a policy refusal unchanged. RECIPIENT_SUPPRESSED, RECIPIENT_AGENT_CONTAINED, and RECIPIENT_NOT_ON_ALLOWLIST will refuse identically until a human changes configuration. Surface remedy to your operator rather than looping.
4. A refusal is not a content block. These gates run before scanning. A send that passes the gates can still be held or blocked by the content scanner — that is a separate outcome; see /agents/send-outcomes and /agents/messages.

Refused agent sends against a restricted mailbox are recorded and can be delivered to your webhook as a blocked-attempt event — see /agents/webhooks.