Email validation API status guide
How to interpret validation API results without treating SMTP evidence as magic certainty.
Why validation statuses are not all equal
Mailbox providers do not all answer SMTP probes the same way. Some confirm users, some hide existence, some greylist, and some accept every address at the domain. That is why WillItInbox separates status, sub-status, confidence, and evidence. Use the email validator when this decision belongs in the product workflow.
| Result | Meaning | Default policy |
|---|---|---|
| valid | The mailbox appears reachable. | Accept and monitor bounces |
| invalid | Syntax, DNS, or mailbox evidence says it should fail. | Suppress |
| risky | Role, disposable, catch-all, or policy signals increase risk. | Segment or review |
| unknown | The provider did not produce reliable evidence. | Retry or send conservatively |
Catch-all is not valid
A catch-all domain accepts random local parts. That means SMTP acceptance does not prove the specific person exists. For cold outbound, catch-all addresses should usually be sent at lower volume. For product signup, you may still accept them but should watch activation and bounce signals.
How to integrate the API
- Use single validation in forms where quality matters.
- Use batch validation for small CRM or enrichment jobs.
- Use bulk validation for CSV imports and campaign hygiene.
- Tie validation policy back to deliverability checks using the sample report.
If you need the broader list hygiene strategy, read the existing list hygiene and sunsetting guide.
Use four top-level outcomes, not a boolean
A validation API should return valid, invalid, risky, or unknown plus a stable reason code. Valid means the available evidence supports delivery, not that a future message is guaranteed to arrive. Invalid requires durable evidence such as impossible syntax, no usable mail route, or a permanent SMTP response. Risky covers accepted-but-uncertain addresses such as catch-all domains. Unknown means the check could not reach a reliable conclusion.
| Outcome | Typical evidence | Recommended send policy |
|---|---|---|
| Valid | Syntax, DNS, and mailbox evidence agree | Allow after consent and suppression checks |
| Invalid | Permanent syntax, domain, or SMTP failure | Suppress and retain the reason |
| Risky | Catch-all, role, disposable, or quality warning | Segment by use case and risk tolerance |
| Unknown | Timeout, greylisting, provider blocking, or temporary error | Retry later; do not label invalid |
Reason codes keep integrations stable
Store the top-level outcome separately from reason codes and evidence. Product teams can change policy for role addresses or disposable domains without rewriting the transport layer. Preserve the submitted address, normalized address, provider classification, catch-all state, SMTP evidence category, and check timestamp. Never expose raw SMTP transcripts containing credentials or unrelated message data.
{
"email": "[email protected]",
"status": "unknown",
"reason": "smtp_temporary_failure",
"retryable": true,
"catch_all": false,
"checked_at": "2026-06-13T10:30:00Z"
}Use the email validation API example, email validation documentation, and API reference as the integration contract. Suppression, consent, and campaign eligibility remain separate business decisions.
Frequently asked questions
Continue this email validation api and bulk verification workflow with the commercial page, the core guide, the implementation docs.
Sources reviewed
Factual review: June 13, 2026 by WillItInbox Editorial.
Keep reading