EmailVerifyerAPI developer documentation

Getting started

The API answers one question well: can this address receive mail, and how confident are we? You send an address or a list, and you get back a verdict, the reason behind it, the individual checks that produced it, and a score you can threshold on.

Two surfaces exist. The public API is authenticated with an API key and is what your servers call. The session API backs the dashboard, uses cookies and CSRF, and is not intended for machine clients. This page documents the public API and describes the session API only so you know why you should not call it.

What the API does

What the API deliberately does not do

• It does not promise a mailbox exists. Catch-all domains accept every address, so the honest answer there is accept_all, not valid.
• It does not send email. Verification stops at the SMTP RCPT stage and no message is ever delivered.
• It does not score reputation or predict inbox placement. Those depend on your sending history, not on the address.
• It does not store the addresses you verify longer than your retention setting allows. See security and data handling.

Getting started

Three steps from nothing to a verdict. Pick your language once and every example on this page follows it.

1. Create a key. In the dashboard, open API keys, choose the scopes you need, and copy the key. The full value is shown once, at creation.
2. Put it in the environment, not in the source. The examples read EVA_API_KEY.
3. Call POST /verify and branch on data.status.

curl -sS -X POST https://www.emailverifyerapi.com/api/public/v1/verify \
  -H "Authorization: Bearer $EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

The response

{
  "data": {
    "email": "[email protected]",
    "status": "valid",
    "reason": "deliverable",
    "checks": {
      "syntax": true,
      "mx": true,
      "smtp": true,
      "disposable": false,
      "role": false,
      "free": false
    },
    "suggestion": null,
    "score": 0.98
  }
}

Getting started

Every public-API request carries an API key as a bearer token. There is no other authentication path: no query-string keys, no basic auth, no session cookies.

Authorization: Bearer mp_live_9f2c1d7a4b8e0c3f5a6d2b9e1c4f7a0d3b6e9c2f5a8d1b4e
Content-Type: application/json
Accept: application/json

Key anatomy

Scopes

Scopes are attached at creation and cannot be widened afterwards. Create one key per integration and give it the narrowest set that works.

A key missing the required scope gets 403 insufficient_scope, never a silent empty result.

Operating rules

• One key per environment and per service. Shared keys make the audit log useless and turn one rotation into an outage.
• Rotate on a schedule and on every departure. Create the new key, deploy it, then revoke the old one. Revoking first causes downtime.
• Revocation requires a fresh MFA challenge in the dashboard, and notifies every owner and admin on the tenant with the key prefix, the actor and the IP.
• Never ship a key to a browser or a mobile binary. Anything a user can install, a user can read. Proxy the call through your own backend.

Getting started

Keys are environment-tagged. A key beginning mp_test_ exercises the same routes, the same validation and the same response shape as a live key, and does not consume the plan's verification quota.

• Write your integration tests against the contract, not against a live domain. Real mailboxes change; the response shape does not.
• Assert on status and reason, and on the presence of the six checks keys. Do not assert on score to two decimal places: scoring inputs improve inside v1 without a version bump.
• Test the failure paths. A missing scope, an expired key, a 429 and a 402 are all things production will hand you eventually.

Pre-launch checklist

Core concepts

Two response shapes exist across the whole API. Nothing else is ever returned, which means one deserialiser and one error handler cover every endpoint.

// Success, single resource
{ "data": { ... } }

// Success, list endpoint
{ "data": [ ... ], "next_cursor": "eyJpZCI6…" }   // next_cursor is null on the last page

// Failure, every status code
{ "error": { "code": "rate_limited", "message": "Too many requests." } }

// Failure with field detail, only for 422 validation_failed
{ "error": { "code": "validation_failed", "message": "…",
             "fields": { "email": ["must be a valid address"] } } }

Request conventions

Core concepts

One object shape is returned by POST /verify and by every row of a batch result page. It is frozen by contract tests: renaming or removing any key below requires a new major version.

Core concepts

