Check the email domain
before you create the account.
One call tells you whether an email’s domain is disposable, a free provider, a privacy alias, testing, parked or unknown, and whether it can receive mail. Start without a key; add one when you need more.
Quickstart
Try it now. No account, no key. The keyless endpoint allows 10 checks an hour and 30 a day per network. To check one domain by hand, use the free disposable email checker.
# No key, no signup. From your server or terminal.
curl https://disban.io/api/v1/check/someone@yopmail.com
{"domain":"yopmail.com","category":"disposable","disposable":true,"mail_routing":"routable"}// npm install disban
import { signupDecision } from "disban";
const decision = await signupDecision("someone@yopmail.com");
// { action: "block", reason: "disposable", result: { ... } }# pip install disban
from disban import signup_decision
decision = signup_decision("someone@yopmail.com")
# {"action": "block", "reason": "disposable", "result": {...}}Get a free API key
A free key gives you 2,000 checks a month, the full evidence behind each result, batch checks and a usage API. Get one without leaving the terminal, or sign up on the web.
npx disban signup # or: pip install disban && disban signup
# Your name, your email, the 6-digit code from the email.
# The key is printed once and can be saved to ./.env as DISBAN_API_KEY.curl -X POST https://disban.io/api/check \
-H "Authorization: Bearer $DISBAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"someone@yopmail.com"}'The SDKs use DISBAN_API_KEY automatically. When the keyless allowance runs out, the CLI offers to sign you up on the spot.
Use cases
Free trials and credits
Stop one person opening ten trials with ten inboxes. Block disposable and testing domains; hold credits for unknown ones until the email is confirmed.
Referral programs
Pay rewards only to accounts on real, long-lived inboxes. Check the invitee before the reward is granted, not after.
B2B lead forms
Disposable addresses are junk; free providers (Gmail, Outlook) are real people but not a company domain. Route them differently instead of blocking.
Newsletters and waitlists
Keep sign-up lists clean so engagement and deliverability numbers mean something. Flag domains that can't receive mail.
Cleaning an existing list
Check up to 50 emails or domains per request with batch. Only the domain is classified.
Coding agents
Give Claude Code or Cursor a check_email_domain tool, or point the agent at llms.txt and the OpenAPI schema.
Recipes
signupDecision (Node) and signup_decision (Python) return block, fix or allow. They fail open: if Disban is slow, unreachable or rate-limited, the signup is allowed with hold: true, so real users are never locked out.
// app/api/signup/route.js
import { signupDecision } from "disban";
export async function POST(request) {
const { email } = await request.json();
const decision = await signupDecision(email);
if (decision.action === "block")
return Response.json({ error: "Please use a permanent email address." }, { status: 422 });
if (decision.action === "fix")
return Response.json({ error: "That domain can't receive email. Check for a typo." }, { status: 422 });
// Create the user. When decision.hold is true, hold free credits until the email is confirmed.
return Response.json({ ok: true });
}import express from "express";
import { signupDecision } from "disban";
const app = express();
app.use(express.json());
async function blockDisposable(req, res, next) {
const decision = await signupDecision(req.body.email);
if (decision.action !== "allow") return res.status(422).json({ error: decision.reason });
req.holdCredits = decision.hold; // unknown domain or Disban unreachable
next();
}
app.post("/register", blockDisposable, createAccount);import { betterAuth } from "better-auth";
import { APIError } from "better-auth/api";
import { signupDecision } from "disban";
export const auth = betterAuth({
databaseHooks: {
user: {
create: {
before: async (user) => {
const decision = await signupDecision(user.email);
if (decision.action !== "allow")
throw new APIError("BAD_REQUEST", { message: "Please use a permanent email address." });
return { data: user };
},
},
},
},
});// Blocking function: runs before Firebase creates the account.
import { beforeUserCreated, HttpsError } from "firebase-functions/v2/identity";
import { signupDecision } from "disban";
export const blockDisposable = beforeUserCreated(async (event) => {
const decision = await signupDecision(event.data.email, { timeoutMs: 3000 });
if (decision.action === "block")
throw new HttpsError("invalid-argument", "Please use a permanent email address.");
if (decision.action === "fix")
throw new HttpsError("invalid-argument", "That email domain can't receive mail. Check it for typos.");
});
// Cloud Functions share outbound IPs: set DISBAN_API_KEY as a secret rather than relying on keyless checks.from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from disban import signup_decision
app = FastAPI()
class Signup(BaseModel):
email: str
@app.post("/signup")
def signup(body: Signup):
decision = signup_decision(body.email)
if decision["action"] != "allow":
raise HTTPException(422, decision["reason"])
return {"ok": True, "hold_credits": decision.get("hold", False)}from django import forms
from disban import signup_decision
class SignupForm(forms.Form):
email = forms.EmailField()
def clean_email(self):
email = self.cleaned_data["email"]
decision = signup_decision(email)
if decision["action"] == "block":
raise forms.ValidationError("Please use a permanent email address.")
if decision["action"] == "fix":
raise forms.ValidationError("That domain can't receive email. Check for a typo.")
self.hold_credits = decision.get("hold", False)
return emailfunc emailCategory(ctx context.Context, email string) (string, error) {
body, _ := json.Marshal(map[string]string{"input": email})
req, err := http.NewRequestWithContext(ctx, "POST", "https://disban.io/api/check", bytes.NewReader(body))
if err != nil {
return "", err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("DISBAN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
return "", err // fail open: allow the signup and hold rewards
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return "", fmt.Errorf("disban: HTTP %d", res.StatusCode)
}
var v struct {
Category string `json:"category"`
}
if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
return "", err
}
return v.Category, nil
}import { signupDecision } from "disban"; // runs on Workers; no Node APIs needed
export default {
async fetch(request, env) {
const { email } = await request.json();
const decision = await signupDecision(email, { apiKey: env.DISBAN_API_KEY });
if (decision.action !== "allow")
return Response.json({ error: decision.reason }, { status: 422 });
return Response.json({ ok: true, hold: decision.hold });
},
};// Supabase Edge Function, wired up as the "Before User Created" HTTP hook
// (Dashboard: Authentication → Hooks). Runs before Supabase creates the account.
import { beforeUserCreated } from "npm:disban/supabase";
// Verifies Supabase's signature, blocks disposable and test inboxes and domains
// that can't receive mail, and allows everyone else. If Disban is slow or
// unreachable it allows the signup: real users are never locked out.
Deno.serve(beforeUserCreated());
// Secrets: SUPABASE_HOOK_SECRET (from the hook settings) and DISBAN_API_KEY.// Auth0 Action, trigger: Pre User Registration. Add the "disban" npm package
// as a dependency and DISBAN_API_KEY as a secret in the Action settings.
exports.onExecutePreUserRegistration = async (event, api) => {
const { signupDecision } = await import("disban");
const decision = await signupDecision(event.user.email, {
apiKey: event.secrets.DISBAN_API_KEY,
timeoutMs: 3000,
});
if (decision.action === "block")
return api.access.deny("disposable_email", "Please sign up with a permanent email address.");
if (decision.action === "fix")
return api.access.deny("no_mail_route", "That email domain can't receive mail. Check it for typos.");
if (decision.hold) api.user.setAppMetadata("disban_hold", true);
};
// Runs for database and passwordless signups, not social logins.// Clerk has no hook before an account is created, so act on the user.created
// webhook: ban accounts made with a disposable inbox. Next.js route handler,
// endpoint added in Dashboard → Webhooks with CLERK_WEBHOOK_SIGNING_SECRET set.
import { verifyWebhook } from "@clerk/nextjs/webhooks";
import { clerkClient } from "@clerk/nextjs/server";
import { signupDecision } from "disban";
export async function POST(req) {
const evt = await verifyWebhook(req);
if (evt.type !== "user.created") return new Response("ok");
const email = evt.data.email_addresses?.[0]?.email_address;
const decision = email ? await signupDecision(email) : null;
// Only "block": the account already exists, so never act on a typo or an outage.
if (decision?.action === "block") await (await clerkClient()).users.banUser(evt.data.id);
return new Response("ok");
}Signup policy
Act on category, then on mail_routing. Blocking every free address turns away real customers; treating unknown as safe lets new disposable domains through. Tell people what to do, not what you suspect, and link disban.io/why from your error message: it explains the check to the person who was turned away.
| Category | What it means | Recommended action |
|---|---|---|
disposable | A temporary inbox anyone can open | Block, or ask for another address |
testing | Mail-testing infrastructure | Block in production |
free | Consumer provider such as Gmail or Outlook | Allow. For B2B, ask for a work email or score lower |
alias | Privacy relay such as SimpleLogin or Firefox Relay | Allow, or set your own rule. These are real, long-lived users |
parked | Parking or registrar mail | Ask for another address |
unknown | Not enough evidence either way | Allow, verify the email, hold rewards until confirmed |
mail route invalid | The domain can't receive mail now | Ask the user to fix a typo |
API reference
Base URL https://disban.io. Send JSON with Content-Type: application/json and authenticate with Authorization: Bearer dbn_…. Call from your server: browser requests from other sites are refused.
| Endpoint | Auth | Use it for |
|---|---|---|
GET /api/v1/check/{input} | None | Trying it, prototypes and low volume |
POST /api/check | Bearer key | One email or domain, full evidence |
POST /api/batch | Bearer key | Up to 50 at once, results in input order |
POST /api/webhooks/check | Bearer key | Form tools and automations that push one or many inputs |
GET /api/subscription | Bearer key | Plan, remaining checks, reset time |
GET /api/v1/check/{email or domain}
No key. Returns domain, category, disposable and mail_routing (routable or invalid). Response headers include RateLimit-Policy and RateLimit-Remaining; at the limit you get 429 with Retry-After.
curl https://disban.io/api/v1/check/person@duck.com
{"domain":"duck.com","category":"alias","disposable":false,"mail_routing":"routable"}
POST /api/check
Body {"input": "email or domain"}. Add ?realtime=true to wait (up to 2.5 seconds) for a live mail-route lookup, or ?realtime=false for stored evidence only. Without the parameter, stale routing is refreshed live.
{
"domain": "sharklasers.com",
"category": "disposable",
"reason": "list_match",
"matched_on": "sharklasers.com",
"disposable": true,
"historical_disposable": true,
"mail_routing": {
"status": "routable",
"reason": "mx",
"observed_at": "2026-10-15T09:12:03Z",
"expires_at": "2026-10-15T09:17:03Z"
},
"mx": true,
"mx_records": [{ "hostname": "mail.guerrillamail.com", "priority": null }],
"public_domain": null,
"relay_domain": null,
"alias": null,
"email": "someone@sharklasers.com",
"normalized_email": "someone@sharklasers.com",
"cached": false,
"latency_ms": 41.2
}
POST /api/batch
Body {"inputs": [...]}, up to 50 entries. Results come back in input order; a failed entry carries status and error and is refunded. Uses one rate-limit slot and one credit per successful entry.
curl -X POST https://disban.io/api/batch \
-H "Authorization: Bearer $DISBAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs":["gmail.com","sharklasers.com","person@duck.com"]}'
{"results":[{"domain":"gmail.com","category":"free",...},{"domain":"sharklasers.com","category":"disposable",...},{"domain":"duck.com","category":"alias",...}]}
POST /api/webhooks/check
For form builders and automation tools: send {"input": "..."} or {"inputs": [...]} and get results back in the same response. Lookup-only by default; add ?realtime=true for live checks. Same key and quota. There are no outbound callbacks.
GET /api/subscription
Returns your plan, remaining (monthly plus bonus credits), monthly_remaining, bonus_remaining and resets_at (UTC).
Response fields
| Field | Type | Meaning |
|---|---|---|
domain | string | The normalised domain that was classified |
category | string | disposable, free, alias, testing, parked or unknown |
reason | string | Why: see the reason codes below |
matched_on | string? | The listed domain or provider that matched (may be a parent domain) |
disposable | bool or null | true or false when classified; null when unknown. Never treat null as safe |
historical_disposable | bool | The domain has disposable history. Not a low-confidence flag, not proof of current operation |
mail_routing | object | status (routable, invalid, unknown), reason, observed_at, expires_at |
mx, mx_records | bool?, array? | Mail exchangers when fresh evidence exists; priorities are null for now |
public_domain, relay_domain, alias | bool? | true on a positive match, otherwise null |
email, normalized_email | string? | Echoed back to you only; never stored |
cached, latency_ms | bool, number | Whether stored evidence answered, and how long it took |
spf, dmarc, spam, role_account, did_you_mean, … | null | Not collected yet. Null means unavailable, not negative |
Categories and reasons
Read category first; reason and matched_on explain it. Unknown means not enough evidence, not verified safe. How classification works →
| Reason | Category | Meaning |
|---|---|---|
list_match | disposable | The domain or a parent is on the reviewed disposable inventory |
mx_cluster, reviewed_operator_mx | disposable | Its mail servers belong to a known disposable operator, even if the domain is new |
redirect_to_disposable | disposable | Its website redirects to a known disposable service |
current_provider_pool | disposable | Currently offered by a disposable service |
free_webmail | free | A consumer email provider |
alias_provider | alias | A privacy relay or forwarding service |
managed_mx, shared_mx | unknown | Business mail platform or shared hosting: too mixed to label disposable |
clean | unknown | Receives mail; nothing matched |
historical_seed_only, reassessment_required | unknown | Disposable history only; it has to show current evidence again |
domain_not_found | unknown | The domain doesn't exist |
Mail routing
Routing is reported separately from the category: a disposable domain can route mail, and a real company’s domain can be misspelled.
| mail_routing.status | Meaning |
|---|---|
routable | Has mail servers (reason mx) or an implicit route (implicit_mx). It doesn't prove a mailbox exists |
invalid | No current route: domain_not_found, no_mx_or_address or null_mx. Ask for a correction |
unknown | Verification pending or unavailable. The API returns 503 instead of guessing |
Errors
| Status | When | What to do |
|---|---|---|
| 400 | Invalid input: not an email address or domain | Fix the input |
| 401 | Missing, invalid or revoked key | Check DISBAN_API_KEY |
| 403 | Browser call from another site | Call from your server |
| 409 | Free plan already has an active key | Revoke it in Settings, then create a new one |
| 415 | Body isn't JSON | Send Content-Type: application/json |
| 429 | Rate or monthly limit (or keyless limit) | Wait for Retry-After. Keyless: run npx disban signup |
| 502 | Checker unavailable | Retry with backoff; fail open |
| 503 | Mail-route verification couldn't finish (verification_unavailable) | Retry after Retry-After. Not charged |
Checks have no idempotency key: don’t blindly retry a successful request, because each success uses a credit.
Limits
| Keyless | Free key | |
|---|---|---|
| Checks | 10 an hour, 30 a day per network | 2,000 a month |
| Rate | Shared | 1 request a second (a batch counts as one) |
| Response | category, disposable, mail_routing | Full evidence (fields above) |
| Batch, webhook, usage API | No | Yes |
| Charged | Never | Successful checks only (cache hits included); failures refunded |
SDKs and CLI
No dependencies. npm: disban ↗ (Node 18+, Bun, Deno, edge runtimes) · PyPI: disban ↗ (Python 3.8+, standard library only).
import { check, isDisposable, signupDecision, DisbanError } from "disban";
await check("person@duck.com"); // full result object
await isDisposable("a@yopmail.com"); // true | false | null (unknown)
await signupDecision(email); // { action: "block" | "fix" | "allow", hold?, reason, result? }
// Options: { apiKey, timeoutMs = 5000, baseUrl, fetch }from disban import check, is_disposable, signup_decision, DisbanError
check("person@duck.com") # dict
is_disposable("a@yopmail.com") # True | False | None (unknown)
signup_decision(email) # {"action": "block" | "fix" | "allow", ...}
# Options: api_key=..., timeout=5.0, base_url=...npx disban check someone@mailinator.com example.com
npx disban signup # free account and key
npx disban login # new key for an existing account
npx disban mcp # MCP server over stdioMCP server
Give your agent Disban as tools: check_email_domain, check_email_domains (up to 50) and get_usage. The hosted server at https://disban.io/mcp (Streamable HTTP) uses your API key and the same monthly credits as the API. The local server runs with npx and works without a key.
claude mcp add --transport http disban https://disban.io/mcp \
--header "Authorization: Bearer $DISBAN_API_KEY"{
"mcpServers": {
"disban": {
"url": "https://disban.io/mcp",
"headers": { "Authorization": "Bearer dbn_your_key" }
}
}
}claude mcp add disban -- npx -y disban mcp # keyless, or set DISBAN_API_KEYAgents and machine-readable docs
llms.txt (integration guide) · llms-full.txt (every guide in full) · OpenAPI 3.1 · Agent quickstart, including account activation with the owner’s authorisation.
Privacy and keys
- Only the domain is classified and stored. The part before the @ is echoed back to you and never kept.
- Call Disban from your server. Keep keys in environment variables or a secret manager, never in browser code or source control.
- Revoke a key in Settings; it stops working on the next request. Free allows one active key.
- Free plan history is kept for 15 days, then deleted.
- Free beta: limits and fields may change. Questions or a misclassified domain: support.