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.

Always call the apex host shown above, not www.mailsurity.com. The www host issues a 308 redirect to the apex, and curl (with -L) and many HTTP clients drop the Authorization header on that cross-host redirect, which surfaces as a confusing Invalid authorization header error.

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:

// npm i mailsurity   (server-side only, keep your key secret)
import { Mailsurity } from "mailsurity";

const ms = new Mailsurity({ apiKey: process.env.MAILSURITY_API_KEY! });

// Convenience boolean, fail-open: a transient outage never blocks a signup
if (await ms.isDisposable("user@mailinator.com")) {
  // reject the signup
}

// ...or the full result
const verdict = await ms.checkEmail("user@mailinator.com");
console.log(verdict.isDisposable); // true

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" }.

• Every verdict (list hit, cache hit, or full live detection) costs exactly one credit. Errored requests (4xx/5xx) aren't charged, except that a 402 is itself the "out of credits" signal.
• New accounts start with 500 free credits, no card required.
• Paid plans grant a monthly credit allotment that resets each billing cycle and doesn't roll over. See Pricing.
• Checking thousands of addresses at once? Use the Bulk Check CSV uploader instead of looping the API. It's billed per unique domain.

The recommended integration path going forward. Instead of a boolean plus classification metadata, /api/assess returns a 0-100 risk score, a paired confidence score, and a resolved ALLOW / VERIFY / BLOCK decision, so you branch directly on the decision the engine already made instead of writing your own if/else around isDisposable.

Request

Same one-field body as /api/check-email:

{ "email": "abc@temporary-domain.example" }

Response

{
  "check_id": "0f3c1e6a-1234-4a11-9c2e-8b6f2a5d9e10",
  "email": "abc@temporary-domain.example",
  "risk_score": 93,
  "confidence": 88,
  "decision": "BLOCK",
  "signals": {
    "disposable": true,
    "mx_valid": true,
    "domain_age_days": 4,
    "role_account": false,
    "free_provider": false,
    "network": null
  },
  "reasons": ["Disposable email provider", "Domain registered 4 days ago"],
  "applied_rule": null,
  "scoring_version": "decision-v1"
}

Cost, auth, and error behavior are identical to /api/check-email: 1 credit per successful call, same 400/401/402 bodies, plus a 404 while the endpoint isn't live in this deployment.

Reports the actual outcome of a signup (fraud or legitimate) so scoring gets calibrated against real results over time. This isn't a rating of /api/assess's decision; it's ground truth about the identity.

{ "check_id": "0f3c1e6a-1234-4a11-9c2e-8b6f2a5d9e10", "outcome": "fraud" }

Or, without a check_id on hand:

{ "email": "user@example.com", "outcome": "legitimate", "note": "optional, max 500 chars" }

Exactly one of check_id or email must be present.

A successful call returns:

{ "recorded": true, "id": 123 }

• Validate syntax client-side before you call the API, so a malformed address doesn't cost you a credit and a round trip on a 400.
• Branch your logic on isDisposable, not source. The boolean is the contract; source and signals are for logging and tuning your own thresholds.
• Treat null as genuinely unknown, not as false. Decide whether to allow, soft-flag, or challenge rather than hard-blocking.
• Retry 5xx with backoff, and surface 402 to whoever manages billing rather than retrying it.
• If you re-check the same domains often, cache the verdict on your side. Verdicts are stable, and it conserves credits.

Wiring this into a specific stack? These guides show the exact integration point (webhook handler, Action, or API route) for the frameworks Mailsurity customers use most.

• How to block disposable emails in Next.js
• Block fake signups in Clerk and Supabase Auth
• Block disposable signups in Auth0 with a Pre User Registration Action

See all guides at /guides.

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.