API Reference
All endpoints. No authentication required.
POST /
Validate a single email address.
{
"email": "user@example.com",
"quick": false,
"force": false
}
| Field | Type | Description |
|---|---|---|
email | string | Required. Email address to validate. |
quick | boolean | Skip enrichment/security (Tier 1 only). Default false. |
force | boolean | Bypass cache. Default false. |
pow | object | Proof-of-work solution (for unlimited access). See protocol → |
POST /batch
Validate up to 20 emails in one request.
{
"emails": ["user@example.com", "admin@test.org"],
"quick": false
}
GET /health
Health check. Returns {"status":"ok","version":"1.0.0"}.
Response
The response has three top-level fields you care about:
{
"email": "user@gmail.com",
"action": "allow", // allow | verify | block
"confidence": "valid", // valid | likely_valid | risky | invalid | unknown
"validation": { ... }, // detailed signals
"_meta": { ... } // timing, cache status, version
}
The action field
This is the product. One field, three values:
- allow — safe to accept. Good syntax, valid MX, not disposable.
- verify — probably fine, but send a confirmation email. Catch-all provider, role account, etc.
- block — reject at signup. Invalid syntax, no MX, disposable, or domain doesn't exist.
Validation signals
| Signal | Type | Description |
|---|---|---|
syntax_valid | boolean | RFC 5321 compliance |
mx_found | boolean | Domain has MX records |
null_mx | boolean | Domain explicitly refuses email (RFC 7505) |
disposable | boolean | Known disposable/temporary domain |
privacy_relay | boolean | Apple HME, SimpleLogin, etc. (not disposable) |
free_provider | boolean | Gmail, Yahoo, Outlook, etc. |
role_account | boolean | admin@, info@, support@, etc. |
has_typo | boolean | Domain looks like a typo |
typo_suggestion | string|null | Corrected email if typo detected |
provider | object|null | Identified email provider with behavior hints |
subaddressed | boolean | Contains + tag (e.g. user+tag@) |
is_ip_literal | boolean | Domain is an IP literal ([1.1.1.1]) |
is_internationalized | boolean | Uses internationalized characters (EAI/IDN) |
is_punycode | boolean | Domain contains punycode labels (xn--) |
domain_type | string|null | "domain" or "ip_literal" |
catch_all_likely | boolean | Domain likely accepts all addresses (catch-all) |
catch_all_reason | string|null | Why catch-all is suspected ("provider_default") |
Rate Limits
Free tier: 10 requests/hour + 50/day per IP.
Need more? Solve a proof-of-work challenge (SHA-256 hashcash, difficulty 20, ~2–8s CPU) and include the solution in your request. Unlimited with valid PoW. Full PoW protocol docs →
Cross-origin
Full CORS support. Access-Control-Allow-Origin: * on all responses.