API Guide

Quickstart

Three steps from zero to a verified address.

1. Create an account and an API key

Sign up (300 free verifications a month, no credit card), then open API Keys in the dashboard and create a key. Keys start with eva_ and are shown once, so store it in your environment rather than in code.

2. Verify your first address

curl "https://verifications.email/api/v1/verify?email=user@gmail.com" \
  -H "X-API-Key: $EVA_API_KEY"

import { EvaClient } from '@verifications-email/sdk';

const eva = new EvaClient({ apiKey: process.env.EVA_API_KEY });
const { data } = await eva.verify('user@gmail.com');

console.log(data.risk, data.score); // "safe" 94

import os
from eva_email import EvaClient

eva = EvaClient(api_key=os.environ["EVA_API_KEY"])
result = eva.verify("user@gmail.com")

print(result.data.risk, result.data.score)  # safe 94

3. Read the result

Every response is wrapped in a data envelope. The two fields most integrations act on are risk and score; the rest is the evidence behind them.

{
  "data": {
    "email": "user@gmail.com",
    "score": 94,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": true,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "smtp_provider": "google",
    "deliverability": {
      "grade": "A",
      "score": 92,
      "authentication": { "spf": "strict", "dkim": "found", "dmarc": "reject" },
      "blacklist": { "listed": false, "listed_count": 0, "high_confidence_count": 0, "total_checks": 10, "evaluated_checks": 10 }
    }
  }
}

See Understanding results for what each field means and what to do with each verdict. The reference lists every field.

Authentication

Every request carries your API key in the X-API-Key header. Keys are the string eva_ followed by 64 hexadecimal characters. Create, name, and revoke keys under API Keys in the dashboard; a revoked key stops working immediately.

X-API-Key: eva_3f9c2a1b8e7d4c6f0a9b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f

• Keep keys on the server. A key in browser or mobile code can be read by anyone who loads the page.
• A missing or unknown key returns 401 UNAUTHORIZED. A key on a suspended account, or one that may not perform the action, returns 403 FORBIDDEN.
• Dashboard sessions use a separate JWT; you never need it for verification.

Understanding results

A result has two verdict fields and a set of evidence fields. Start with risk; use the rest to decide how much to trust it.

Verdicts

What to do with each verdict

Greylisting

Some mail servers refuse the first contact from an unfamiliar sender with a temporary error and accept a retry a few minutes later. That is greylisting, and it is the most common reason for an unknown result. EVA handles it differently depending on how you call it.

• Single and batch verification run under a 15-second request deadline, so a greylisting server comes back as unknown instead of holding your request. The result is not billed, the domain is remembered as a greylister, and a retry a few minutes later usually resolves it.
• Bulk jobs absorb the wait for you. Addresses that came back unknown for a temporary reason are re-probed while the job is still running, up to three times: a greylisting server that names its window is retried after that window, otherwise after one, two and four minutes; a rate-limited exit is retried from a different outbound IP after a minute. Once the last address of the list has been processed, the job waits up to five more minutes for retries already scheduled, then finishes; anything still waiting at that point, or in the middle of a retry, stays unknown for Re-run unknowns. Addresses whose cause cannot change within minutes, such as a mail server that blocks our IP outright or a domain whose mail host is down, are not retried inside the job.
• Re-run unknowns covers whatever is still unresolved after the job completes. It unlocks 30 minutes later, when greylist windows have typically cleared, and creates a follow-up job with only those addresses.

unknown never means invalid. Treat it as "ask again later", not as a reason to drop the address.

Evidence fields

Every field, including the provider-specific ones, is listed in the reference.

Rate limits and quotas

Two limits apply to every key: a per-minute request budget and a monthly quota of verifications. Both depend on your plan.

• A batch request counts every address in its body against the per-minute budget, not just the one call.
• Unknown results are not counted against the monthly quota. When a call was paid with credits, the credits for unknown results are returned. Pay-as-you-go credit packs extend it at a flat $1.20 per 1,000 and never expire.
• The official libraries retry rate-limited requests automatically with backoff.

Headers

Exceeding the per-minute budget returns 429 RATE_LIMITED with Retry-After: 60. Using up the monthly quota returns 429 QUOTA_EXCEEDED, with X-RateLimit-Reset set to the end of the billing window. Accounts on the Free plan without credits also have a limit of 50 checks a day: past it, single, batch and domain deliverability checks return 429 DAILY_LIMIT with X-Daily-Limit, X-Daily-Remaining (what is left today: 0, or more when a batch is larger than what is left) and Retry-After (seconds until 00:00 UTC). Successful checks on such an account carry X-Daily-Limit and X-Daily-Remaining. Any plan or credit pack removes the limit.