Verdicts are deterministic. The table is evaluated top down and the first matching row wins, so the same inputs always produce the same output. This is the whole decision function, published rather than described.

Every reason value

Thresholds worth copying

• Block at signup: status === "invalid". Nothing else is safe to block on without losing real customers.
• Warn at signup: suggestion !== null. A typo correction recovers a signup that a hard block would have lost.
• Exclude from a cold campaign: status !== "valid". Cold sending is where risky addresses cost you a domain reputation.
• Keep in a warm campaign: status !== "invalid". An engaged contact on a catch-all domain is still a customer.

Core concepts

Error codes are stable identifiers. Messages are prose and may be reworded at any time. Branch on error.code, log error.message, and never parse a message string.

{
  "error": {
    "code": "validation_failed",
    "message": "The request could not be processed.",
    "fields": {
      "emails": ["must contain between 1 and 500 addresses"]
    }
  }
}

Core concepts

Two independent ceilings apply. A rate limit caps how fast you may call. A quota caps how many verifications your plan includes. Hitting the first is a pacing problem; hitting the second is a billing decision.

Pacing that works

• Rate-limit yourself first. A client-side token bucket set just below your allowance costs one small class and removes most 429s.
• Prefer one batch to five hundred single calls. A batch is one request against the rate limit, and the work happens off your critical path.
• Honour Retry-After exactly. It is the only authoritative wait. Fall back to exponential backoff with jitter when the header is absent.
• Never run retries in an unbounded loop. Cap attempts, then surface the failure. Silent infinite retry is how one slow dependency becomes an outage.
• Alert on 402 separately. It means work stopped for a commercial reason, and no amount of engineering fixes it.

Core concepts

List endpoints are cursor-paginated. Cursors are opaque, stable under inserts, and cheap for the database, which is why there are no page or offset parameters to reach for.

GET /api/public/v1/batches/{id}/results?limit=100
  -> { "data": [ … 100 rows … ], "next_cursor": "eyJpZCI6IjAxOTIt…" }

GET /api/public/v1/batches/{id}/results?limit=100&cursor=eyJpZCI6IjAxOTIt…
  -> { "data": [ … 43 rows … ],  "next_cursor": null }      # done

• Stop when next_cursor is null. Never infer the end from a short page: a full page can still be the last one.
• Pass the cursor back verbatim. It is a signed, opaque token, not a row id. Editing it returns 400 bad_cursor.
• Do not cache a cursor across runs. Cursors belong to the resource they came from and are not addresses you can bookmark.
• limit is a maximum, not a promise. Handle a page shorter than you asked for.

API reference

Runs the full check chain against one address and answers synchronously. This is the endpoint a signup form calls.

Body

Response

A verification result object inside data. The call blocks for the length of the check chain, and the SMTP probe alone has a five-second budget, so allow at least ten seconds of client timeout.

{
  "data": {
    "email": "[email protected]",
    "status": "invalid",
    "reason": "no_mx",
    "checks": { "syntax": true, "mx": false, "smtp": false,
                "disposable": false, "role": false, "free": false },
    "suggestion": "[email protected]",
    "score": 0.0
  }
}

Errors specific to this route

• 422 validation_failed with fields.email when the input is not one address.
• 402 quota_exceeded when the plan's verifications are spent. The address is not consumed.
• 403 insufficient_scope when the key lacks verify:read.

API reference

Queues a list for asynchronous verification and returns immediately with an id and a status. Work happens on the queue, so a slow receiving server never blocks your request.

Body

// Request
{ "emails": ["[email protected]", "[email protected]", "[email protected]"] }

// Response
{ "data": { "id": "0192a7f4-9c31-7c2e-8b55-2f6ad1c40e77", "status": "queued" } }

API reference

Returns the job's current status. Poll it until the status leaves queued and running, then read the results.

API reference

Returns one result object per address, cursor-paginated.

