Detect disposable email in two lines

Quickstart

The base URL is https://api.isitdisposable.com. Create an account and generate a secret key from the dashboard, then check an address from your backend in your language of choice:

Send either an email or a domain (at least one is required). An email has its domain extracted; a bare domain is checked directly.

curl https://api.isitdisposable.com/v1/check \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{"email": "[email protected]"}'

A disposable address comes back like this:

{
  "checked": true,
  "normalized_email": "[email protected]",
  "domain": "mailinator.com",
  "disposable": true,
  "mx_valid": true,
  "role_account": false,
  "relay": false,
  "public_domain": false,
  "spam_risk": false,
  "did_you_mean": null,
  "mx_records": ["mail.mailinator.com", "mail2.mailinator.com"],
  "action": "block",
  "reason": "disposable"
}

action is one of allow, warn, or block; treat checked: false as allow.

The API fails open. Over quota or for an inactive subscription it still returns HTTP 200 with checked: false and action: "allow", so your form never breaks. Treat allow as do nothing.

Authentication

Send your key as a bearer token: Authorization: Bearer <key>. There are two kinds:

• sk_… secret keys are for server side use only. Keep them out of the browser and any public repository.
• pk_… publishable keys are safe in the browser. Each is restricted to the origins you list, so a lifted key only works from your approved sites. The snippet uses a publishable key.

API reference

Schemas

The request and response objects, as the API returns them.

Snippet install guide

Drop one tag into your page. It watches your email fields and checks them as the visitor types, enforcing the mode you choose. No build step.

<script src="https://cdn.isitdisposable.com/v1/snippet.js"
        data-key="pk_live_…"
        data-mode="warn"
        async></script>

Attributes

The dashboard generates a snippet pre-filled with your publishable key under Snippet.

Errors

Errors return a JSON (JavaScript Object Notation) body of the shape { detail: { reason, message } }. A 429 includes a Retry-After header. Detection problems never raise an error; they fail open with an allow.

Rate limits are per second and depend on your plan; see pricing.

For AI agents

Point your agent or client generator at the machine-readable specification. It is the same schema this page is built from, scoped to the public endpoints:

GET https://api.isitdisposable.com/v1/openapi.json