Skip to Content

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.

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

It calls GET /deliver/check: Check recipient deliverability in the API reference.

Example

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

Options

The last argument, options, takes:

OptionTypeSent asDescription
tostringquery toRequired. Recipient email address being checked
fromstringquery fromSender 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.
ipstringquery ipConnecting client IP address
ptrstringquery ptrConnecting client reverse DNS PTR hostname
helostringquery heloConnecting client HELO/EHLO identity
submissionbooleanquery submissiontrue: 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).

Answer

Awaited, it is the API's JSON, RecipientAccepted. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403FIVE 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.
404unknown_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.
429TEMPORARY, 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.
503temporary_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: 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.