Email verification: unknown and catch-all, what to do

Why a verifier that does not guess answers unknown, why catch-all is risky and not valid, and what your code should do with each.

Every verifier meets servers that will not answer: a "come back later" on first contact, policy blocks on the verifier's IPs, tarpits, servers that accept every recipient and decide later. The dishonest response is a confidence score. Ours is unknown, free, with the server's reply in the evidence.

Catch-all is different: the server did answer, and the answer is that it accepts every address. That is a fact about the domain and it is billed; what we do not do is upgrade it to valid. Your address is tested as well, so a full or explicitly dead mailbox on a catch-all domain still gets its own verdict.

Wire it in

const v = await verify(email);                    // POST /v3/verify
switch (v.reason) {
  case 'greylisted':           // the server asked us to come back; a form cannot wait
  case 'relay_blocked':        // the server refuses our IPs, not the mailbox
  case 'accepts_unverified':   // a 252: it will try later
  case 'timeout':              // your ceiling ran out
    return acceptAndConfirm(email);              // unknown: not billed
  case 'domain_catch_all':
  case 'provider_catch_all':
    return acceptAndConfirm(email);              // risky: the domain takes anything
  case 'mailbox_full':
    return acceptAndConfirm(email);              // risky: real, full today
}

What to do with each answer here

unknown	Accept and confirm by email, or retry later. Never reject. Not billed, so a retry costs you only when it gets an answer.
risky, domain_catch_all	Accept and confirm by email. On a list: send if the list is opt-in; discard if it was bought or scraped.
risky, mailbox_full	Real mailbox, no room. Accept and confirm; re-verify in a few weeks on a list.
risky, disposable_domain	The one risky reason whose suggested_action is reject.

What this does not do

We do not resolve catch-all domains, and we say so. Vendors who return valid for them are estimating.
Microsoft's consumer namespace (outlook.com, hotmail.com) blocks verifiers by IP; unknown is more common there than elsewhere, and the evidence shows the block.
Our unknown rate will sometimes look higher than a competitor's. That is the honest number.

Reference: the API, handling results, result codes. A free key gives you 100 verifications a month: get one.