Metadata-Version: 2.5
Name: disban
Version: 0.3.0
Summary: Detect disposable email at signup: classify an email domain as disposable, free, alias, testing, parked or unknown. Works without an API key.
Project-URL: Homepage, https://disban.io
Project-URL: Documentation, https://disban.io/docs
Project-URL: Support, https://disban.io/support
Author-email: Disban <info@disban.io>
License-Expression: MIT
Keywords: burner-email,disposable-email,email-validation,signup,temporary-email
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# disban

Detect disposable email addresses at signup. `disban` classifies the domain of an email address as **disposable**, **free** (Gmail, Outlook), **alias** (privacy relays such as SimpleLogin), **testing**, **parked** or **unknown**, and tells you whether it can receive mail. Works without an API key. Standard library only.

```sh
pip install disban
```

```python
from disban import is_disposable, signup_decision

is_disposable("someone@yopmail.com")   # True; None means unknown (not verified safe)

decision = signup_decision(email)
if decision["action"] == "block":
    raise ValueError("Please use a permanent email address.")
if decision["action"] == "fix":
    raise ValueError("That domain can't receive email. Check for a typo.")
# "allow": create the account; if decision["hold"], hold free credits until the email is confirmed
```

`signup_decision` fails open: if Disban is slow, unreachable or rate-limited, it allows the signup with `hold: True`.

## FastAPI

```python
from fastapi import FastAPI, HTTPException
from disban import signup_decision

app = FastAPI()

@app.post("/signup")
def signup(email: str):
    decision = signup_decision(email)
    if decision["action"] != "allow":
        raise HTTPException(422, decision["reason"])
    return {"ok": True, "review": decision.get("hold", False)}
```

## Limits and API keys

Start straight away without a key: 10 checks an hour and 30 a day per network, from your server. When that runs out, `disban check` offers to create your free account on the spot, and in server code you'll get a one-time warning telling you to run `disban signup`. For production, set `DISBAN_API_KEY`: a free key includes **2,000 checks a month** with the evidence behind each result. [disban.io/signup](https://disban.io/signup)

```sh
disban signup     # free account and API key from the terminal; saves DISBAN_API_KEY to ./.env if you want
disban login      # new key for an existing account
disban check someone@mailinator.com example.com
```

[Docs](https://disban.io/docs) · [Methodology](https://disban.io/methodology) · [llms.txt](https://disban.io/llms.txt)
