Docs

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.

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.

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.

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.