Verdict reasons
Every answer leads with a verdict: deliverable, risky, or undeliverable. When the verdict is not deliverable, the reason field says why in one machine-readable word, and smtp_reason adds the detail behind the mailbox handshake. A phone validation answers valid and, when it is false, a reason of its own, and so does an address lookup that cannot stand as written. A consistency check adds flag values, which describe two signals rather than one. Each value has its own page with the full explanation, an example, and what to do with the input.
Undeliverable reasons
Do not send. The risk score is always 100, the address joins your suppression list, and the lookup is free.
| reason | meaning |
|---|---|
| invalid_syntax | the input does not parse as an email address |
| invalid_local_part | the username breaks the rules its own provider enforces |
| no_mx_records | the domain has no mail servers at all |
| null_mx | the domain declares that it never accepts mail |
| mx_unresolvable | the mail servers the domain points at do not exist |
| mailbox_not_found | the mail server rejected the mailbox during the handshake |
| mailbox_disabled | the mailbox exists but its provider has disabled it |
| suppressed | the email address, phone number or postal address is on your account's suppression list |
Risky reasons
Mail may arrive, but something argues for caution. Each reason adds its published weight to the risk score; the answer costs 1 credit like any deliverable one.
| reason | meaning | risk weight |
|---|---|---|
| likely_typo | the domain is a known misspelling of a real mail provider | +60 |
| parked_domain | the domain is parked or for sale, and still accepts mail | +60 |
| disposable | the domain belongs to a disposable, temporary email provider | +80 |
| mx_blocklisted | the domain's mail is served from a network on the threat blocklists | +60 |
| implicit_mx | the domain has no MX record and relies on the address-record fallback | +30 |
| mailbox_full | the mailbox is over its storage quota | +20 |
| no_reply | a no-reply address: mail to it is discarded by design | +20 |
| role | a shared role inbox such as info@ or support@ rather than a person | +30 |
| recycled_mailbox | the mailbox exists now, but once answered that it did not | +30 |
| catch_all | the server accepts every address at the domain, so the mailbox cannot be confirmed | +30 |
| unverified | the mailbox could not be confirmed | +10 |
Phone validation reasons
Why POST /api/v1/phone answered valid: false. Every one is free. Only unassigned_block keeps the parsed number in its answer, because the number itself is well-formed and it is the regulator's table that rules it out.
| reason | meaning |
|---|---|
| missing_country | no country was given, and the input does not carry one |
| invalid_country_code | the calling code after the + is not assigned to any country |
| too_short | fewer digits than any number in that plan |
| too_long | more digits than any number in that plan |
| not_a_number | the input does not look like a phone number |
| invalid_length | a digit count the plan never uses |
| invalid_number | the right length, but not assignable under the plan |
| unassigned_block | the regulator has not allocated the block the number sits in |
| emergency_number | an emergency number, not a subscriber line |
| short_number | a short code or service number, not a subscriber line |
Address verification reasons
Why POST /api/v1/address answered valid: false, in the order a person would fix them: what is missing first, then what is wrong, then what does not exist. Every one is free, and the parts that were recognised are still reported. missing_country is shared with the phone lookup and documented above.
| reason | meaning |
|---|---|
| empty_address | nothing in the request was an address |
| unknown_country | no postal format is published for that country |
| missing_street | the country requires a street line and none was found |
| missing_locality | a country with no postcode to name the town was given neither |
| missing_administrative_area | a country with no postcodes needs the state or province |
| missing_postal_code | the country requires a postcode and none was given |
| invalid_postal_code | the postcode is not the shape that country uses |
| postcode_not_found | the postcode is well formed but is not in the directory |
Cross-signal consistency flags
What POST /api/v1/consistency names when two signals disagree, or when two weak signals coincide. These sit in a flag field rather than a reason, because they are not a verdict: each one is a statement about two fields whose values are quoted beside it. People travel, move house, keep a foreign number and browse through a VPN, so a flag is evidence to weigh and never a decision. The last two rows are not flags at all — they say why a comparison was left unanswered. All of it is free.
| flag | meaning |
|---|---|
| phone_country_differs_from_address_country | the phone number and the address name different countries |
| ip_country_differs_from_address_country | the IP address and the postal address name different countries |
| ip_country_differs_from_phone_country | the IP address and the phone number name different countries |
| disposable_email_from_datacenter_ip | a disposable address arriving from a datacenter |
| disposable_email_from_anonymous_network | a disposable address arriving over an anonymous network |
| mail_drop_address_with_free_email_provider | a mail-drop address with a free email provider |
| disposable_phone_with_disposable_email | a disposable number with a disposable address |
| entity_country_differs_from_address_country | the company is registered in one country and the address is in another |
| entity_name_differs_from_address_organization | the registered name and the organisation on the address are not the same name |
| missing_value | a comparison was withheld because a value was missing |
| low_confidence | a comparison was withheld because the location was not the person’s |
Mailbox-check details
The smtp_reason field explains what the SMTP handshake found, or why it could not settle the mailbox. A message is never sent.
| smtp_reason | meaning |
|---|---|
| no_mailbox | the server answered that the mailbox does not exist |
| disabled | the server reported the mailbox as disabled or suspended |
| greylisted | the server deferred the handshake and asked the sender to come back later |
| timeout | the mail server did not answer within the probe's time limit |
| no_connect | no mail server accepted a connection on port 25 |
| mx_unreachable | the mail exchangers could not be reached from the verification network |
| delivered_recently | your own delivery report confirmed this mailbox |
| provider_unavailable | the verification provider itself could not answer |
Every page here has a Markdown twin at the same URL with a .md suffix, and all of them are collected in llms-full.txt.