Design an API that can say “unknown” clearly.
A static technical guide to designing email verification APIs with layered results, bounded latency, privacy controls, idempotency, and safe retries.
Verification APIs depend on local parsing, DNS, remote mail systems, provider intelligence, and customer policy. Those layers have different latency and certainty. A durable contract separates the evidence, exposes timestamps and reason codes, and lets the client decide how much friction the workflow requires.
Illustrative resource model
POST /v1/verifications
Idempotency-Key: 8f2b...
{
"email": "[email protected]",
"mode": "interactive"
}A successful API transaction creates a verification resource even when the address outcome is unfavorable or unknown. HTTP errors should describe request, authentication, authorization, quota, or service failures—not turn a mailbox verdict into a transport error.
Illustrative response
{
"id": "ev_01J...",
"status": "unknown",
"reason": "smtp_policy_block",
"address": {
"normalized": "[email protected]",
"syntax": "valid"
},
"domain": {
"status": "mail_capable",
"catch_all": "unknown"
},
"mailbox": {
"status": "unknown",
"retryable": false
},
"checked_at": "2026-10-23T18:42:00Z",
"policy_version": "2026-10"
}Fast path and deferred path
Interactive checks
Run syntax, cautious normalization, cached intelligence, and bounded DNS work. Return partial evidence before the form experience becomes unpredictable.
Deferred checks
Complete mailbox observations, retries, deeper enrichment, or bulk processing in a job. Return a stable ID and deliver a signed webhook or polling resource.
Recommended fields
- Original and normalized address, with normalization rules documented
- Syntax, domain, mail route, mailbox, catch-all, disposable, and role statuses
- Stable reason code, retryable flag, and recommended delay where meaningful
- Checked time, evidence freshness, method version, and policy version
- Request and resource identifiers for support and idempotency
- Redaction-safe diagnostics that do not leak remote or recipient details
Result design
Use favorable, unfavorable, conditional, and unknown families. Keep the evidence fields beneath the top-level recommendation. A client may accept an unknown result for a public newsletter and require confirmation for an account recovery channel. Policy should be versioned separately from evidence.
Latency and cancellation
Assign a budget to each stage, expose timing metrics by dependency and receiving domain, and cancel work when the request budget expires. A timeout should return partial evidence with a specific reason. Avoid continuing hidden probes after the API has declared the resource complete.
Caching
Cache domain routing according to DNS behavior, provider intelligence under its own freshness rule, and domain-wide catch-all observations conservatively. Negative results deserve shorter lifetimes because a new domain or corrected record can become usable. Mailbox-level caches are sensitive and should be purpose-limited.
Privacy controls
- Do not place raw addresses in request URLs, metric labels, trace names, or ordinary logs.
- Collect no extra CRM fields unless the operation requires them.
- Encrypt data, restrict operator access, and define deletion across stores, queues, caches, and backups.
- Treat hashes as sensitive; a predictable email address can be guessed and compared.
- Prevent one tenant’s query history or cached result from becoming visible to another.
Rate limits and anti-enumeration safeguards
Require authentication, set per-tenant and per-domain limits, monitor concentrated queries, and provide controlled bulk jobs for legitimate high-volume work. A mailbox checker can be abused to enumerate recipients, so the service should reveal only what the customer’s legitimate workflow needs.
Reliable webhooks
Sign payloads, include an event ID and timestamp, reject replay, retry with backoff, and make events idempotent. Let consumers retrieve the canonical resource after a missed event. Support secret rotation and keep delivery logs redaction-safe.
Error taxonomy
| Layer | Example | Representation |
|---|---|---|
| API request | Malformed JSON or missing authentication | HTTP error plus stable API code |
| Verification result | Malformed address or recipient rejection | Successful resource with unfavorable result |
| Dependency uncertainty | DNS timeout or SMTP policy block | Successful resource with unknown result |
| Async delivery | Webhook endpoint unavailable | Retry history; canonical resource remains available |
Testing matrix
Test malformed and internationalized input, nonexistent domains, no MX, multiple MX hosts, DNS timeout, temporary and permanent SMTP responses, catch-all, policy blocks, connection reset, cancellation, idempotent replay, quota limits, webhook replay, and redaction. Load tests should concentrate traffic on one receiving domain as well as distribute it broadly.
Full implementation guide
Read Real-Time Email Verification API Design for a longer treatment of versioning, internationalization, caching, webhooks, privacy, and operational safeguards.