EmailValidly API

Put the checks where an address enters your product.

From input to a decision

1. Receive an address on your server.
2. Call the API with a stable request identifier.
3. Store status and individual checks.
4. Apply your correction or review policy.

Use deep: false for syntax, DNS and risk checks. Set deep: true to request SMTP and catch-all probes too. Providers can block or limit probes, so a requested check may remain inconclusive.

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
  }
}

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.

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.

Before you ship an integration

API questions