# mta.checkRecipient

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.

```ts
openemail.mta.checkRecipient(
  options: MtaCheckRecipientOptions,
): ApiPromise<RecipientAccepted>
```

It calls `GET /deliver/check`: [Check recipient deliverability](/docs/api/delivery/get_DeliverCheck) in the API reference.

## Example

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

## Options

The last argument, `options`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `to` | `string` | query `to` | Required. Recipient email address being checked |
| `from` | `string` | query `from` | 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` | query `ip` | Connecting client IP address |
| `ptr` | `string` | query `ptr` | Connecting client reverse DNS PTR hostname |
| `helo` | `string` | query `helo` | Connecting client HELO/EHLO identity |
| `submission` | `boolean` | query `submission` | `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. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`RecipientAccepted`](/docs/sdks/typescript/types/recipient-accepted). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `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. |
| `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. |
| `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. |
| `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. |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

It names these types of the API, each on a page of its own: [`RecipientAccepted`](/docs/sdks/typescript/types/recipient-accepted).
