isitdisposable

Detect disposable, temporary, and burner email addresses in real time from Python, using the isitdisposable.com Application Programming Interface (API).

Install

pip install isitdisposable

or with uv:

uv add isitdisposable

You will need an API key from isitdisposable.com. A free tier is available, so you can try this out without a credit card.

Quick start: check an email address

from isitdisposable import Client

client = Client(api_key="isid_live_your_key_here")

result = client.check(email="someone@example.com")

if result.disposable:
    print("This looks like a disposable email address.")
else:
    print("This looks like a real, ongoing email address.")

api_key can also come from the ISITDISPOSABLE_API_KEY environment variable, so in most setups you can just write Client().

Example: block disposable signups in a Django form

# forms.py
from django import forms
from isitdisposable import Client

client = Client()  # reads ISITDISPOSABLE_API_KEY from the environment


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

    def clean_email(self):
        email = self.cleaned_data["email"]
        result = client.check(email=email)

        if result.disposable:
            raise forms.ValidationError(
                "Please sign up with an email address you check regularly. "
                "Disposable or throwaway addresses are not allowed."
            )

        return email

Example: block disposable signups in a FastAPI dependency

# dependencies.py
from fastapi import Depends, HTTPException
from isitdisposable import AsyncClient

async_client = AsyncClient()  # reads ISITDISPOSABLE_API_KEY from the environment


async def reject_disposable_email(email: str) -> str:
    result = await async_client.check(email=email)

    if result.disposable:
        raise HTTPException(
            status_code=400,
            detail="Please use an email address you check regularly, not a disposable one.",
        )

    return email


# In a route:
# @app.post("/signup")
# async def signup(email: str = Depends(reject_disposable_email)):
#     ...

Checking a batch

Check up to 100 emails or domains in a single request. Items can be plain strings (anything containing an "@" is treated as an email, everything else as a domain) or dicts:

result = client.check_batch(
    [
        "someone@example.com",
        "example.org",
        {"domain": "another-example.com"},
    ]
)

for item in result.results:
    print(item.domain, item.disposable, item.action)

print(f"Checked {result.count} items.")

Fail open by design

Signup forms and checkout flows should never break because of an email checking service having a bad moment. This client fails open by default: if the isitdisposable.com service cannot be reached, times out, is rate limiting you, or has an internal error, check() and check_batch() do not raise. Instead they return a result where checked is False, disposable is None, and action is "allow", and a warning is logged through the standard logging module under the logger name "isitdisposable". Your form keeps working; you can watch the warning logs to notice if this starts happening a lot.

If you would rather see failures as exceptions (for example in a background job where you want to retry later), turn this off:

client = Client(fail_open=False)

With fail_open=False, a connection problem raises NetworkError, a rate limit response raises RateLimitError, and a server error raises ServerError. Invalid requests (a missing or malformed API key, or a request that is missing both an email and a domain) always raise, in either mode, because those indicate something in your own code needs fixing rather than a temporary service problem.

Response fields

Every check returns a result with these fields. Any field can be None if the underlying signal was not evaluated for that request.

Links

• Website: https://isitdisposable.com
• Documentation: https://isitdisposable.com/docs
• A free tier is available, so you can get started without a credit card.