# EMAIL-CHECK.APP API Documentation

> Email validation API for production applications: MX and SMTP mailbox verification, disposable and free-provider detection, name detection, and domain intelligence.

The API is served at `https://api.email-check.app` (the same API is also reachable same-origin at `https://email-check.app/api`). All endpoints authenticate with an `x-api-key` header and are billed per call.

## Start here

- Interactive API reference (with one-click MCP install buttons): https://email-check.app/open-api
- MCP integration guide for AI agents: https://email-check.app/guides/mcp-server
- OpenAPI document (machine-readable, this is the contract): https://email-check.app/json/open-api.json
- Pricing and credit packs: https://email-check.app/pricing
- Live demo in the browser: https://email-check.app/try
- Guides: https://email-check.app/guides
- Technical articles: https://email-check.app/blog

## MCP server for AI agents

- Endpoint: https://api.email-check.app/mcp
- Transport: Streamable HTTP — POST JSON-RPC 2.0, header `Accept: application/json, text/event-stream`
- Auth: `x-api-key` header with a product API key (host-scoped; cross-product keys are rejected with A1003)
- Demo access: key `demo-key` with a valid TOTP in `x-ct` (rate-limited, evaluation only)
- Billing: 1 credit per tool call; `account_whoami` is free; HTTP 402 means out of credits (top up at https://email-check.app/pricing)
- Tools: - account_whoami (free identity probe)
- email_validate (verifyMx, verifySmtp, detectName, suggestDomain, checkDomainAge, checkDomainRegistration, smtpDebug)
- Discovery: https://email-check.app/.well-known/mcp/server-card.json · this llms.txt · the Scalar MCP panel on /open-api
- Supported clients: Claude Code, Claude (claude.ai + Desktop), Codex (CLI, IDE extension, ChatGPT desktop app), Cursor, VS Code (Copilot), Windsurf, Cline, Continue, Zed, Gemini CLI, and any client that speaks Streamable HTTP.
- The server returns agent instructions in the MCP initialize result.

## Authentication and errors

- `x-api-key` header (or `x-api-key` query parameter) — create keys at https://email-check.app/account/api-keys. Keys are scoped to this product host.
- `x-jwt-token` header — session alternative; when both are present the API key wins.
- Error envelope: `{ "error": "CODE", "message": "...", "issues": [...] }`. Auth codes: A1001 missing credential, A1002 malformed key, A1003 unknown/disabled key or cross-host key, A1004 invalid TOTP, A1006 unverified account, A1008 authentication required, A1009 admin required.
- Rate limits: guest limits are strict and per-IP; authenticated keys get plan-based limits (429 with Retry-After when exceeded).

## API endpoints

### API Key
- `POST /v1-create-api-key` — Create API key: Generate a new API key for Email-Check.app integrations.
- `POST /v1-delete-api-key` — Delete API key: Delete an API key owned by the authenticated account.
- `POST /v1-get-api-key-details` — Get API key details: Fetch details for one API key owned by the authenticated account.
- `POST /v1-list-api-keys` — List API keys: List API keys for the authenticated Email-Check.app account.
- `POST /v1-update-api-key` — Update API key: Update an API key name, enabled state, or service access.
- `GET /v1-who-am-i` — Get current identity: Return the account or API-key identity associated with the request credentials.

### API Usage
- `GET /v1-download-api-usage` — Download API usage export: Download usage data for reporting or billing review.
- `GET /v1-get-api-usage` — Get API usage: Fetch API usage metrics for the authenticated account.

### Email
- `GET /v1-get-email-details` — Validate email address: Validate and enrich a single email address.

### Bulk Email
- `POST /v1-upload-email-json` — Upload bulk email validation batch: Upload a CSV-derived email batch for bulk validation.
- `POST /v1-list-upload-email-json` — List bulk email validation batches: List bulk email validation batches for the authenticated account.
- `POST /v1-download-email-json` — Download bulk email validation results: Download processed records for a bulk email validation batch.
- `POST /v1-resume-email-json` — Resume bulk email validation batch: Retry or resume a stuck or failed bulk email validation batch.

## Workflows

- Signup screening — validate the address with email_validate before creating the account.
- CRM hygiene — re-validate stored addresses through the bulk JSON upload endpoints.
- Bounce prevention — enable verifySmtp for high-value sends; fall back to verifyMx for bulk.
- Fraud review — disposable and free-provider detection feed risk scoring.

## Notes for agents

- All lookups are read-only and cache-backed; pass `skipCache=true` only when freshness matters.
- The bulk JSON upload endpoints run asynchronously: upload, poll list status, then download results.
- Tool calls over MCP and REST calls cost the same credits and return the same data shapes.