All public API examples use:

Send your MailBeacon API key in the Authorization header.

These reserved addresses are for testing your integration. They return predictable mock responses and do not cost any tokens.

Use GET /verify for quick checks from scripts and POST /verify when sending JSON from an application.

curl -H "Authorization: Bearer <your-api-key>" \
  "https://api.mailbeacon.co/verify?email=user@example.com"

curl -X POST https://api.mailbeacon.co/verify \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Request parameters

Envelope status is success and data.status is valid. data.reason is null.

{
  "status": "success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "reason": null,
    "is_free": false,
    "suggested_email": "",
    "address_info": {
      "mx_record": "mx.example.com",
      "smtp_provider": "google",
      "domain": "example.com"
    },
    "verified_on": "2026-05-24T19:00:00.000Z"
  }
}

Envelope status is still success — the request succeeded — but data.status is invalid or unknown. data.reason explains why.

{
  "status": "success",
  "data": {
    "email": "user@example.com",
    "status": "invalid",
    "reason": "mailbox_not_found",
    "is_free": false,
    "suggested_email": "",
    "address_info": {
      "mx_record": "mx.example.com",
      "smtp_provider": "google",
      "domain": "example.com"
    },
    "verified_on": "2026-05-24T19:00:00.000Z"
  }
}

Reason codes

Bulk validation is asynchronous. Upload one file as multipart form data, then poll the returned job ID until the result is ready. Creating a job parses the upload and reserves credits, then returns 202 Accepted with the job usually in queued status. It does not wait for validation workers to finish.

curl -X POST https://api.mailbeacon.co/bulk/jobs \
  -H "Authorization: Bearer <your-api-key>" \
  -F "file=@subscribers.csv"

{
  "status": "success",
  "data": {
    "id": "<job-id>",
    "status": "queued",
    "filename": "subscribers.csv",
    "rows": {
      "total": 1000,
      "unique": 950,
      "processed": 0,
      "valid": 0,
      "invalid": 0,
      "unknown": 0,
      "failed": 0,
      "deduplicated": 50
    },
    "credits": {
      "required": 950,
      "available": 5000
    },
    "created_at": "2026-07-09T23:00:00.000Z",
    "completed_at": null,
    "expires_at": null
  }
}

Upload rules

• • Send exactly one file field with a .csv, .txt, .xls, or .xlsx file.
• • A job may contain up to 100,000 recognized email rows. The documented upload-size limit also applies; an oversized file or row count is rejected before validation.
• • TXT files contain one email per non-empty line. CSV, XLS, and XLSX files use a case-insensitive email column header, with a single-column file accepted as a fallback. Ambiguous multi-column files are rejected with a mapping error.
• • Input order and duplicate rows are preserved in the result. Duplicate normalized addresses are checked once, reuse the same result, and consume only one credit.

Send the same API key on every request. Poll the status endpoint until the job reaches a terminal state; a successful result download returns text/csv.

The result contains email, status, reason, is_free, suggested_email, domain, mx_record, smtp_provider, and verified_on columns.

curl -H "Authorization: Bearer <your-api-key>" \
  "https://api.mailbeacon.co/bulk/jobs"

curl -H "Authorization: Bearer <your-api-key>" \
  "https://api.mailbeacon.co/bulk/jobs/<job-id>"

curl -X DELETE \
  -H "Authorization: Bearer <your-api-key>" \
  "https://api.mailbeacon.co/bulk/jobs/<job-id>"

curl -L \
  -H "Authorization: Bearer <your-api-key>" \
  "https://api.mailbeacon.co/bulk/jobs/<job-id>/result" \
  --output validated-emails.csv

Credits and retention

After analysis, MailBeacon atomically reserves enough credits for every unique normalized address before the job enters the queue. If the full amount is unavailable, validation does not start and no partial job is run. Credits are refunded for blocked, test, or unprocessed addresses under the normal charging rules, including work left unprocessed after cancellation or failure.

The original upload is deleted after processing. Completed result CSVs remain available for seven days, after which the job becomes expired and the result can no longer be downloaded.