# 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)

## Plans
- free: 2000 checks per UTC calendar month; 1 HTTP check/batch requests per second; planned $0/month, currently $0. Available for activation.
- launch: 10000 checks per UTC calendar month; 5 HTTP check/batch requests per second; planned $19/month, not available. Coming soon; not selectable.
- growth: 100000 checks per UTC calendar month; 15 HTTP check/batch requests per second; planned $49/month, not available. Coming soon; not selectable.
- scale: 1000000 checks per UTC calendar month; 30 HTTP check/batch requests per second; planned $149/month, 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":"yopmail.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.