Developer access

MailCheckr API

Submit an email address and receive its result in the same response. Receive signed events when a verification finishes.

Base URL

https://mailcheckr.app/api/v1

Manage API keys

Authentication

Use a bearer API key

Create a key in the dashboard and send it in every request. API key owners must have a verified email address.

Authorization: Bearer mc_live_your_api_key

Keep keys server-side. Create a separate key for each environment and revoke a key immediately if it is exposed.

POST /verifications

Create a verification

A new request reserves one credit and waits for the SMTP worker to complete the verification. Supply an Idempotency-Key so retries never create duplicate work or reserve another credit.

curl -X POST https://mailcheckr.app/api/v1/verifications \
  -H "Authorization: Bearer mc_live_your_api_key" \
  -H "Idempotency-Key: verify-person-123" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'

200 OK

{
  "data": {
    "id": "2da6b742-3a56-4ea0-a5a5-0a2bbac752dc",
    "email": "person@example.com",
    "state": "completed",
    "status": "deliverable",
    "reason": "smtp_accepted",
    "checks": [
      {
        "check": "smtp",
        "status": "deliverable",
        "reason": "smtp_accepted",
        "metadata": []
      }
    ],
    "attempts": 1,
    "created_at": "2026-09-22T12:00:00+00:00",
    "completed_at": "2026-09-22T12:00:02+00:00"
  }
}

Most requests return the completed verification with 200 OK. If the worker does not finish within the wait window, the response is 202 Accepted; poll the returned ID until it is complete. Reusing an idempotency key for a different email returns 409 Conflict.

GET /verifications/{id}

Retrieve a verification

The creation response includes a completed result when the SMTP worker responds in time. Otherwise, poll this endpoint with the returned ID until the verification is complete. A key can retrieve only verifications it created.

curl https://mailcheckr.app/api/v1/verifications/2da6b742-3a56-4ea0-a5a5-0a2bbac752dc \
  -H "Authorization: Bearer mc_live_your_api_key"

States

queued, processing, retry_scheduled, completed, failed

Completed statuses

deliverable, undeliverable, risky, unknown

Error handling

Response codes

Status	Meaning
200	A terminal verification. An idempotent replay returns this status when its original verification is terminal.
202	The SMTP worker has not completed within the response wait window. Poll the returned verification ID.
401	The bearer key is missing, invalid, or expired.
402	No credit is available. The response code is `insufficient_credits`.
403	The API key owner has not verified their email address.
409	An idempotency key was reused with a different email.
422	The email or required idempotency key is invalid.

Webhooks

Receive completed events

Configure an HTTPS endpoint in the dashboard and save its one-time signing secret. MailCheckr currently sends these event types:

verification.completedbulk_verification.completed

{
  "id": "event_123",
  "type": "verification.completed",
  "created_at": "2026-09-22T12:00:00+00:00",
  "data": { "...": "event data" }
}

Verify every delivery

Compute an HMAC SHA-256 using your signing secret over the exact raw body prefixed with the timestamp and a period.

signed_payload = X-MailCheckr-Timestamp + "." + raw_request_body
expected = HMAC_SHA256(signing_secret, signed_payload)
X-MailCheckr-Signature = "v1=" + expected

Also reject old timestamps to reduce replay risk. Successful responses are any 2xx status. Failed deliveries are attempted up to six times with increasing delays over roughly nine hours.