DEVELOPER DOCS

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

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 email
func 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.

CategoryWhat it meansRecommended action
disposableA temporary inbox anyone can openBlock, or ask for another address
testingMail-testing infrastructureBlock in production
freeConsumer provider such as Gmail or OutlookAllow. For B2B, ask for a work email or score lower
aliasPrivacy relay such as SimpleLogin or Firefox RelayAllow, or set your own rule. These are real, long-lived users
parkedParking or registrar mailAsk for another address
unknownNot enough evidence either wayAllow, verify the email, hold rewards until confirmed
mail route invalidThe domain can't receive mail nowAsk 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.

EndpointAuthUse it for
GET /api/v1/check/{input}NoneTrying it, prototypes and low volume
POST /api/checkBearer keyOne email or domain, full evidence
POST /api/batchBearer keyUp to 50 at once, results in input order
POST /api/webhooks/checkBearer keyForm tools and automations that push one or many inputs
GET /api/subscriptionBearer keyPlan, 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

FieldTypeMeaning
domainstringThe normalised domain that was classified
categorystringdisposable, free, alias, testing, parked or unknown
reasonstringWhy: see the reason codes below
matched_onstring?The listed domain or provider that matched (may be a parent domain)
disposablebool or nulltrue or false when classified; null when unknown. Never treat null as safe
historical_disposableboolThe domain has disposable history. Not a low-confidence flag, not proof of current operation
mail_routingobjectstatus (routable, invalid, unknown), reason, observed_at, expires_at
mx, mx_recordsbool?, array?Mail exchangers when fresh evidence exists; priorities are null for now
public_domain, relay_domain, aliasbool?true on a positive match, otherwise null
email, normalized_emailstring?Echoed back to you only; never stored
cached, latency_msbool, numberWhether stored evidence answered, and how long it took
spf, dmarc, spam, role_account, did_you_mean, …nullNot 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 →

ReasonCategoryMeaning
list_matchdisposableThe domain or a parent is on the reviewed disposable inventory
mx_cluster, reviewed_operator_mxdisposableIts mail servers belong to a known disposable operator, even if the domain is new
redirect_to_disposabledisposableIts website redirects to a known disposable service
current_provider_pooldisposableCurrently offered by a disposable service
free_webmailfreeA consumer email provider
alias_provideraliasA privacy relay or forwarding service
managed_mx, shared_mxunknownBusiness mail platform or shared hosting: too mixed to label disposable
cleanunknownReceives mail; nothing matched
historical_seed_only, reassessment_requiredunknownDisposable history only; it has to show current evidence again
domain_not_foundunknownThe 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.statusMeaning
routableHas mail servers (reason mx) or an implicit route (implicit_mx). It doesn't prove a mailbox exists
invalidNo current route: domain_not_found, no_mx_or_address or null_mx. Ask for a correction
unknownVerification pending or unavailable. The API returns 503 instead of guessing

Errors

StatusWhenWhat to do
400Invalid input: not an email address or domainFix the input
401Missing, invalid or revoked keyCheck DISBAN_API_KEY
403Browser call from another siteCall from your server
409Free plan already has an active keyRevoke it in Settings, then create a new one
415Body isn't JSONSend Content-Type: application/json
429Rate or monthly limit (or keyless limit)Wait for Retry-After. Keyless: run npx disban signup
502Checker unavailableRetry with backoff; fail open
503Mail-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

KeylessFree key
Checks10 an hour, 30 a day per network2,000 a month
RateShared1 request a second (a batch counts as one)
Responsecategory, disposable, mail_routingFull evidence (fields above)
Batch, webhook, usage APINoYes
ChargedNeverSuccessful 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 stdio

MCP 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_KEY

Agents 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