API Documentation

Base URL: https://mailprobe.dev

All API requests require authentication via your API key in the Authorization header.

Developer Resources

OpenAPI 3.0 specification — generate a client in any language, import it into Swagger, Insomnia or Bruno, or hand it to an agent. It documents every field, enum and error of the two endpoints below.

Postman collection — import it, paste your API key into the api_key variable, and verify an address in under a minute.

Authentication

Include your API key in every request:

Authorization: Bearer mp_live_your_api_key_here

Get your API key from the dashboard after signing up.

Verify Emails

POST /api/v1/verify

Send 1 to 500 emails per request. Each email costs 1 credit.

Example: Single email

curl -X POST \
  -H "Authorization: Bearer mp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"emails": ["zzq-no-such-mailbox-4821@gmail.com"]}' \
  "https://mailprobe.dev/api/v1/verify"

Example: Multiple emails

curl -X POST \
  -H "Authorization: Bearer mp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"emails": ["alex@acme.co", "zzq-no-such-mailbox-4821@gmail.com"]}' \
  "https://mailprobe.dev/api/v1/verify"

Response

Always returns an array, even for a single email. This is a real response, reproducible with the free tester on the homepage.

[
  {
    "email": "zzq-no-such-mailbox-4821@gmail.com",
    "result": "undeliverable",
    "status": "invalid",
    "score": 0,
    "catch_all": false,
    "reason": null,
    "retry_after": null,
    "smtp_code": 550,
    "syntax": true,
    "mx_found": true,
    "smtp_check": true,
    "disposable": false,
    "role_based": false,
    "free_provider": true,
    "did_you_mean": null,
    "mx_records": [
      "gmail-smtp-in.l.google.com",
      "alt1.gmail-smtp-in.l.google.com",
      "alt2.gmail-smtp-in.l.google.com",
      "alt3.gmail-smtp-in.l.google.com",
      "alt4.gmail-smtp-in.l.google.com"
    ]
  }
]

result is the raw SMTP verdict; status is the actionable rollup you filter on; score is a 0–100 confidence value. reason explains a non-deliverable / unknown verdict (e.g. no_mx, accept_all, greylisting, provider_blocks_probe, mx_unresolved), and is null otherwise. retry_after is the suggested wait in seconds when a mailbox is temporarily deferred (greylisting), else null. catch_all is true when the domain accepts every address. smtp_check reports that an SMTP conversation actually took place, not that the mailbox was accepted — it is true above even though the server answered 550; the verdict itself is in result and status. did_you_mean suggests a likely typo fix (e.g. gmial.com → gmail.com) or null. Entries that aren't strings are returned as {"email": <value>, "error": "invalid"} with no result field.

Result Values

The raw technical verdict from the verification pipeline.

Value	Description
`deliverable`	SMTP confirmed the mailbox exists
`undeliverable`	SMTP rejected the address
`catch-all`	Server accepts all addresses (can't confirm individually)
`unknown`	Could not determine (timeout, connection refused, greylisting)

Status Values

The actionable classification most integrations filter on.

Value	Description
`valid`	Deliverable and clean — safe to send
`invalid`	Bad syntax, no MX, or the mailbox rejects — do not send
`risky`	Accepted but uncertain: catch-all, role-based, disposable, or a provider that blocks probing (Microsoft consumer domains — `outlook.com`, `hotmail.com`, `live.com`, `msn.com`)
`unknown`	Temporarily undeterminable (greylisting, timeout, connection refused, unresolved MX)

Score

A deterministic 0–100 confidence value derived only from the signals already in the response — no black-box model, no stored data. Rough bands: 90+ deliverable and clean; ~65 probe-blocking provider (well-formed address on a live Microsoft-consumer MX); ~55 catch-all; ~50 greylisted; ≤15 disposable; 0 invalid. Role-based and suspected-typo addresses are penalised. Threshold it to fit your risk tolerance per campaign.

Check Credit Balance

GET /api/v1/credits

Example

curl -H "Authorization: Bearer mp_live_abc123..." \
  "https://mailprobe.dev/api/v1/credits"

Response

{ "credits": 847 }

Credits are valid for 12 months from your most recent purchase; an expired balance returns 0.

Error Codes

HTTP	Code	Description
400	`INVALID_INPUT`	Missing or empty `emails` array
400	`TOO_MANY`	Bulk request exceeds 500 emails
401	`UNAUTHORIZED`	Missing or invalid API key
402	`NO_CREDITS`	No credits remaining, buy more
413	—	JSON body above 50 kB — split the batch (no `code` field on this one)
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Rate Limits

API requests are limited by your credit balance (1 credit per verification) and capped at 60 requests per minute per API key. Exceeding the limit returns 429 RATE_LIMITED. Bulk requests accept up to 500 emails each.

Freshness

Every verification is performed in real time, no caching. Each request produces a fresh result and costs 1 credit.