Email validation API reference

Overview

All requests go to the base URL below over HTTPS. Requests and responses use JSON, and responses are UTF-8 encoded.

Authentication

Authenticate every request with your API key. The recommended method is the Authorization header:

Authorization: Bearer ev_your_api_key

The API also accepts an X-API-Key: ev_your_api_key header, or an api_key query parameter for quick tests. Keep your key on your server. Anyone who has it can use your quota.

Validate an address

Validates a single address. Use GET with a query parameter, or POST a JSON body.

Parameters

Example

curl "https://validateemail.io/v1/validate?email=jane.doe@gmail.com" \
  -H "Authorization: Bearer $VALIDATEEMAIL_KEY"

curl -X POST "https://validateemail.io/v1/validate" \
  -H "Authorization: Bearer $VALIDATEEMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@gmail.com"}'

const res = await fetch("https://validateemail.io/v1/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VALIDATEEMAIL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane.doe@gmail.com" }),
});
const result = await res.json();

Batch validation

Validates up to 100 addresses in one request. Results come back in the same order you sent them. Each distinct domain is looked up once per batch, so batches are much faster than the same number of single calls.

curl -X POST "https://validateemail.io/v1/validate/batch" \
  -H "Authorization: Bearer $VALIDATEEMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["jane@gmail.com", "info@acme.io", "bob@gmial.com"]}'

The response is an object with a results array. Each entry has the same shape as a single-address response:

{ "results": [ { "email": "jane@gmail.com", "status": "valid", … }, … ] }

Response format

{
  "email": "bob@gmial.com",
  "normalized": "bob@gmial.com",
  "user": "bob",
  "domain": "gmial.com",
  "status": "risky",
  "reason": "possible_typo",
  "score": 0.5,
  "did_you_mean": "bob@gmail.com",
  "checks": {
    "syntax": true,
    "domain_exists": true,
    "mx_found": true,
    "disposable": false,
    "role_based": false,
    "free_provider": false,
    "smtp": null
  },
  "mx_records": [{ "exchange": "mx.gmial.com", "priority": 10 }],
  "cached": false,
  "checked_at": "2026-10-21T14:37:17.479Z"
}

Statuses & reasons

When several risk signals apply, the most significant one is reported as the reason. Every signal is still visible in checks.

Errors

Errors use standard HTTP status codes and a consistent JSON body:

{ "error": { "code": "unauthorized", "message": "Invalid or revoked API key" } }

Caching

To keep responses fast, results are cached: per address for 7 days, and per domain (DNS and list checks) for 24 hours. A cached response has "cached": true and keeps the original checked_at. Temporary DNS failures are never cached. Add fresh=true to force a re-check.

Best practices

• Call from your backend. Your key should never ship in browser or mobile code.
• Block invalid, review risky. Decide per use case. A newsletter might accept role accounts, while a free trial might reject disposable inboxes.
• Show did_you_mean. Offering the fix inline recovers sign-ups that would otherwise bounce.
• Treat unknown as a soft pass. Accept the address and re-validate later rather than blocking a real user.
• Use batch for lists. It's one round-trip, and shared domains are only looked up once.