EmailValidly API
Verify an address from your application with explicit syntax, mail-routing, disposable-domain and mailbox signals. The authenticated API uses your workspace's verification credits.
1. Create a key
API access is available with Growth and Pro when paid plans launch. Open your workspace, create a labelled API key, and copy it once. Store it on your server as a secret. Never put a key in browser JavaScript, a mobile bundle, or a public repository. Revoke a compromised key in the workspace and create a replacement.
2. Verify an address
Send JSON to POST https://www.emailvalidly.com/v1/verify. Include a Bearer token and an Idempotency-Key for every request.
curl https://www.emailvalidly.com/v1/verify \
-H "Authorization: Bearer $EMAILVALIDLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-unique-event-001" \
-d '{"email":"person@example.com","deep":false}'email is required, up to 254 characters. deep is optional and defaults to false; true requests SMTP and catch-all probing. A deeper check costs the same one credit. The returned result may still be unknown when the receiving system refuses a probe.
3. Interpret the response
The example below illustrates a domain that explicitly does not accept mail; it is not a successful inbox verification.
{
"email": "person@example.com",
"status": "invalid",
"checks": {
"syntax": true, "domain": true, "mx": false,
"disposable": true, "role": true,
"mailbox": null, "catch_all": null
}
}| Status | Meaning | Suggested handling |
|---|---|---|
| valid | Mailbox probe accepted the address without a detected risk flag. | Continue normal consent and delivery checks. |
| likely_valid | Syntax and mail routing look usable; no conclusive mailbox result. | Keep uncertainty visible. |
| risky | Disposable, role-based or catch-all signal. | Review in context; a role address can be legitimate. |
| invalid | Invalid syntax, nonexistent domain, explicit null MX, or mailbox rejection. | Ask for a correction or suppress after review. |
| unknown | Insufficient or temporary DNS/SMTP evidence. | Retry later; do not treat as definitely invalid. |
The boolean fields disposable and role are pass checks: true means not disposable or not role-based. For catch_all, true means a random address was accepted. A null value means the check was not performed or was inconclusive. The numeric score is a heuristic summary, not a measured probability of delivery.
Retries and credit accounting
Use a unique Idempotency-Key of 8–100 letters, digits, underscores or hyphens per logical verification. Reusing it with the same input returns the stored result without another charge. Reusing it for a different email or deep setting returns 409. If an in-flight request returns 409, wait and retry with the same key. Use a fresh key only when you intentionally want a new verification.
One credit is reserved before verification. Insufficient balance returns 402 before a probe starts. Internal verification exceptions are refunded. An inconclusive but completed DNS or SMTP check is still a verification and uses a credit.
| HTTP code | Action |
|---|---|
| 400 | Correct the input or idempotency key. |
| 401 | Check the API key and active plan. |
| 402 | Add credits when billing becomes available. |
| 409 | Retry an in-flight request or correct a reused key. |
| 429 | Wait for the Retry-After interval. |
| 500 / 503 | Retry with backoff and the same idempotency key. |
The current API limit is 120 requests per minute per IP. Apply exponential backoff with jitter and cap concurrency. Responses are private and are not cacheable by shared HTTP caches.
Free diagnostic endpoints
The public website uses rate-limited endpoints for individual checks. They do not require API keys and are intended for interactive tools, not a substitute for the paid API.
- POST /api/verify — email, optional smtp and catch_all booleans.
- POST /api/bulk — emails array, maximum 100 and daily bulk allowance.
- GET /api/syntax?email=… — structural check.
- GET /api/mx?domain=… — mail exchangers.
- GET /api/disposable?email=… — disposable-domain lookup.
- GET /api/auth-records?domain=… — SPF and DMARC records.
- GET /api/dkim?domain=…&selector=… — selector-specific DKIM lookup.
Limits of verification
No endpoint sends a message. SMTP probes stop before the message body stage. Acceptance is not proof of ownership, permission to contact, or future inbox placement. Use a confirmation email in your own application when ownership matters. Review the data handling policy before submitting a list.