Result codes

Four verdicts, 29 reason codes, 17 of them never billed. Documented the way HTTP status codes are: one line each, no adjectives. Generated from GET /v3/codes.

Deliverable deliverable

Code	Reason	Billed	Meaning	Action
200	mailbox_existsdeliverable	1 credit	The mail server accepted the mailbox.	Accept
204	mailbox_accepteddeliverable	1 credit	Accepted with a non-standard 2xx reply.	Accept

Risky risky

Code	Reason	Billed	Meaning	Action
300	provider_catch_allcatch_all	1 credit	A provider known to accept every address.	Accept and confirm by email
301	domain_catch_all_knowncatch_all	1 credit	The domain was found to accept any address within the last hour; this mailbox was accepted too.	Accept and confirm by email
302	domain_catch_allcatch_all	1 credit	A random address and this mailbox were both accepted.	Accept and confirm by email
406	mailbox_fullinbox_full	1 credit	The mailbox is over quota (552 or enhanced status x.2.2).	Accept and confirm by email
—	disposable_domaindisposable	1 credit	A mailbox on a disposable-address provider.	Reject

Unknown unknown

Code	Reason	Billed	Meaning	Action
404	greylistedsoftbounce	free	The mail server temporarily refused the mailbox (4xx), typically greylisting.	Accept and confirm by email
408	no_verdictunknown	free	The dialogue ended after the greeting without a verdict.	Accept and confirm by email
411	accepts_unverifiedunknown	free	The server accepts without verifying (252).	Accept and confirm by email
412	relay_blockedunknown	free	The server blocked our checking IP on policy (5.7.x); every relay we tried was refused.	Accept and confirm by email
413	server_busysoftbounce	free	The server is shedding load (4xx greeting).	Accept and confirm by email
414	tarpitunknown	free	The server stalled after accepting the sender.	Accept and confirm by email
415	no_greetingunknown	free	No greeting for a transient reason: timeout, reset, or TLS failure.	Accept and confirm by email
416	relay_deferredsoftbounce	free	The server deferred our checking IP at EHLO or MAIL FROM (volume deferral, greylisting).	Accept and confirm by email
418	dns_unavailableunknown	free	DNS resolution was unavailable; try again.	Accept and confirm by email
419	timeoutunknown	free	The time you allowed ran out before the mail server answered.	Accept and confirm by email
500	no_relay_availableunknown	free	No verification relay could be reached: a failure on our side, not a fact about the address.	Accept and confirm by email

Undeliverable undeliverable

Code	Reason	Billed	Meaning	Action
100	empty_addresssyntax_error	free	Empty address.	Reject
101	address_too_longsyntax_error	free	Longer than 255 characters.	Reject
102	missing_at_signsyntax_error	free	No @ sign, or nothing before it.	Reject
103	local_part_too_longsyntax_error	free	The part before the @ is longer than 64 characters.	Reject
104	invalid_domainsyntax_error	free	The domain is not a valid host name.	Reject
105	invalid_local_partsyntax_error	free	The part before the @ contains characters no mail server accepts.	Reject
400	no_mail_serverundeliverable	1 credit	The domain has no mail server: no MX and no A record, or a null MX.	Reject
405	mailbox_rejectedhardbounce	1 credit	The mail server rejected the mailbox permanently (5xx).	Reject
407	dropped_at_rcpthardbounce	1 credit	The server dropped the connection when the mailbox was named.	Reject
409	greeting_rejectedundeliverable	1 credit	The server refused our greeting.	Reject
410	no_smtp_serviceundeliverable	1 credit	No SMTP service: connection refused, unreachable, or a 5xx banner.	Reject
417	mailbox_gonehardbounce	1 credit	The domain accepts any address, but rejected this mailbox specifically: it is gone.	Reject

Markers that only appear in a file

Status	Verdict	Billed	Meaning
greylisted	unknown	free	The mail server asked us to come back and had not answered by the time the file was written.
not-found	unknown	free	The file was stopped before this row was verified.
pending	unknown	free	Not verified yet (a download taken while the file was still verifying).

The original labels

The result field under each reason is the label the API has answered since 2019 and still does; disposable is the one label without a code of its own: a mailbox that exists on a disposable domain is reported under it, whatever the dialogue said. deliverable (the boolean) is also true for catch_all and disposable, because those mailboxes will technically accept a message; act on verdict and suggested_action.

When you should not trust a verdict

A verdict is what the mail server told us, read carefully. Here is where that is not the same as the truth.

A server that accepts everything: A catch-all domain (provider_catch_all, domain_catch_all) accepts a random address as readily as a real one. We test yours as well, so a full or explicitly dead mailbox on such a domain still gets its own verdict; the rest is risky, and no verifier can honestly do better.
A server that accepts without checking: Some servers answer 252 to every recipient (accepts_unverified): they will try to deliver and decide later. That is an unknown, not a yes, whatever other tools call it.
A server that refuses us, not the mailbox: Policy blocks on our IPs (relay_blocked) and deferrals that name our host or volume (relay_deferred) say nothing about the address. We retry through other relays inside the request; if every one is refused you get unknown. Microsoft's consumer namespace (outlook.com, hotmail.com) is where this happens most.
A server that asks us to come back: greylisted is a first-contact stall: the server asks us to come back. A file retries it on the server's schedule; a single API call cannot wait fifteen minutes, so it answers unknown and lets you decide.
A mailbox that exists today: mailbox_exists is what the server said now. A mailbox can be closed tomorrow, and a full one (mailbox_full) can be emptied. A verdict is not a permanent property of an address.
A disposable domain we have not seen yet: The disposable list is rebuilt daily from public sources (about 75,000 domains). A brand-new throwaway domain can still come back deliverable with flags.disposable false. Confirmation by email remains your backstop.
Our own failures: dns_unavailable, no_relay_available and your timeout are about us or about time, never about the address. They are unknown, unbilled, and worth a retry.

What you are charged for

Answers, not attempts, on the API and in a file alike. A verification costs one credit when it comes back billed: true: a mailbox that answered, a domain with no mail server, a catch-all domain (the server told us a fact, and your address was tested too). Syntax errors never reached a mail server. Every unknown taught you nothing about the mailbox: a server that would not say, a block on our IPs, a tarpit, your timeout, our own resolver or relays failing. In a file, duplicates and rows never reached are credited back as well.