{
  "data": [
    { "email": "[email protected]", "status": "valid", "reason": "deliverable",
      "checks": { "syntax": true, "mx": true, "smtp": true,
                  "disposable": false, "role": false, "free": false },
      "suggestion": null, "score": 0.98 },
    { "email": "[email protected]", "status": "risky", "reason": "role",
      "checks": { "syntax": true, "mx": true, "smtp": true,
                  "disposable": false, "role": true, "free": false },
      "suggestion": null, "score": 0.6 }
  ],
  "next_cursor": "eyJpZCI6IjAxOTJhN2Y0LTljMzEtN2MyZS04YjU1In0"
}

Results become readable as they are produced, so a long job can be consumed incrementally rather than waiting for completed. Rows are stable once written: re-reading a page returns the same verdicts.

Guides

The full flow: chunk, submit, poll, page, write. The example below is the same program in every language, and it is the one most integrations actually need.

1. Chunk at 500. One request per chunk, and a failure costs you one chunk rather than the whole file.
2. Submit and keep the id. Persist it before you start polling, so a crashed job can be resumed rather than resubmitted.
3. Poll every five seconds until the status leaves queued and running.
4. Page the results with limit=100 and follow next_cursor until it is null.
5. Write the verdicts next to your own ids, not over the top of the addresses. You will want to audit the decision later.

# Create the batch, poll it, then page the results.
BATCH=$(curl -sS -X POST https://www.emailverifyerapi.com/api/public/v1/batches \
  -H "Authorization: Bearer $EVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]"]}' | jq -r '.data.id')

What to do with the verdicts

Guides

Real-time verification at signup is the highest-value integration and the easiest one to get wrong. The failure mode is not a bad address getting through: it is a real customer being blocked by a slow or inconclusive probe.

Rules that hold up in production

• Verify on blur, not on every keystroke. One call per address, after the field loses focus.
• Never block the submit button on the network. Give the call a short deadline of about two seconds; if it has not answered, accept the signup and verify asynchronously.
• Block only invalid. Blocking risky or unknown rejects paying customers on catch-all corporate domains, which is most enterprise buyers.
• Offer suggestion as a one-tap fix. Show "did you mean [email protected]?" with a button that fills the field. Never rewrite what a user typed.
• Call from your backend. A key in front-end JavaScript is a public key.
• Say why. "That address does not exist" is actionable; "invalid email" is not.

Guides

Every integration needs a retry policy, and most have one that makes outages worse. This is the policy the service is designed for.

# Retry 429 and 5xx only. Honour Retry-After when the server sends it.

Policy

Timeout budgets

• POST /verify: at least 10 seconds. The SMTP probe holds a 5-second budget of its own, and a tighter client timeout manufactures false unknown results.
• POST /batches: 10 seconds. The call only enqueues; it does not wait for verification.
• Reads: 5 seconds is generous.

Repeating a write safely

The public API has no idempotency-key header, so a timed-out POST /batches is genuinely ambiguous: the batch may exist. Two habits remove the ambiguity.

• Persist your own correlation id with the chunk before you call, and store the returned batch id against it. On a timeout, look up the correlation id rather than resubmitting blindly.
• Make the consumer tolerant of duplicates. Keying results by address means a resubmitted chunk costs quota, not correctness.

Guides

The dashboard runs on a second, larger API at /api/v1. It is authenticated with a session cookie, requires a CSRF token on every write, and enforces roles and step-up MFA. It exists for the browser application, and it is documented here so that you do not build against it by mistake.

Guides

v1 has no outbound webhooks. Batch completion is discovered by polling GET /batches/{id}, which the bulk guide shows in every language. Saying so plainly is more useful than a page describing an endpoint that does not answer yet.

What to build in the meantime

• One poller per job, five seconds apart, with a ceiling. Stop when the status is terminal or when your own deadline passes.
• Consume results incrementally. Rows are readable before the job reports completed, so a long job can feed a pipeline continuously.
• Do not poll from a request handler. Enqueue the poll in a background worker; a user-facing request should never wait on a batch.

When webhooks arrive