Errors

Errors use one shape: a human-readable message and a stable code you can branch on.

{ "error": "rate limit exceeded", "code": "RATE_LIMITED" }

Single verification

GET /api/v1/verify?email=… or POST /api/v1/verify with a JSON body {"email": "…"}. Both return the same result. Most addresses come back in under a second. A server that greylists first contact returns unknown within the 15-second deadline; see Greylisting.

# GET
curl "https://verifications.email/api/v1/verify?email=user@gmail.com" \
  -H "X-API-Key: $EVA_API_KEY"

# POST
curl -X POST https://verifications.email/api/v1/verify \
  -H "X-API-Key: $EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@gmail.com"}'

const { data, rateLimit } = await eva.verify('user@gmail.com');

if (data.risk === 'invalid') {
  reject(data.suggested_correction);   // "user@gmail.com" for a typo like gmial.com
} else if (data.risk === 'unknown') {
  retryLater();                        // not billed; the server gave no definitive answer
}
console.log(rateLimit.remaining);      // requests left this minute

result = eva.verify("user@gmail.com")
data = result.data

if data.risk == "invalid":
    reject(data.suggested_correction)   # e.g. "user@gmail.com" for a typo like gmial.com
elif data.risk == "unknown":
    retry_later()                       # not billed; the server gave no definitive answer

Batch (up to 100)

POST /api/v1/verify/batch verifies up to 100 addresses in one synchronous call. Duplicates are removed before processing. Each address counts against your per-minute budget. For anything larger, use a bulk job.

curl -X POST https://verifications.email/api/v1/verify/batch \
  -H "X-API-Key: $EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "info@example.com", "nobody@mailinator.com"]}'

const { data } = await eva.verifyBatch([
  'user@gmail.com', 'info@example.com', 'nobody@mailinator.com',
]);

for (const r of data.results) {
  console.log(r.email, r.risk, r.score);
}

batch = eva.verify_batch([
    "user@gmail.com", "info@example.com", "nobody@mailinator.com",
])

for r in batch.data.results:
    print(r.email, r.risk, r.score)

{
  "data": {
    "total": 3,
    "results": [
      { "email": "user@gmail.com", "score": 94, "risk": "safe", "smtp_check": "deliverable", … },
      { "email": "info@example.com", "score": 55, "risk": "risky", "is_role_account": true, … },
      { "email": "nobody@mailinator.com", "score": 45, "risk": "risky", "is_disposable": true, … }
    ]
  }
}

Bulk jobs

Upload a file, let the job run in the background, then collect the results by polling or through a webhook. Available on Starter and above; per-file caps are in the plan table.

File format

• .csv or .xlsx, up to 11 MB, one address per row.
• If the header row has a column named email, email_address, or e-mail, that column is used. Otherwise the first column is.
• Rows that do not contain a valid address are skipped, and duplicates are removed.

Upload, wait, download

# 1. upload (multipart). webhook_url is optional.
curl -X POST https://verifications.email/api/v1/verify/async/upload \
  -H "X-API-Key: $EVA_API_KEY" \
  -F "file=@subscribers.csv" \
  -F "webhook_url=https://example.com/hooks/eva"

# 2. poll until status is "completed"
curl https://verifications.email/api/v1/verify/async/JOB_ID \
  -H "X-API-Key: $EVA_API_KEY"

# 3. results as JSON, or as CSV with ?format=csv (add &risk=invalid to filter)
curl "https://verifications.email/api/v1/verify/async/JOB_ID/result?format=csv" \
  -H "X-API-Key: $EVA_API_KEY" -o results.csv

import { readFile } from 'node:fs/promises';

const file = await readFile('subscribers.csv');
const { data: job } = await eva.uploadBulk(file, {
  filename: 'subscribers.csv',
  webhookUrl: 'https://example.com/hooks/eva',   // optional
});

const { data: done } = await eva.waitForBulkJob(job.id, {
  onProgress: j => console.log(`${j.completed_count}/${j.total_count}`),
});

const { data: results } = await eva.getBulkJobResults(done.id);
const invalid = results.filter(r => r.risk === 'invalid');

with open("subscribers.csv", "rb") as f:
    job = eva.upload_bulk(f, filename="subscribers.csv",
                          webhook_url="https://example.com/hooks/eva")  # webhook_url optional

