Introduction

Welcome to the EmailValidator API documentation. EmailValidator provides fast, accurate email address verification via a simple REST API and bulk CSV upload.

On this page

What EmailValidator does

EmailValidator checks whether an email address is deliverable by performing a layered set of probes at build time:

  1. Format check — verifies the address conforms to RFC 5321.
  2. DNS / MX lookup — confirms the domain has a valid mail exchanger.
  3. SMTP probe — connects to the mail server and tests whether the mailbox accepts mail.
  4. Disposable / free detection — flags addresses from known temporary or consumer mail providers.
  5. Role-address detection — identifies aliases such as admin@, support@, or noreply@.

The result is a structured JSON object that tells you not just deliverable or invalid, but why — including the specific sub-status, MX record, SMTP provider, and more.

Outcomes overview

A verification carries two independent things, on two fields. status answers has it finished?; result.outcome answers what did we conclude?

Field Answers Values
status Has it finished? pending, complete
result.outcome What did we conclude? deliverable, invalid, catch-all, unknown

result (and recovery) are null while status is pending. The verdict vocabulary is:

result.outcome Meaning
deliverable Mailbox confirmed deliverable via SMTP
invalid Mailbox does not exist or hard-rejected
catch-all Domain accepts all addresses; deliverability unconfirmable
unknown Could not determine — DNS failure, transient error, or no SMTP probe data

result.sub_status adds the reason within an outcome, and result.risk is a single planning signal. See Outcomes for both references in full.

Two ways to validate

Single address — submit one email via POST /api/v1/verify and receive a result synchronously (or poll if the timeout is exceeded). Ideal for real-time signup validation.

Batch — upload a CSV file via POST /api/v1/verify/batch and poll for job completion. Results are available as pre-signed CSV and JSON download URLs. Ideal for cleaning existing lists.

Next steps