MMailChecked

API reference

Simple REST. Bearer-token auth. JSON in, JSON out. Stable v1.

Authentication

All endpoints accept an API key via the Authorization header. Generate keys in your dashboard — keys are shown only once and stored as SHA-256 hashes server-side.

Authorization: Bearer mck_live_abc123…

Base URL

https://app.mailchecked.com/v1

Rate limits

Single-validation endpoint is rate-limited per API key. Bulk endpoints accept up to 100,000 emails per job. Limits scale with your plan and historical sender reputation.

POST /v1/validate

Validate a single email synchronously. Costs 1 credit on a definitive verdict; cache hits and Unknown results are free.

Request

POST /v1/validate 
curl -X POST https://app.mailchecked.com/v1/validate \
  -H "Authorization: Bearer mck_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response

{
  "email": "user@example.com",
  "verdict": "valid",
  "score": 0.98,
  "checks": {
    "syntax": true,
    "mx": true,
    "smtp": "accepted",
    "catch_all": false,
    "disposable": false,
    "role": false,
    "free_provider": false
  },
  "provider": "google",
  "credits_charged": 1,
  "cached": false,
  "request_id": "req_01HXY..."
}

Verdicts

  • valid — RCPT-confirmed deliverable.
  • invalid — Hard-fails RCPT, no MX, bad syntax, or known-dead.
  • catch_all — Domain accepts every recipient. Send at your own risk.
  • risky — Disposable, role-based, or otherwise discouraged.
  • unknown — Greylisted, blocked, or temporary failure. Free of charge.

POST /v1/bulk

Submit a list of emails for asynchronous validation. Returns a job ID you can poll.

POST /v1/bulk
curl -X POST https://app.mailchecked.com/v1/bulk \
  -H "Authorization: Bearer mck_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["a@example.com", "b@example.com"],
    "name": "october-leads"
  }'
{ "job_id": "job_01HXY...", "status": "queued", "count": 2 }

POST /v1/bulk/csv

Upload a CSV (one email per line, or a header row with an email column). Max 100,000 rows.

curl -X POST https://app.mailchecked.com/v1/bulk/csv \
  -H "Authorization: Bearer mck_live_abc123" \
  -F "file=@leads.csv" \
  -F "name=october-leads"

GET /v1/bulk/{job_id}

{
  "job_id": "job_01HXY...",
  "status": "completed",
  "name": "october-leads",
  "progress": { "done": 2, "total": 2 },
  "summary": {
    "valid": 1, "invalid": 1, "catch_all": 0,
    "risky": 0, "unknown": 0
  },
  "credits_charged": 2,
  "result_url": "https://app.mailchecked.com/v1/bulk/job_01HXY.../results.csv"
}

GET /v1/account

Returns your current credit balance and plan.

{
  "credits": 9842,
  "plan": "payg",
  "email": "you@yourcompany.com"
}

Errors

All errors return JSON with error.code and error.message. Common codes:

  • invalid_request — 400, malformed body or missing field.
  • unauthorized — 401, missing or invalid API key.
  • insufficient_credits — 402, top up to continue.
  • rate_limited — 429, slow down. Retry-After header included.
  • server_error — 5xx, transient. Safe to retry with exponential backoff.

Webhooks

Configure a webhook in your dashboard to receive bulk.completed events. Payloads are signed with HMAC-SHA256 in the MailChecked-Signature header.

SDKs

Coming soon. The API is small enough that a direct fetch/requests call usually beats wrapping it.