# Disban
> Disban is an email-domain classification API (Free beta). It classifies a domain as disposable, free, alias, testing, parked or unknown so you can protect signups.

## Discover
- API base: https://disban.io
- [OpenAPI 3.1](https://disban.io/openapi.json)
- [Plan catalog](https://disban.io/api/plans)
- [Human quickstart](https://disban.io/agents)
- [API documentation](https://disban.io/docs)

## Try it without a key
GET https://disban.io/api/v1/check/{email or domain} returns {"domain","category","disposable","mail_routing"}. No signup or key. Call it from your server, not the browser (browser cross-origin requests get 403). Limits: 10 per hour and 30 per day per network, then HTTP 429 with Retry-After. disposable is null when the category is unknown: treat that as unverified, not safe. For production signup traffic, use a free API key (2,000 checks per month, full evidence, batch) with POST /api/check below.
Example: curl https://disban.io/api/v1/check/sharklasers.com -> {"domain":"sharklasers.com","category":"disposable","disposable":true,"mail_routing":"routable"}

## SDK, CLI and MCP (npm and PyPI: disban)
Start without signing up: npm install disban (or pip install disban) works immediately on the keyless allowance. When it runs out, get a free key from the terminal with npx disban signup (or disban signup): name, email, the emailed 6-digit code, and the key is printed and can be saved to ./.env as DISBAN_API_KEY. npx disban login issues a key for an existing account.
npm install disban. import { signupDecision } from "disban"; const d = await signupDecision(email); then block when d.action is "block", ask for a correction when "fix", otherwise create the account and hold free credits when d.hold is true. It fails open (allow with hold) if Disban is slow, unreachable or rate-limited. Without DISBAN_API_KEY it uses the keyless endpoint; with it, POST /api/check.
CLI: npx disban check someone@example.com
Hosted MCP server (Streamable HTTP, uses your API key and plan credits; tools check_email_domain, check_email_domains, get_usage): claude mcp add --transport http disban https://disban.io/mcp --header "Authorization: Bearer $DISBAN_API_KEY"
Local MCP server (keyless or DISBAN_API_KEY): claude mcp add disban -- npx -y disban mcp

## Plans
- free: 2000 checks per UTC calendar month; 1 HTTP check/batch requests per second; $0. Available for activation.
- launch: 10000 checks per UTC calendar month; 5 HTTP check/batch requests per second; not available. Coming soon; not selectable.
- growth: 100000 checks per UTC calendar month; 15 HTTP check/batch requests per second; not available. Coming soon; not selectable.
- scale: 1000000 checks per UTC calendar month; 30 HTTP check/batch requests per second; not available. Coming soon; not selectable.
Free is the only plan available for activation: 2,000 checks per UTC month and one active API key. Launch, Growth, and Scale are coming soon. No payment or automatic billing. Successful domain checks consume credits; failed checks are refunded. Plan changes preserve usage. Activity retention follows your current plan: Free 15 days, Launch 30, Growth 60, Scale 90. Expired activity is deleted; upgrades do not restore deleted records. Saved results are never recalculated.

## Activate with owner authorization
1. GET /api/plans to inspect current plans and launch terms.
2. POST /api/auth/otp/request with JSON {"intent":"signup","name":"OWNER_NAME","email":"OWNER_EMAIL","plan_id":"free"}. Disban checks the signup domain before sending a code. With the owner's authorization, submit the emailed code to POST /api/auth/otp/verify {"intent":"signup","challenge_id":"RETURNED_ID","code":"SIX_DIGIT_CODE"}. Save the returned session cookie securely. Existing accounts use intent "login" for both requests. Password authentication is disabled. Codes expire in ten minutes, permit five attempts and can be used once. Never store codes in logs or source control.
3. POST /api/keys with the session cookie and JSON {"name":"Agent integration"}. The response contains token, shown only once. Store it in a secret manager, not in logs or source control.
4. POST /api/check with Authorization: Bearer TOKEN and JSON {"input":"sharklasers.com"}. Or POST /api/batch with {"inputs":["gmail.com","yopmail.com"]}, maximum 50 entries.
5. GET /api/subscription with Bearer TOKEN to inspect the selected plan, usage and reset time. remaining includes unexpired referral credits; monthly_remaining and bonus_remaining separate the balances. Monthly credits are used first, then bonus credits by expiry. Failed checks refund their original source. GET /api/referrals requires an owner session and returns the referral link and reward policy. Change plan with POST /api/subscription {"plan_id":"free"} using the owner's session, not an API key. Switching plans does not reset usage.
6. DELETE /api/keys/{id} using the session cookie to revoke a key. POST /api/auth/logout with {} to end the session.

All POSTs require Content-Type: application/json. Browser cross-origin calls are rejected; use server-side HTTP. Signup returns 201 and Set-Cookie. A key is scoped to check, batch, inbound check webhook and read-only subscription usage; it cannot administer accounts or keys. No payment method is collected and no money is charged.

## Lookup, realtime and incoming webhook
Add ?realtime=false to /api/check or /api/batch for stored fresh evidence only. Add ?realtime=true to wait for bounded live routing. Missing or stale lookup evidence is unknown, never a safe result. Omitted mode preserves standard verification.
POST /api/webhooks/check accepts {"input":"person@example.com"} or {"inputs":["example.com","example.org"]} and returns ordered results immediately. It defaults to lookup-only; ?realtime=true enables live checks. Use the same API key and quotas. This is an inbound push endpoint, with no outbound callback.
Unknown domains join discovery using domain names only. A queued candidate does not become a disposable seed automatically.

## Results and errors
Activity retention follows the current plan: Free 15 days, Launch 30 days, Growth 60 days, Scale 90 days. A plan change applies the new retention window to existing activity. Expired records are deleted and cannot be restored by upgrading. Saved results are never recalculated; new checks create new results. Monthly credit usage is independent of activity retention.

Unavailable enrichment fields are null, not negative results. email and normalized_email are request-only echoes and are never retained in history. disposable is null when unresolved. SPF, DMARC, authority, spam reputation, MX provider metadata, role detection, and typo suggestions are not yet collected. MX priorities are null until collected.
Use category (disposable, free, alias, testing, parked, unknown), reason, and optional matched_on. Unknown is not verified safe. Alias is distinct from disposable. This is domain classification, not mailbox existence verification. Inspect mail_routing separately: invalid means no current public mail route; unknown means verification is pending or temporarily unavailable; routable does not prove a mailbox exists. Cold and expired routing checks wait up to 2.5 seconds for verification. Unresolved routing returns HTTP 503 with code verification_unavailable and Retry-After matching the cached DNS retry deadline (five seconds when no deadline is available), rather than a successful pending verdict. Batch failures carry status 503 per entry. No credit is charged and no successful check is saved. Retry with backoff and respect rate limits. A returning domain may have reason reassessment_required; historical evidence alone does not restore a disposable verdict.
400 invalid input; 401 missing/expired credentials; 403 cross-origin; 409 duplicate account or key limit; 413 oversized body; 415 wrong content type; 429 rate or quota exceeded (Retry-After header); 502 checker unavailable; 503 verification unavailable (Retry-After header). Batch errors appear per entry; failed entries are refunded. Cache hits cost one credit. A batch uses one request-rate slot and one monthly credit per successful entry. Do not blindly retry successful checks: checking has no idempotency key and repeated successes consume credits.

Only Free is available for activation, with one active API key. Future paid plans require explicit opt-in. No SLA, team seats, outbound webhook callbacks, or mailbox delivery guarantee is offered in this preview.


## Guides
- [The best disposable email detection APIs in 2026, compared](https://disban.io/blog/best-disposable-email-detection-apis): Disban, UserCheck, Kickbox, ZeroBounce, Abstract API, DeBounce and open-source lists: free tiers, entry prices, what each checks, and which fits signup protection.
- [How to block disposable emails before sending with Resend (Node.js)](https://disban.io/blog/block-disposable-emails-before-sending-with-resend): Resend does not check whether an address is disposable. Check the domain with Disban first, then send the verification email with Resend only when the address is allowed.
- [What is a disposable email address?](https://disban.io/blog/what-is-a-disposable-email-address): A disposable email address is a temporary inbox that works for minutes or days and is then abandoned. How they work, how they differ from free email and aliases, and how to recognise one.
- [How to detect disposable email addresses: five methods compared](https://disban.io/blog/how-to-detect-disposable-email-addresses): Blocklists, mail-server checks, operator matching, APIs and behaviour signals: what each method catches, what it misses, and which combination works at signup.
- [Is Gmail a disposable email? Free email vs disposable email](https://disban.io/blog/is-gmail-a-disposable-email): No. Gmail, Outlook and Proton Mail are free email providers with long-term inboxes. Why some blocklists include them anyway, and how to treat free email at signup.
- [How temporary email services work, and why new domains keep appearing](https://disban.io/blog/how-temporary-email-services-work): Temporary email services run many domains on the same mail servers and replace them as they get blocked. Our October 2026 data on Yopmail, Mailinator and generator.email shows the pattern.
- [Should you block disposable email addresses?](https://disban.io/blog/should-you-block-disposable-emails): Usually yes for free trials and credits, but not always outright. When to block, when to allow with limits, and how to avoid turning away real customers.
- [Half of known disposable email domains no longer exist (October 2026 data)](https://disban.io/blog/half-of-disposable-email-domains-no-longer-exist): We looked up all 429,532 domains in Disban's disposable-email inventory. 52.1% no longer exist and only 40.5% can receive mail. Here is what that means for blocklists.
- [Disposable email runs on shared mail infrastructure: what 8,522 mail operators tell us](https://disban.io/blog/disposable-email-infrastructure-cloudflare-mail-operators): Live disposable domains are spread across 8,522 mail operators, and 12.2% of them route through Cloudflare's free email forwarding. Why that makes domain-level evidence essential.
- [How to block disposable emails at signup (with code)](https://disban.io/blog/block-disposable-emails-at-signup): Check the email domain on your server before creating the account, act on the category, and handle unknown results and outages without blocking real users.
- [Disposable email vs email alias: make the right signup decision](https://disban.io/blog/disposable-email-vs-email-alias): Separate public inboxes, personal mail, and privacy relays before deciding which signups to accept.
- [Gmail dots, plus tags, and the limits of email identity](https://disban.io/blog/gmail-dots-plus-tags-signup-limits): How to separate a delivery address from a limits identity without merging the wrong accounts.
- [How much free credit can duplicate accounts unlock?](https://disban.io/blog/free-trial-referral-credit-exposure): Model the free allowance and referral reward together, then choose the controls that address the actual exposure.
- [How to block disposable emails in a Next.js signup route](https://disban.io/blog/block-disposable-emails-nextjs): Reject Yopmail, Mailinator and other throwaway inboxes in a Next.js App Router route handler or Server Action with one call to Disban. Works without an API key.
- [Express middleware to block disposable and temporary email signups](https://disban.io/blog/block-disposable-emails-express): A drop-in Express middleware that rejects disposable and temporary email domains at registration, fails open on outages, and works without an API key.
- [Reject disposable emails in a Python FastAPI signup endpoint](https://disban.io/blog/block-disposable-emails-python-fastapi): Use the disban package (standard library only) to reject disposable and temporary emails in FastAPI, Flask or Django signup code, with a keyless start and a fail-open default.
- [An API that tells disposable, free and privacy-alias emails apart](https://disban.io/blog/api-disposable-free-or-alias-email): Disposable inbox, free provider like Gmail, or privacy relay like SimpleLogin? One API call returns which, so you can block throwaway inboxes without turning away real people.

## Free tools
- [Free Disposable Email Checker](https://disban.io/tools/disposable-email-checker): Check whether an email address or domain is disposable, free webmail, a privacy alias or parked. Free live check, no signup, with its limits explained.
- [CSV Email List Profiler](https://disban.io/tools/csv-email-profiler): Extract domains locally, remove duplicates, and inspect a small list without uploading anyone’s full email address.
- [Signup Guard Generator](https://disban.io/tools/signup-guard-generator): Generate a server-side JavaScript integration with explicit decisions for disposable and unresolved results.
- [Email Alias Explorer](https://disban.io/tools/email-alias-explorer): See which addresses group together under Disban's signup-limit policy. Keep delivery and identity separate.
- [Signup Policy Lab](https://disban.io/tools/signup-policy-lab): Explore a decision before turning it into a signup rule. Personal inbox, relay, disposable, or unresolved?
- [Free Credit Exposure Calculator](https://disban.io/tools/free-credit-calculator): See the combined effect of free accounts and referral rewards. Change the inputs, inspect the assumptions.

## Reference
- [Methodology](https://disban.io/methodology): how domains are classified and what the evidence means
- [Provider directory](https://disban.io/directory): disposable, free, alias and testing providers with their domains
- [Support and corrections](https://disban.io/support): report a misclassified domain
- [Why was my email address rejected?](https://disban.io/why): for people turned away at signup; sites can link it from their error message
- [Full text of every guide](https://disban.io/llms-full.txt)