How deep to check

{ "email": "ada@example.com", "variant": "full" }

variant	What it does	Costs up to
full (default)	Everything below, and then one SMTP transaction asking the destination about this recipient.	10 credits
domain	Syntax, domain, mail routing and the risk signals. No session is opened with anybody.	2 credits

The default is full, and omitting the field keeps it that way

variant is optional and an empty value means the product’s most complete depth. That is not a convenience — it is the only reading that does not change what existing integrations buy. Every integration written before the field existed omits it, and any other default would quietly start selling them a shallower answer, turning deliverable into unknown on a signup form nobody had touched.

An unrecognised value is refused with a 400 rather than defaulted. A caller asking for a depth we do not sell has a bug, and answering it with the most expensive depth charges them for the misunderstanding.

What domain can and cannot tell you

It can tell you that a domain does not exist, publishes no mail routing, has declared that it accepts no mail, is a known disposable provider, or is one edit away from a large provider. Those are real, final answers — undeliverable from DNS_NXDOMAIN is as certain as this service gets.

It cannot tell you anything about the mailbox. A well-formed address at a perfectly ordinary domain comes back:

{
  "status": "unknown",
  "action": "allow_with_email_confirmation",
  "checks": { "syntax": "valid", "domain": "valid", "mail_routing": "valid", "smtp": "skipped" },
  "reason_codes": ["MX_FOUND", "SMTP_PROBE_NOT_REQUESTED"]
}

SMTP_PROBE_NOT_REQUESTED is distinct from SMTP_PROBE_SKIPPED_PROVIDER_POLICY, and the distinction is yours to read: one says you bought the cheaper depth, the other says we declined to ask a destination that would not have answered. Collapsing them would leave you unable to tell your decision from ours.

When each is the right purchase

Use full on a signup form. The whole point of asking at registration time is to catch the address that was mistyped thirty seconds ago, while the person is still there to fix it — and a typo usually produces a perfectly valid domain.

Use domain when you are grading a list you already have and the question is “is this domain worth mailing at all”, when you are filtering disposable providers, or when volume matters more than certainty. It opens no SMTP sessions, so it is not paced against destinations and returns immediately — there is no pending at this depth.

Credits are per product, not per depth

Both depths spend from the same balance, and a credit is a credit. What differs is how many of them one answer costs. See Credits.