isdisposable 1.0.0

Detect disposable and temporary email addresses. 160k+ domains, zero dependencies.

isdisposable

Detect disposable emails in Python. One function call.

Open-source disposable email detection with 160,000+ domains.
Offline-first. Zero dependencies. Fully typed.

Website · Docs · API Reference

---

Install

pip install isdisposable

Usage

from isdisposable import is_disposable

is_disposable("[e-mail]")  # True
is_disposable("[e-mail]")       # False

Synchronous. Offline. Zero config.

Bulk Check

from isdisposable import is_disposable_bulk

results = is_disposable_bulk([
    "[e-mail]",
    "[e-mail]",
    "[e-mail]",
])
# [True, False, True]

Domain Check

from isdisposable import is_domain_disposable

is_domain_disposable("mailinator.com")  # True
is_domain_disposable("gmail.com")       # False

API Mode — Real-time Detection

For DNS/MX validation, risk scoring, and domain age analysis:

from isdisposable import create_client

client = create_client(api_key="isd_live_xxxxx")

result = client.check("[e-mail]")
print(result.disposable)       # True
print(result.score)            # 95
print(result.reason)           # "blocklist_match"
print(result.mx_valid)         # True
print(result.domain_age_days)  # 3

The API client automatically falls back to offline detection on network errors.

Error Handling

from isdisposable import create_client
from isdisposable.client import AuthenticationError, RateLimitError

client = create_client(api_key="wrong_key")

try:
    result = client.check("[e-mail]")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests")

Bulk API Check

results = client.check_bulk([
    "[e-mail]",
    "[e-mail]",
])
for r in results:
    print(f"{r.email}: {r.disposable} (score: {r.score})")

Framework Integrations

Django — Form Validation

from django import forms
from isdisposable import is_disposable

class SignupForm(forms.Form):
    email = forms.EmailField()

    def clean_email(self):
        email = self.cleaned_data["email"]
        if is_disposable(email):
            raise forms.ValidationError("Disposable emails are not allowed.")
        return email

FastAPI — Dependency

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from isdisposable import is_disposable

app = FastAPI()

class SignupRequest(BaseModel):
    email: str
    password: str

@app.post("/signup")
def signup(req: SignupRequest):
    if is_disposable(req.email):
        raise HTTPException(400, "Disposable emails are not allowed")
    return {"ok": True}

Flask — Before Request

from flask import Flask, request, jsonify
from isdisposable import is_disposable

app = Flask(__name__)

@app.route("/signup", methods=["POST"])
def signup():
    email = request.json.get("email", "")
    if is_disposable(email):
        return jsonify(error="Disposable emails are not allowed"), 400
    return jsonify(ok=True)

Pydantic — Field Validator

from pydantic import BaseModel, field_validator
from isdisposable import is_disposable

class User(BaseModel):
    email: str

    @field_validator("email")
    @classmethod
    def check_disposable(cls, v: str) -> str:
        if is_disposable(v):
            raise ValueError("Disposable emails are not allowed")
        return v

API Reference

is_disposable(email: str) -> bool

Returns True if the email is from a disposable provider.

is_disposable_bulk(emails: list[str]) -> list[bool]

Bulk check. Returns list of booleans matching input order.

is_domain_disposable(domain: str) -> bool

Check a domain directly.

extract_domain(email: str) -> str | None

Extract the domain from an email address.

create_client(api_key, ...) -> IsDisposableClient

Create an API client with .check(), .check_bulk(), and .clear_cache().

SDKs

Language	Package	Status
JavaScript/TypeScript	@isdisposable/js	Stable
Python	isdisposable	Stable
Go	isdisposable-go	Coming soon

License

MIT

---

Built by Junaid Shaukat
Dashboard & API at isdisposable.com