disposable-email-domains

disposable-email-domains is a continuously updated list of domains used by temporary and throwaway email services, packaged as a Python module for quick disposable-email detection. The blocklist is community-maintained, with a scheduled GitHub Action fetching new domains daily from known disposable-email providers and a validation script (verify.py) enforcing formatting and Public Suffix List correctness on every push and pull request.

Beyond the PyPI package, the underlying disposable_email_blocklist.conf file is consumed directly by ports and snippets in Go, PHP, Ruby, Node.js, Java, Kotlin, C#, and other ecosystems, making it a de facto standard reference list. PyPI itself uses this list, alongside an internal one, to block disposable-domain signups for PyPI accounts.

What You Get

• Ready-to-import blocklist - from disposable_email_domains import blocklist gives a Python set of thousands of known disposable domains for instant in checks.
• Daily automated updates - A scheduled GitHub Action scrapes known disposable-email provider pages and opens a PR with newly discovered domains every day.
• Format and public-suffix validation - verify.py checks every domain against the Public Suffix List and blocklist formatting rules on every push and PR, with --fix to auto-correct issues.
• Cross-ecosystem reference file - The raw .conf file is consumed directly by ports and code snippets in Go, PHP, Ruby, Node.js, Java, Kotlin, C#, and more, beyond the PyPI package itself.

Common Use Cases

• Signup form validation - A SaaS app checks a new user’s email domain against the blocklist during registration to reject throwaway addresses.
• Fraud and abuse prevention - A platform’s trust-and-safety team filters disposable-domain signups to reduce fake-account creation and spam.
• Lead quality scoring - A marketing or sales tool flags leads that signed up with a disposable email as lower-quality or unverified.
• Public registry protection - Package and account registries (as PyPI itself does) block registration from known disposable-email domains to curb abuse.

Under The Hood

Architecture The repo isn’t a conventional application codebase but a data-maintenance pipeline centered on one flat artifact, disposable_email_blocklist.conf. A handful of top-level scripts do all the work: fetch_domains.py defines source-specific DomainFetcher subclasses (e.g. a Yopmail fetcher) that scrape known disposable-email listing pages and merge newly found domains into the conf file; verify.py implements the validation/auto-fix pass against the Public Suffix List and a local override file; and scripts/discover_new_domains.py / scripts/generate_stats.py support the daily and weekly GitHub Actions workflows (fetch-domains.yml, maintain.yml, pr.yml) that open automated pull requests. There is no runtime application logic beyond this pipeline — the importable PyPI wheel itself is packaged separately by a co-maintainer and simply wraps the conf file into a Python set.

Tech Stack The pipeline targets Python 3.11 in CI; requirements.txt pins publicsuffixlist, requests, and beautifulsoup4 for PSL validation, HTTP fetching, and HTML scraping respectively. There is no packaging configuration in this repository (no setup.py or pyproject.toml) since the PyPI distribution is built and published from a separate wrapper maintained by a co-maintainer. CI/CD runs entirely on GitHub Actions (actions/checkout, actions/setup-python, peter-evans/create-pull-request) with no database, ORM, or web framework involved — just scripts operating on a flat text file.

Code Quality No unit test suite exists in this repo; pr.yml runs verify.py as the only integrity check on push and PR, functioning as an implicit smoke test rather than a formal test framework. Type hints appear inconsistently (present in fetch_domains.py signatures such as Set[str], largely absent in verify.py), there is no linter/formatter configuration checked in, and error handling around network calls (PSL download, domain-source fetches) is minimal with no retry or backoff logic. Stated explicitly: this project has no automated test suite in the conventional sense.

API Design The public surface is about as minimal as it gets: from disposable_email_domains import blocklist returns a plain Python set[str], so integration is a single import and an in check with no configuration or client setup. This zero-ceremony design is the package’s main developer-experience strength, at the cost of no built-in domain-parsing helper — callers must split the email and walk subdomain levels themselves, as the README’s per-language snippets all demonstrate. Documentation lives entirely in the README rather than dedicated docs, but it is unusually thorough, with worked examples in nine different languages.