isitdisposable 0.1.1

Detect disposable, temporary, and throwaway email addresses in real time with a simple Python client for the isitdisposable.com API.

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="[e-mail]")

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(
    [
        "[e-mail]",
        "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.

Field	Type	Meaning
checked	bool	Whether a real check was performed (False on a fail-open response).
normalized_email	str or None	The email address you sent, normalized.
domain	str or None	The domain that was evaluated.
disposable	bool or None	The core verdict: whether the domain is a disposable or throwaway email provider.
mx_valid	bool or None	Whether the domain has a working mail server.
role_account	bool or None	Whether the local part looks like a role address (for example support@).
relay	bool or None	Whether the domain is a mail relay or forwarding service.
public_domain	bool or None	Whether the domain is a large public provider (for example a well known free email service).
spam_risk	bool or None	Whether the domain appears on a spam or abuse reputation list. Only populated if your account has this signal enabled.
mx_masked	bool or None	Whether the domain's mail server is masked or hidden behind a routing service.
did_you_mean	str or None	A suggested correction if the domain looks like a likely typo.
mx_records	list[str] or None	The mail server records found for the domain.
action	str	The recommended action for your account's policy: "allow", "warn", or "block".
reason	str or None	A machine readable reason code. This set is open ended; treat unknown values as informational.
raw	dict	The full parsed response, including any fields not yet listed above, for forward compatibility.

Links

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