Email Verification API

The Mailsurity API tells you, in a single request, whether an email address is disposable — a throwaway, burner, or temporary inbox — or a legitimate address worth keeping in your funnel. It is a JSON-over-HTTPS API: one endpoint, bearer-token auth, no SDK required.

Every verdict flows through a layered cascade — curated allow/deny lists, a global disposable-domains list, a 30-day verdict cache, and finally live heuristics (MX records, local-part entropy, brand similarity, mail-server reputation) with an AI classifier for borderline cases. The response tells you which layer produced the answer via the source field.

All requests go to a single HTTPS base. There is no versioned path prefix.

HTTPS is required; plain-HTTP requests are rejected. All request and response bodies are application/json encoded as UTF-8.

Authenticate every request with your team's API key as a bearer token in the Authorization header. Keys are issued per team and can be revoked at any time from the dashboard.

• Treat your key like a password — keep it server-side, in an environment variable, never in client-side code or a public repo.
• Requests with a missing or malformed header get 401 Unauthorized; an unrecognized key also returns 401.
• Rotate a key by issuing a new one and revoking the old one from API Keys. Revocation is immediate.

Send a POST with one JSON field — email — and read isDisposable off the response. Pick your language:

curl -X POST https://mailsurity.com/api/check-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@mailinator.com"}'

A throwaway address comes back like this:

{
  "email": "user@mailinator.com",
  "isDisposable": true,
  "source": "list"
}

Evaluates a single email address and returns a disposable verdict. This is the core, metered endpoint — each successful call costs one credit (see Credits & limits).

Headers

Body parameters

A minimal request body:

{ "email": "user@mailinator.com" }

A 200 OK returns a JSON verdict. Which fields are present depends on how the verdict was resolved — email, isDisposable, and source are always there; the rest are added only when a live detection runs.

The signals object

The source field reports which layer of the detection cascade produced the verdict, in precedence order (earlier layers win):

Disposable — resolved live (full payload)

{
  "email": "user@mailinator.com",
  "isDisposable": true,
  "classification": "disposable",
  "confidence": 0.94,
  "reason": "high-entropy local part; MX cluster flagged disposable",
  "source": "heuristic",
  "signals": {
    "mxValid": true,
    "entropy": 3.7,
    "levenshteinMatch": "mailinator",
    "mxClusterSuspicious": true
  }
}

Legitimate — fast legit-list hit

{
  "email": "jane@gmail.com",
  "isDisposable": false,
  "source": "legit-list"
}

Team rule match

When a team allow/deny rule matches, it overrides every other layer:

{
  "email": "partner@trusted-partner.com",
  "isDisposable": false,
  "source": "allowlist",
  "matchedRule": { "kind": "domain", "value": "trusted-partner.com" }
}

Errors use standard HTTP status codes and return a JSON body of the shape { "error": "message" }.

• One credit per successful call. Every verdict — list hit, cache hit, or full live detection — costs exactly one credit. Errored requests (4xx/5xx) are not charged, except that a 402 is itself the "out of credits" signal.
• Free tier: 500 credits granted once at signup, no card required.
• Paid plans grant a monthly credit allotment that resets each billing cycle and does not roll over. See Pricing.
• Need to check thousands of addresses at once? Use the Bulk Check CSV uploader instead of looping the API — it's billed per unique domain.

• Validate syntax first. Reject obviously malformed input client-side so you don't spend a credit (and a round-trip) on a 400.
• Branch on isDisposable, not source. The boolean is the contract; source and signals are for logging and tuning your own thresholds.
• Treat null gracefully. A null verdict means "unknown" — decide whether to allow, soft-flag, or challenge rather than hard-blocking.
• Handle 402 and retry 5xx. Back off and retry on 500; surface 402 to whoever manages billing.
• Cache on your side if you re-check the same domains often — verdicts are stable, and it conserves credits.

Questions, edge cases, or a domain you think we're scoring wrong? Reach us through the contact page, and check the API status page for live health.