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,
  "mx_masked": 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.

Official SDKs

Prefer a native Software Development Kit (SDK) to raw HTTP calls? Official clients wrap the API above for Python and TypeScript, plus a Model Context Protocol (MCP) server so an MCP capable assistant can call it as a tool.

pip install isitdisposable

npm install isitdisposable

npx -y isitdisposable-mcp

All three fail open by default. On network trouble they return a not checked result with action: "allow" and log a warning, so a signup form using them never breaks because a check could not complete.

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 applied per second, with a ceiling per API key and a higher ceiling per account; they are currently the same on every plan. If you need more throughput, contact support.

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

The quickest integration for an agent is the official MCP server, which hands an MCP capable assistant tools to check email addresses and domains directly.