Introduction

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

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 valid or invalid, but why — including the specific sub-status, MX record, SMTP provider, and more.

Outcomes overview

Every validated address is assigned a top-level status and an optional sub_status:

status Meaning
valid 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

See Outcomes for the full sub_status reference.

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