done = eva.wait_for_bulk_job(job.data.id)          # polls until completed or failed

results = eva.get_bulk_job_results(done.data.id)
invalid = [r for r in results.data if r.risk == "invalid"]

{
  "data": {
    "id": "5c1e0a7e-3b2f-4d61-9a0c-8f2d1b4e6a90",
    "status": "processing",
    "total_count": 12480,
    "completed_count": 9310,
    "webhook_url": "https://example.com/hooks/eva",
    "created_at": "2026-09-05T08:12:44Z",
    "started_at": "2026-09-05T08:12:46Z",
    "completed_at": null,
    "rerun_available_at": null
  }
}

Job lifecycle

POST …/async/{id}/pause, …/resume, and …/cancel control a running job; a control that does not fit the job's current state returns 409 INVALID_STATE. Up to three jobs run at once per account. GET /api/v1/verify/async lists your jobs.

Results

GET /api/v1/verify/async/{id}/result returns an array with one row per address: the verdict fields (score, risk, reason, smtp_check), the evidence flags (syntax_valid, mx_found, is_disposable, is_role_account, is_catch_all, is_free_provider, is_b2b, spam_trap_risk, is_full_inbox, is_locked, has_sub_addressing, suggested_correction, smtp_provider), and the domain summary (deliverability_grade, deliverability_score, domain_age_days, domain_age_risk). Add ?format=csv for a download and ?risk=safe|risky|catchall|invalid|unknown to filter either format.

Jobs from a free-only account (Free plan, no credits) show a summary and up to 10 sample rows until the account has any plan or credit pack. GET /api/v1/verify/async/{id}/summary returns job_id, total, the verdict counts (safe, risky, catchall, invalid, unknown), free_sample and results_locked, plus up to 10 result rows in sample while results are locked. While locked, /result (JSON and CSV) and rerun-unknowns answer 403 RESULTS_LOCKED. Job objects carry the same two flags. Buying a plan or pack unlocks the full results, including for earlier uploads.

Re-run unknowns

Unknowns are not billed and are worth a second pass once the mail servers that greylisted you have settled. POST /api/v1/verify/async/{id}/rerun-unknowns creates a follow-up job containing only that job's unknown addresses and returns it with 201 Created; poll the new job id and read its results the same way. The original job and its results are unchanged. A re-run becomes available 30 minutes after the job completes (rerun_available_at on the job); before that the API returns 429 RERUN_COOLDOWN with a Retry-After header.

Domain deliverability

GET /api/v1/domain/{domain}/deliverability grades a domain on its own: SPF, DKIM, and DMARC posture, presence on 10 blacklist zones, MX presence, and reputation. Useful for scoring a signup's company domain or auditing your own.

curl https://verifications.email/api/v1/domain/example.com/deliverability \
  -H "X-API-Key: $EVA_API_KEY"

const { data } = await eva.getDomainDeliverability('example.com');
console.log(data.grade, data.score, data.blacklist.listed);

report = eva.get_domain_deliverability("example.com")
print(report.data.grade, report.data.score, report.data.blacklist.listed)

{
  "data": {
    "domain": "example.com",
    "score": 88,
    "grade": "B",
    "authentication": {
      "spf": { "found": true, "policy": "strict" },
      "dkim": { "found": true },
      "dmarc": { "found": true, "policy": "quarantine" }
    },
    "blacklist": { "listed": false, "listed_count": 0, "high_confidence_count": 0, "total_checks": 10, "evaluated_checks": 10 },
    "has_mx": true,
    "reputation_score": 81,
    "checked_at": "2026-09-05T08:20:01Z"
  }
}

Webhooks

When a bulk job completes, EVA can call a URL of yours instead of you polling. Set webhook_url on the upload for a single job, or add endpoints under Webhooks in the dashboard to receive every job's event. The dashboard also shows a delivery log with each attempt's status code.

Event: bulk_job.completed

{
  "event": "bulk_job.completed",
  "job_id": "5c1e0a7e-3b2f-4d61-9a0c-8f2d1b4e6a90",
  "status": "completed",
  "total_count": 12480,
  "completed_count": 12480,
  "summary": { "safe": 10112, "risky": 1089, "catchall": 314, "invalid": 871, "unknown": 94 },
  "result_url": "https://verifications.email/api/v1/verify/async/5c1e0a7e-3b2f-4d61-9a0c-8f2d1b4e6a90/result",
  "timestamp": "2026-09-05T08:41:07Z"
}

