Block disposable emails in Django and Python (free API, offline fallback)

"""Block disposable email addresses: FFraud's free API decides, its MIT list answers when the API cannot.

Standard library only. refresh_list() downloads the list; run it daily from cron or a scheduler.
"""
import json
import os
import re
import time
import urllib.request

LIST_URL = "https://raw.githubusercontent.com/FFraud-com/disposable-email-domains/main/disposable-email-domains.txt"
API_URL = "https://api.ffraud.com/public/email/check"
LIST_PATH = os.environ.get("DISPOSABLE_LIST", "disposable-email-domains.txt")
# Relay services such as Apple's Hide My Email forward to an inbox a real person reads. Set to False to refuse them too.
ACCEPT_RELAYS = True

EMAIL = re.compile(
    r"(?!\.)(?!.*\.\.)[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+(?<!\.)@"
    r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
)

_domains: set[str] = set()
_mtime = 0.0
_checked = 0.0
_types: dict[str, tuple[float, str]] = {}


def refresh_list(url: str = LIST_URL, path: str = LIST_PATH, min_lines: int = 100_000) -> int:
    """Download a fresh copy next to the old one and swap it in. A short or failed download keeps the old file."""
    part = path + ".part"
    urllib.request.urlretrieve(url, part)
    with open(part, encoding="utf-8") as f:
        lines = sum(1 for line in f if line.strip() and not line.startswith("#"))
    if lines < min_lines:
        os.remove(part)
        raise RuntimeError(f"only {lines} domains in the download, keeping the current list")
    os.replace(part, path)
    return lines


def _load() -> None:
    """Read the list into a set, and again when the file on disk changes (checked once a minute)."""
    global _domains, _mtime, _checked
    if _domains and time.monotonic() - _checked < 60:
        return
    _checked = time.monotonic()
    try:
        mtime = os.path.getmtime(LIST_PATH)
    except OSError:
        return  # no list yet
    if mtime != _mtime:
        with open(LIST_PATH, encoding="utf-8") as f:
            _domains = {line.strip().rstrip(".").lower() for line in f if line.strip() and not line.startswith("#")}
        _mtime = mtime


def is_listed(domain: str) -> bool:
    """True when the domain or one of its parent domains is on the list."""
    _load()
    labels = domain.strip().rstrip(".").lower().split(".")
    return any(".".join(labels[i:]) in _domains for i in range(len(labels) - 1))


def looks_like_email(email: str) -> bool:
    at = email.rfind("@")
    return len(email) <= 254 and 1 <= at <= 64 and EMAIL.fullmatch(email) is not None


def api_type(domain: str, timeout: float = 2.0) -> str | None:
    """'temp', 'alias' or 'normal', kept for a day per domain; None when the API cannot answer.

    The type depends on the domain alone, so the API gets user@ and the domain, never the address.
    """
    hit = _types.get(domain)
    if hit and time.monotonic() - hit[0] < 86_400:
        return hit[1]
    req = urllib.request.Request(
        API_URL,
        data=json.dumps({"email": "user@" + domain}).encode(),
        headers={"Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=timeout) as res:
            kind = json.load(res).get("email_type")
    except Exception:
        return None
    if not isinstance(kind, str):
        return None
    _types[domain] = (time.monotonic(), kind)
    return kind


def check_email(value: str, timeout: float = 2.0) -> tuple[bool, str]:
    """(accept, reason): the API decides; without an answer, the offline list does."""
    email = value.strip()
    if not looks_like_email(email):
        return False, "not an email address"
    domain = email.rsplit("@", 1)[1].lower()
    kind = api_type(domain, timeout)
    if kind is None:
        # The list cannot tell a relay from a throwaway inbox, so it refuses both.
        if is_listed(domain):
            return False, "disposable domain"
        return True, "API unavailable, offline list only"
    if kind == "temp" or (kind == "alias" and not ACCEPT_RELAYS):
        return False, "disposable domain"
    return True, "relay address" if kind == "alias" else "ok"

from django import forms
from django.core.exceptions import ValidationError

from .disposable import check_email


def validate_not_disposable(value):
    accept, reason = check_email(value)
    if not accept and reason == "disposable domain":
        raise ValidationError(
            "Please use an email address you will keep. Throwaway inboxes are not accepted.",
            code="disposable_email",
        )


class SignupForm(forms.Form):
    email = forms.EmailField(max_length=254, validators=[validate_not_disposable])

Python 3.13.7 2026-10-26T00:15:10+00:00
refresh_list: 224174 domains, 3544412 bytes, 0.21 s
guard: only 2000 domains in the download, keeping the current list | file kept out: True
load into a set: 224174 domains, 597 ms, 20.9 MB held (peak 21.4 MB)
is_listed('mailinator.com') = True, 0.90 microseconds per call
is_listed('gmail.com') = False, 0.90 microseconds per call
is_listed('inbox.mailinator.com') = True, 0.99 microseconds per call
API latency, 20 calls: median 226 ms, min 157 ms, max 650 ms
check_email('test@mailinator.com') -> (False, 'disposable domain'), 272.8 ms, API calls: 1
check_email('user@inbox.mailinator.com') -> (False, 'disposable domain'), 262.6 ms, API calls: 1
check_email('test@privaterelay.appleid.com') -> (True, 'relay address'), 379.6 ms, API calls: 1
check_email(' team@ffraud.com\n') -> (True, 'ok'), 222.3 ms, API calls: 1
check_email('team@ffraud.com') -> (True, 'ok'), 0.0 ms, API calls: 0
check_email('us..er@ffraud.com') -> (False, 'not an email address'), 0.0 ms, API calls: 0
what the API received: {"email": "user@mailinator.com"} {"email": "user@inbox.mailinator.com"} {"email": "user@privaterelay.appleid.com"} {"email": "user@ffraud.com"}
check_email('test@mailinator.com', timeout=0.001) -> (False, 'disposable domain'), 34.8 ms, API calls: 1
check_email('test@privaterelay.appleid.com', timeout=0.001) -> (False, 'disposable domain'), 42.1 ms, API calls: 1
check_email('team@ffraud.com', timeout=0.001) -> (True, 'API unavailable, offline list only'), 9.6 ms, API calls: 1
check_email('test@privaterelay.appleid.com') with ACCEPT_RELAYS = False -> (False, 'disposable domain'), 197.3 ms, API calls: 1
validate_not_disposable('test@mailinator.com'): ValidationError code='disposable_email' 'Please use an email address you will keep. Throwaway inboxes are not accepted.'
validate_not_disposable('test@privaterelay.appleid.com'): passes
validate_not_disposable('team@ffraud.com'): passes
validate_not_disposable('us..er@ffraud.com'): passes
SignupForm.email kwargs: {'max_length': 254, 'validators': [<function validate_not_disposable at 0x000002736C5D7B00>]}