Outbound webhooks are a gated feature in development. Adding a route and a signed callback is a non-breaking change under the versioning policy, so it will land inside v1, appear in the changelog, and require no migration from anyone who is polling. The one inbound webhook the platform already operates is the Stripe billing callback, which is signature-verified and not part of the public API.

Guides

Tenants can register Model Context Protocol servers in the dashboard, over stdio or HTTP, so an agent can reach verification through a tool call rather than a hand-written HTTP client.

• Credentials are sealed. Bearer tokens and secrets attached to an MCP server are field-encrypted at rest and never returned by a read. You can replace one; you cannot retrieve it.
• Give an agent its own API key, scoped to verify:read only. Agents are exactly the class of caller that should not hold verify:write.
• Every call stays attributable. Usage is recorded against the key id, so an agent's spend is visible next to everything else.
• Point the model at this page. The copy buttons above emit Markdown built from the live DOM, so what a model reads is what the page says, not a stale mirror of it.

Platform

For an API-first product this is a customer commitment, not an operational detail. It is published so you can plan against it.

Scheme

• The major version lives in the path: /api/public/v1. There are no date-based versions, no header negotiation, and no v1.1.
• A major version increments only for a breaking change. Everything else ships continuously inside v1 with no version signal.
• At most two majors run at once, the current one and its predecessor.

What counts as breaking

status is a closed enum and reason is open. That single distinction is what lets you switch exhaustively on one and never on the other.

Deprecation timeline

An announced sunset date can be extended and never shortened. Enterprise agreements may negotiate longer windows, never shorter ones.

Platform

Verification means handling other people's contact data, so the handling rules matter as much as the endpoint list.

Your side of the line

• Verify only addresses you have a lawful reason to hold. A verification service is not a discovery service, and bought lists stay bought lists.
• Do not log full addresses at debug level. Log the verdict and a hash if you need to correlate.
• Keep keys out of client applications and out of source control.
• Report anything you find to the contact in security.txt. See the security page for scope.

Platform

Every change to the public contract lands here first. Non-breaking additions ship inside v1 continuously; anything breaking follows the deprecation timeline.

2026-08-20 · Documentation

This reference published: full v1 surface, the decision table, the error registry, and runnable examples in fourteen languages. Section and whole-page Markdown export added for model consumption.

2026-08-20 · Policy

Versioning and deprecation policy published, including the Deprecation, Sunset and Link response headers and the endpoint_sunset error code.

2026-08-13 · Tools

MX, SPF, DKIM and DMARC checkers extended with transport-security records. Free, no key required.

Q3 2026 · API

v1 public API in early access. Request a key.

Platform

Accept-all (catch-all) domain

A domain configured to accept mail for every local part. An SMTP probe cannot distinguish a real mailbox from a nonexistent one there, which is why the honest verdict is risky with reason accept_all.

Batch

An asynchronous verification job created by POST /batches, holding up to 500 addresses and identified by a UUID.

Cursor

An opaque token identifying a position in a result set. Passed back unchanged as cursor; null in next_cursor means the walk is finished.

Greylisting

A receiving server deliberately deferring a first delivery attempt. It produces unknown, not invalid.

Idempotent

Safe to repeat with the same effect. Every GET here is idempotent; POST /batches is not, so it needs a correlation id on your side.

Open enum

A field that may gain values without a major version bump. reason is open; status is closed.

Quota

The verifications your plan includes per billing period. Exhaustion returns 402 quota_exceeded.

Rate limit

A ceiling on request frequency per key. Exhaustion returns 429 rate_limited with Retry-After.

Role account

A shared function mailbox such as info@, sales@ or abuse@. Deliverable, and rarely a person.

Scope

A capability attached to an API key at creation: verify:read, verify:write or jobs:read. A missing scope returns 403 insufficient_scope.

SMTP probe

A conversation with the receiving server that stops at the RCPT stage. No message is ever sent.

Step-up authentication

A fresh MFA challenge required for sensitive dashboard actions, including revoking a key. It has a five-minute window.

Platform