# Documentation URL: https://email-validation.org/docs/ Updated: 2026-10-20 > Documentation index: https://email-validation.org/llms.txt 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](https://email-validation.org/docs/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](https://email-validation.org/docs/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](https://email-validation.org/docs/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](https://email-validation.org/docs/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](https://email-validation.org/docs/api/validate/): Reference for the single email validation endpoint: request parameters, response fields, status and reason values, credits used and examples. - [Credit balance](https://email-validation.org/docs/api/credits/): Read your remaining credit balance, any debt and your expiring credit lots through the API, with request and response examples and the errors. - [Usage](https://email-validation.org/docs/api/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](https://email-validation.org/docs/api/bulk/): 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](https://email-validation.org/docs/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](https://email-validation.org/docs/statuses/): What deliverable, undeliverable, risky and unknown mean, every reason code, which results cost a credit, and the recommended action for each one. - [Deliverable](https://email-validation.org/docs/statuses/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](https://email-validation.org/docs/statuses/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](https://email-validation.org/docs/statuses/risky/): Catch-all domains, role addresses, disposable inboxes, traps and complainers: what each risky reason means and how to decide whether to send. - [Unknown](https://email-validation.org/docs/statuses/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](https://email-validation.org/docs/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](https://email-validation.org/docs/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](https://email-validation.org/docs/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](https://email-validation.org/docs/bulk/): 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](https://email-validation.org/docs/webhooks/): Get notified when a bulk job finishes or credits run low: event types, payload schema, signature verification, retries and example handlers. ## Integrations - [SDKs](https://email-validation.org/docs/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](https://email-validation.org/docs/sdks/javascript/): 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](https://email-validation.org/docs/sdks/python/): 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](https://email-validation.org/docs/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](https://email-validation.org/docs/mcp/): 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. - [AI agents](https://email-validation.org/docs/ai-agents/): Connect AI agents with an API key: MCP server, A2A endpoint, Agent Skill, WebMCP on the free checker, auth.md and the discovery files agents read. - [No-code recipes](https://email-validation.org/docs/guides/no-code/): 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](https://email-validation.org/docs/guides/signup-form-validation/): 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](https://email-validation.org/docs/api/validate/). - **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](https://email-validation.org/docs/api/bulk/) or the [dashboard guide](https://email-validation.org/docs/bulk/). - **Your account:** read your [credit balance](https://email-validation.org/docs/api/credits/) and [usage](https://email-validation.org/docs/api/usage/). - **Notifications:** [webhooks](https://email-validation.org/docs/webhooks/) tell your server when a bulk job ends or credits run low. - **AI agents:** the [MCP server](https://email-validation.org/docs/mcp/) offers the same checks as tools, with the same key and credits. The whole API is described by an [OpenAPI 3.1 document](https://api.email-validation.org/openapi.json); the [API reference](https://email-validation.org/docs/api-reference/) is generated from it.