Verify the signature

Every delivery carries X-EVA-Signature: the hex HMAC-SHA256 of the raw request body, keyed with your signing secret from the dashboard's Webhooks tab. Compare it in constant time before trusting the payload. The libraries do this for you.

POST /hooks/eva HTTP/1.1
Content-Type: application/json
User-Agent: EVA-Webhook/1.0
X-EVA-Signature: 9f2c…e41a   # hex HMAC-SHA256(raw body, signing secret)

import { parseWebhookEvent } from '@verifications-email/sdk';

// Express: mount with express.raw({ type: 'application/json' }) so the body is untouched
app.post('/hooks/eva', async (req, res) => {
  const event = await parseWebhookEvent({
    payload: req.body,                          // raw Buffer or string
    signature: req.get('X-EVA-Signature'),
    secret: process.env.EVA_WEBHOOK_SECRET,
  });                                           // throws if the signature is wrong
  console.log(event.job_id, event.summary);
  res.sendStatus(200);
});

from eva_email import parse_webhook_event

# Flask
@app.post("/hooks/eva")
def eva_hook():
    event = parse_webhook_event(
        request.get_data(),                     # raw bytes, not parsed JSON
        request.headers["X-EVA-Signature"],
        os.environ["EVA_WEBHOOK_SECRET"],
    )                                           # raises if the signature is wrong
    print(event.job_id, event.summary)
    return "", 200

Delivery rules

• The URL must be public HTTPS. Private and internal addresses are rejected at registration.
• Respond with any 2xx within 10 seconds. Do the heavy work after responding.
• Three attempts per event: immediately, then after 1 second, then after 5 seconds. After that the delivery is marked failed in the dashboard log and the results stay available at result_url.
• Handle duplicates: use job_id as an idempotency key.

Libraries

Official, MIT-licensed clients that wrap everything on this page, retry rate-limited requests with backoff, and verify webhook signatures.

npm install @verifications-email/sdk

pip install verifications-email

MCP server

AI agents can use verifications.email through a remote Model Context Protocol server. There is nothing to install: point your client at https://mcp.verifications.email/mcp and either sign in when the client asks, or pass your API key as a bearer token. Every tool call bills exactly like the REST API, and unknown results stay free.

Claude Code

claude mcp add --transport http email-verification https://mcp.verifications.email/mcp
# then type /mcp in a session to sign in. With an API key instead:
claude mcp add --transport http email-verification https://mcp.verifications.email/mcp \
  --header "Authorization: Bearer eva_your_key"

Cursor, Windsurf, VS Code

{
  "mcpServers": {
    "email-verification": {
      "url": "https://mcp.verifications.email/mcp",
      "headers": { "Authorization": "Bearer eva_your_key" }
    }
  }
}

n8n

Add an MCP Client Tool node, choose the HTTP Streamable transport, set the endpoint to https://mcp.verifications.email/mcp, and create a Bearer credential holding your API key. The node lists the tools below and any AI Agent node can call them.

Connect by signing in (no API key)

Clients that speak OAuth discover the sign-in flow from the server itself. Paste the URL, approve the connection in your browser, and the client keeps its own token. Connections appear under Connected apps on the API keys tab of the dashboard, where you can disconnect any of them. Every plan can connect, including Free.

• claude.ai, Claude Desktop, Cowork: Customize, Connectors, Add custom connector, paste https://mcp.verifications.email/mcp, leave the client id blank, then Connect.
• ChatGPT: Settings, Apps and connectors, enable developer mode, create a connector with the same URL and OAuth authentication.
• Claude Code: claude mcp add --transport http email-verification https://mcp.verifications.email/mcp, then /mcp inside a session to sign in.
• Cursor, Windsurf, VS Code: add the server with only its url; the editor registers itself and opens the sign-in page.

Discovery documents live at https://mcp.verifications.email/.well-known/oauth-protected-resource/mcp and https://verifications.email/.well-known/oauth-authorization-server. Tokens are scoped to this server only; they never work against the REST API.

API key instead of sign-in

Automation that cannot open a browser (n8n, servers, CI) keeps using Authorization: Bearer eva_your_key, exactly as in the examples above.

Tools

Quota and rate-limit problems come back as tool errors the agent can read, using the same codes as the REST API (QUOTA_EXCEEDED, RATE_LIMITED). Usage appears in the dashboard under the source mcp. If a call was paid with credits, credits for unknown results are returned.