# Check recipient deliverability

Advisory RCPT-time pre-flight check. By default it is the inbound MTA's question: does the recipient exist here, and do its blocklists and routing rules accept this sender? With `submission=true` it is the submission MTA's question instead: may the authenticated sender (`from`, judged as /deliver/outbound judges X-Envelope-From for the same caller) submit to this recipient under its OWN rules, the identity's and credential's recipient allowlists, its outbound address lists, and its account's verified-recipients rule? That mode answers nothing about the recipient's existence: an outside recipient is accepted when the sender's rules allow it, and /deliver/outbound at DATA stays the authority for everything else. Its verdict depends on `from`, so an MTA must never cache it under the recipient alone.

## `GET /api/v1/deliver/check`

### Query parameters

- `to` (string, required, min 1 chars) — Recipient email address being checked
- `from` (string | null) — Sender email address (MAIL FROM). With `submission=true` it names the sender whose rules are judged; absent or empty (the null return path), nothing is judged and the recipient is accepted.
- `ip` (string | null) — Connecting client IP address
- `ptr` (string | null) — Connecting client reverse DNS PTR hostname
- `helo` (string | null) — Connecting client HELO/EHLO identity
- `submission` ("true" | "false") — `true`: judge the SENDER's rules for an authenticated submission instead of the recipient's inbound acceptance (default false). Accepted from system and account keys; a sender the caller may not send as, or one that is held, frozen or gone, is accepted here and refused by /deliver/outbound at DATA, which answers it for the whole message.

### Responses

**200** — Recipient is accepted: deliverable here (default), or permitted by the sender's own rules (`submission=true`)

`application/json` → RecipientAccepted

- `accepted` (true, required) — True if recipient address is accepted for delivery

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — FIVE codes, split by the error CODE — the MTA must never map this status alone. receiving_disabled: the address resolves but its domain is not accepting, or the destination mailbox's receive hold is `disabled` (then `policyScope: "mailbox"`) — a recipient verdict, reject permanently (550); the mailbox-scope one is never cached, since its owner can clear it. recipient_not_verified, TWO meanings by mode, both permanent (550) and never cached, since vetting the account or the owner confirming lifts them. By default: the address forwards (a remote route, a pattern or catch-all whose destination is remote, or an alias pattern) for an account that is not yet vetted, to a target that is not one of its verified recipients (an address on its own domains, or one whose owner confirmed it; another customer's address is not) — a recipient verdict; /deliver/inbound refuses the same recipient with the same code at DATA. With `submission=true`: the SENDING account is not yet vetted, so it may send only to its verified recipients, and this recipient is neither; the body carries `source: "verified_recipients"`, the same code and source /deliver/outbound answers at DATA, for this recipient alone (550 5.7.1), and the verdict depends on `from`. sender_blocked: an address list refuses this MAIL FROM for this recipient — also 550, but note the verdict depends on `from`, so it must NOT be cached under the recipient key alone. recipient_not_permitted (`submission=true` only): one of the SENDER's own policies excludes this recipient, the identity's or credential's recipient allowlist or the sender's outbound address lists; `source` says which (`permitted_recipients` | `address_list`), and an address list also names the deciding `list` and `pattern`. Permanent: 550 5.7.1 for this recipient alone, the same code /deliver/outbound answers at DATA; it depends on `from`, so it may not be cached under the recipient alone. insufficient_scope: this caller may not check at all (mailbox principals never can; with `submission=true`, neither can a system key that must name `X-Acting-Credential` and did not, nor one that sent `X-Acting-Credential` without its `X-Acting-Identity` companion) — a fault in the CALLER's configuration, not a fact about the recipient, so it must DEFER (451). A 550 here rejects every message the server sees, on a mistake an operator can fix in a minute.

`application/json` → ErrorBody

**404** — unknown_address — recipient address does not resolve to an active route. Permanent: 550 5.1.1. For SYSTEM callers the body also carries `domain_hosted`; when it is false the recipient's domain was never ours, the session is a relay attempt, and the honest SMTP reply is 550 5.7.1 (relaying denied) rather than 5.1.1 — then `sender_hosted: true` additionally means the MAIL FROM domain IS hosted here, i.e. one of our own users' clients submitting to the MX instead of ports 465/587, and the MTA should say so in the reply text. Both fields are absent for account callers (the foreign-domain collapse must stay indistinguishable from a miss) and on non-core backends; an MTA must treat absence as unknown and keep 5.1.1.

`application/json` → ErrorBody

**429** — TEMPORARY, every code here. receiving_paused: the recipient's account is inside its deletion window, or the destination mailbox's receive hold is `paused` (then `policyScope: "mailbox"`). DEFER (451), never reject: a sending MTA queues a 4xx for days, longer than the window, so a restore (or a cleared hold) still receives what arrived meanwhile. Carries Retry-After, and this verdict is deliberately NOT cached: a restored account must stop deferring immediately. rate_limited: the recipient's tenant or a hosted destination tenant reached through an alias or forward is over its delivery admission share, or that admission check is temporarily unavailable; DEFER (451) the same way, also uncached, with a Retry-After. recently_unknown: a hosted address did not resolve moments ago, as remembered by the colo-wide RCPT cache or the directory's negative memo; DEFER (451), never reject, because it may have been created since. Retry-After is at most the seconds left before the original miss expires (within a minute), and repeat hits never extend that expiry. Only the first authoritative miss answers 404.

`application/json` → ErrorBody

**503** — temporary_failure — the check could not be answered just now: storage or the recipient's directory home failed transiently, or a forward's verified-recipient policy or verdict could not be established (including an outage fallback whose old flag cannot settle an unverified target). With `submission=true`, also the SENDING account's verified-recipients verdict for this recipient (for example a recipient domain mid-removal), as /deliver/outbound answers it at DATA. Nothing about the recipient is known, so DEFER (451), never reject; carries Retry-After and is never cached.

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/deliver/check' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.mta.checkRecipient`](/docs/sdks/typescript/mta/check-recipient)

```ts
const recipientAccepted = await openemail.mta.checkRecipient({ to: 'ada@example.com' })
```
