What this service answers

Three questions, kept apart

Is the address well-formed?

Parsed against what SMTP actually permits, not against a regular expression. The local part is never normalised — case, dots and +tags may be significant to the provider, and changing them changes which mailbox is being asked about.

Can the domain receive mail?

Resolution, MX records, and what those records route to. A domain that publishes MX 0 "." has said in public that it accepts no mail; a domain that does not resolve cannot receive any.

Did a destination accept this recipient?

One SMTP transaction, opened to the destination the domain nominates, stopping at RCPT TO. No message is ever transmitted — the engine has no capability to send one.

What it does not answer

Whether anybody controls the mailbox. Only a confirmation message somebody acts on establishes that, and no amount of protocol evidence substitutes for it. An undeliverable verdict is a reason not to send; a deliverable verdict is not a reason to skip confirming.

Whether a mailbox exists. A 250 to RCPT TO is evidence, not proof: it can come from a domain that accepts every recipient, a gateway that validates after the fact, a provider that deliberately hides mailbox existence, or a system that accepts now and bounces later. A 550 is evidence in the other direction and usually policy rather than absence. This is why the result vocabulary has five values and not two — see The five verdicts.

An inconclusive answer must not block a registration

unknown is the correct answer far more often than it feels like it should be, and it means the service could not establish something — not that the address is bad. An integration that refuses a signup on unknown refuses people for our timeouts, a destination’s greylisting, and every provider that declines to answer questions about its users. The recommended action in that case is allow_with_email_confirmation, and it is the right one.

Where to go next

Integrating

Quickstart is one request and one response. Authentication is the credential and how it is carried. Pending results is the one piece of protocol that is not obvious: some answers arrive later, and polling is how you get them.

Reading answers

The five verdicts and the recommended action beside each. Reason codes is the full closed vocabulary, with what each one is evidence about. Confidence explains what that number is and — more usefully — what it is not.