Docs
Three endpoints, one response shape, and an explicit answer to the question every other vendor leaves vague: what happens when the answer is genuinely not knowable.
A request
curl -X POST https://api.proofwire.app/v1/email -H "Authorization: Bearer pk_test_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" -d '{"value": "catchall@sandbox.proofwire.app"}'The three-state verdict
Confidence ≥ 0.62. Billed.
Confidence ≤ 0.35. Billed.
Inside the band. Never billed. Handle it explicitly — it is an answer, not an error.
Why unknown exists at all
The commonest case is a catch-all mail server: it answers 250 for every address, including ones that cannot exist, so its acceptance of yours proves nothing. The industry norm is to report that as valid and invoice for it — which is where the "we were told it was deliverable and it hard-bounced" complaints come from. We return unknown, charge nothing, and tell you which control probe led us there.
Reading the evidence
Each evidence[] entry carries a weight in log-odds. Positive pushes toward valid, negative toward invalid, and zero means the signal is real but deliberately does not move the verdict — it feeds risk instead.
The weights sum, the sum goes through a sigmoid, and that is confidence. Evidence carrying a freshnessDays value is discounted as it ages, so a month-old carrier record never counts the same as a live probe.
Validity and risk are separate
A real, reachable mobile can belong to a serial fraudster. A disposable inbox can be perfectly deliverable today. Folding those into one number is why fraud scores read as noise, so you get both and gate on whichever your use case cares about.
Idempotency
Send Idempotency-Key on every call if your client retries on timeout. A retry with the same key replays the stored response and spends nothing. Reusing a key with a different body returns 409 rather than quietly answering the wrong question.
Where the data comes from
Phone liveness is a live carrier register query. Mailbox verification is a wholesale probe. IP attribution is built from ranges the operators publish themselves — AWS, Google Cloud, Cloudflare, and the Tor Project exit list.
An operator declaring its own address space is better evidence than a third party inferring it. What those sources do not cover — VPN and residential proxy detection — we do not claim: those fields come back null rather than false, because "we did not find it" and "it is not one" are different statements.