API documentation

Verify email addresses from your own code. Every check runs through 5 verification layers and returns one clear verdict. Pay only for what you use.

Base URL

https://mailcertify.online/api/v1

Authentication

Send your API key in the Authorization header as a Bearer token. Create keys in your dashboard.

Authorization: Bearer sk_live_...

Endpoints

POST/verify

Verify one email address. Costs 1 credit.

Request

{
  "email": "jane@example.com"
}

Response

{
  "email": "jane@example.com",
  "status": "deliverable",
  "sub_status": null,
  "score": 94,
  "free_email": false,
  "role": false,
  "disposable": false,
  "accept_all": false,
  "mx_found": true,
  "smtp_check": true,
  "checked_at": "2026-08-06T12:34:56Z",
  "credits_remaining": 4821
}

POST/bulk

Start a bulk verification job from a JSON array of emails.

Request

{
  "name": "Q3 list",
  "emails": ["a@x.com", "b@y.com"]
}

Response

{
  "id": "job_...",
  "status": "queued",
  "count_submitted": 5000,
  "count_unique": 4870,
  "count_duplicates": 130,
  "credits_held": 4870
}

Returns 202 Accepted. Poll GET /bulk/{id} for progress, then call GET /bulk/{id}/results to get the structured results and the full CSV in one response.

GET/bulk/{id}

Check a bulk job's status and progress.

Response

{
  "id": "job_...",
  "status": "processing",
  "progress": 42,
  "count_submitted": 5000,
  "count_unique": 4870,
  "count_billable": 4870,
  "credits_charged": 0
}

GET/bulk/{id}/results

Get results for a completed bulk job. Returns structured results and the full CSV in a single response.

Response

{
  "total": 4870,
  "limit": 1000,
  "offset": 0,
  "has_more": false,
  "csv": "email,status,sub_status,...\na@x.com,deliverable,,\nb@y.com,undeliverable,invalid_address,...",
  "results": [
    {
      "email": "a@x.com",
      "status": "deliverable",
      "sub_status": null,
      "score": null,
      "free_email": false,
      "role": false,
      "disposable": false,
      "accept_all": false,
      "mx_found": true,
      "smtp_check": true
    }
  ]
}

Use ?limit and ?offset to paginate the results array. The csv field always contains the complete file regardless of pagination. Append ?format=csv to download the raw CSV file instead.

GET/credits

Get your current credit balance.

Response

{
  "credits": 4821
}

Status values

Every verification returns one of these buckets:

Deliverable — Safe to send. The mailbox is real and accepting mail.
Undeliverable — Don't send. The address is invalid, dead, or a trap.
Risky — Send with caution. Includes catch-all, role, disposable, or full mailboxes.
Unknown — We couldn't get a definite answer this time.
Unverifiable — The address is malformed and was never sent for verification.

Errors

Errors use this shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You're out of credits. Add credits to keep verifying."
  }
}

invalid_request400

invalid_email400

invalid_api_key401

insufficient_credits402

rate_limited429

not_found404

verification_unavailable503

internal_error500

Rate limits

Single-verification endpoints are limited to 60 requests per minute per API key. Bulk endpoints are limited by credit balance instead.

Credit packs

One verification costs one credit. Buy credits in packs:

10,000 credits$79

25,000 credits$99

50,000 credits$129

100,000 credits$189