email-validation.org
Sign in Get 500 free credits

Documentation

email-validation.org checks email addresses through a REST API, in bulk lists and from AI agents. Every result has a status, a reason and a recommended action, and results with the status unknown never cost a credit.

New here? The quickstart takes you from an API key to your first result in a few minutes, using free test addresses that cost nothing.

Get started

  • Quickstart: Create an API key, send your first request with curl, JavaScript or Python, and read the result. Uses the 500 free credits you get when you sign up.
  • Authentication: How to create, use, rotate and revoke API keys. Keys go in the Authorization header, never in URLs. Includes examples and the common auth errors.
  • Test addresses: Addresses that return each status and reason for free, so you can test your integration end to end without spending any credits or calling out.

API

  • Validate an email: Reference for the single email validation endpoint: request parameters, response fields, status and reason values, credits used and examples.
  • Credit balance: Read your remaining credit balance, any debt and your expiring credit lots through the API, with request and response examples and the errors.
  • Usage: Read daily credit usage for your account or for each API key: exact credit totals, an approximate breakdown by status, and request examples.
  • Bulk jobs API: Create a bulk job from a CSV or TXT body or a JSON list, follow its progress, download filtered results and cancel it. Up to 1,000,000 rows per file.
  • API reference: Every endpoint, parameter and schema of the email-validation.org REST API, generated from the OpenAPI 3.1 spec. Download the spec as JSON or YAML.

Results

  • Statuses: What deliverable, undeliverable, risky and unknown mean, every reason code, which results cost a credit, and the recommended action for each one.
  • Deliverable: What a deliverable result means, its reasons (accepted, alias, catch-all with a good record and more), why it can still bounce, and when to send.
  • Undeliverable: Why an address is undeliverable: a missing mailbox, bad syntax, a likely typo, no mail records and more, plus what to do with each of these reasons.
  • Risky: Catch-all domains, role addresses, disposable inboxes, traps and complainers: what each risky reason means and how to decide whether to send.
  • Unknown: Why a check can end as unknown (greylisting, timeouts, anti-spam blocks), why unknown results never cost a credit, and when to check again.

Operate

  • Errors: Every error code the API returns, the HTTP status that comes with it, why no credits are used for errors, and how to retry safely with backoff.
  • Rate limits: Paid accounts can send up to 500 validation requests per second. How limits are counted, the 429 response, Retry-After and the 15-second timeout.
  • Credits and billing: How credits work: one per result, unknown results and errors free, +15% bonus on your first 3 payments, 24-month expiry and the no-refund rule.
  • Bulk list verification guide: Prepare a CSV, XLSX or TXT file, upload up to 1,000,000 rows, follow progress, download results, and understand the 30-day automatic deletion.
  • Webhooks: Get notified when a bulk job finishes or credits run low: event types, payload schema, signature verification, retries and example handlers.

Integrations

  • SDKs: Install the official JavaScript/TypeScript and Python SDKs to validate emails, run bulk jobs and handle errors, with copy-paste examples.
  • JavaScript & TypeScript SDK: Install the JavaScript and TypeScript SDK from npm, validate an email, run a bulk job and verify webhooks. Tested on Node.js 24, no dependencies.
  • Python SDK: Install the official Python SDK from PyPI, validate an email, run a bulk job and verify webhook signatures, with copy-paste examples for each step.
  • Code samples: Copy-paste examples for curl, JavaScript, TypeScript, Python, PHP, Ruby, Go, Java, C# and Rust that validate an email and handle errors and rate limits.
  • MCP server setup: Connect the MCP server to your AI client with an API key: the tools it offers, limits, credits, example prompts and setup steps for common clients.
  • No-code recipes: Call the email validation API from Zapier, Make, n8n or Google Sheets through their HTTP request steps, with the API key in the Authorization header.
  • Sign-up forms: Check addresses at sign-up without blocking real users: when to call the API, how to treat risky and unknown results, timeouts and UX copy examples.

How the API fits together

  • One address at a time: POST https://api.email-validation.org/v1/validate returns a result in up to 15 seconds. See Validate an email.
  • Lists: upload a CSV or text file, or send a JSON list, and download the results when the job is done. See the bulk jobs API or the dashboard guide.
  • Your account: read your credit balance and usage.
  • Notifications: webhooks tell your server when a bulk job ends or credits run low.
  • AI agents: the MCP server offers the same checks as tools, with the same key and credits.

The whole API is described by an OpenAPI 3.1 document; the API reference is generated from it.

Updated · Maintained by the email-validation.org team