Email validation API

Overview

Every route lives under https://api.mailchecker.dev/v1, answers JSON in UTF-8 (except result downloads, which are CSV) and needs an API key. Create and revoke keys in the dashboard, under API keys; the full key is shown only once.

The OpenAPI 3.1 spec is at https://api.mailchecker.dev/v1/openapi.json.

Authentication

Send the key (mc_live_…) in the Authorization: Bearer header or, for ZeroBounce compatibility, in the api_key query parameter. Prefer the header: URLs tend to end up in logs.

# Header (recommended)
curl "https://api.mailchecker.dev/v1/credits" \
  -H "Authorization: Bearer mc_live_…"

# Or in the query string, as with ZeroBounce
curl "https://api.mailchecker.dev/v1/credits?api_key=mc_live_…"

Endpoints

Checks one address and returns a Verdict. Parameter: email (required).

curl "https://api.mailchecker.dev/v1/validate?email=emma.jones@gmail.com" \
  -H "Authorization: Bearer mc_live_…"

{
  "address": "emma.jones@gmail.com",
  "status": "valid",
  "sub_status": "",
  "account": "emma.jones",
  "domain": "gmail.com",
  "did_you_mean": null,
  "free_email": true,
  "role_based": false,
  "disposable": false,
  "mx_found": true,
  "mx_record": "gmail-smtp-in.l.google.com",
  "smtp_provider": "google",
  "domain_age_days": 11318,
  "processed_at": "2026-11-07T12:34:56Z",
  "domain_score": 100,
  "domain_reasons": ["dmarc_none", "free_email"]
}

Body {"emails": [...]} with up to 100 addresses. Returns one Verdict per address and the batch’s total cost; repeats within the batch aren’t charged.

curl -X POST "https://api.mailchecker.dev/v1/validate/batch" \
  -H "Authorization: Bearer mc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["emma@company.com", "john@gmial.com"]}'

{
  "results": [ /* one Verdict per address */ ],
  "cost": 2
}

Multipart with file (CSV or XLSX, up to 1 million rows), column (optional: the email column) and name. Answers 201 with the list in the queued state.

curl -X POST "https://api.mailchecker.dev/v1/files" \
  -H "Authorization: Bearer mc_live_…" \
  -F "file=@customers.csv" -F "column=2" -F "name=November customers"

The list’s state: uploaded, queued, running, done, failed or cancelled, with totals by status. Poll it until done.

{
  "id": "0193f1c2-…",
  "name": "November customers",
  "original_filename": "customers.csv",
  "state": "running",
  "total": 12480, "unique_count": 12011, "duplicates": 469,
  "processed": 8300,
  "counts": { "valid": 6904, "invalid": 811, "catch-all": 402, "unknown": 183 },
  "cost": 8117,
  "error": null,
  "created_at": "2026-11-07T12:00:00Z", "started_at": "2026-11-07T12:00:02Z", "finished_at": null
}

The results as CSV. filter=all (default) returns everything, valid only the valid addresses, no_invalid everything except the invalid ones.

The team’s balance: {"balance": 1840}.

Daily usage by status, with YYYY-MM-DD dates: {"days": [{"day", "status", "count", "cost"}]}.

The result (Verdict)

Every checked address becomes an object with these fields:

Domain reputation reasons

Each reason takes points off 100; the ones marked "no penalty" are informational. Free email domains (Gmail, Outlook…) only lose points for blocklists.

Statuses and sub-statuses

The same vocabulary as ZeroBounce.

What each sub-status means

Errors

Every error has the same shape: a stable code in error, a human-readable message in message and, for validation errors, the offending fields in fields.

{
  "error": "validation",
  "message": "…",
  "fields": { "email": ["…"] }
}

Limits

• Requests: a per-key token bucket; the default is 10 requests per second. Need more? Get in touch.
• Synchronous batch: up to 100 addresses per POST /v1/validate/batch.
• Files: CSV or XLSX with up to 1 million rows.
• Retention: results are available for 30 days and then deleted (see our Privacy Policy).

Billing

Credits are debited as each result is stored: 1 credit per address, catch-all included. unknown costs 0, and so do repeated addresses within the same list or batch. Check your balance with GET /v1/credits and see pricing.

Migrating from ZeroBounce

We designed the API so switching is quick:

• The same statuses and sub-statuses, with the same names.
• The same names for the main result fields (address, status, sub_status, account, domain, did_you_mean, free_email, mx_found, mx_record, smtp_provider, domain_age_days, processed_at).
• The key is accepted in ?api_key=.
• The same billing rules: unknown and duplicates are free.

# ZeroBounce
GET https://api.zerobounce.net/v2/validate?api_key=YOUR_KEY&email=emma@company.com

# mailchecker: swap the base URL and the key
GET https://api.mailchecker.dev/v1/validate?api_key=mc_live_…&email=emma@company.com

See also the full comparison.