disposable-email-domains: choosing the right domain list for a signup filter

A repository of data points, with no library to install

The disposable/disposable-email-domains project does one job: it publishes lists of mail hosts that exist mainly to hand out throwaway addresses. The repository description calls it a daily updated repository for the parent disposable project, and the README immediately redirects readers to that main repository for anything beyond the lists themselves. There is no package to add to a dependency file, no service to stand up, and no configuration schema to learn. The top-level entries are data files, a lookup page, a couple of generator scripts and a submodule pointing at the disposable repository.

That shape matters for adoption decisions. A signup filter that wants to reject temporary mail does not need to call an API, refresh a token or handle a rate limit. It needs a list it can put in a set, or a JSON object it can turn into one. The list here is published in both formats, so a small service written in any language can consume it over plain HTTP without gaining a runtime dependency. The downside of that simplicity is that the project answers exactly one question, and it answers it well. Whether a domain hosts a disposable mailbox is all you get. Reputation, age, ownership, volume and abuse history are not part of the answer, and treating the list as a broader risk signal is a mistake.

Seven published list pairs, and one legacy file

The naming is systematic once you see the pattern, and picking the wrong file is the most common way to misuse this project. The generic pair, domains.txt and domains.json, holds every known disposable domain. The domains_mx pair holds only hosts with validated DNS, described in the README as a valid MX or A record, which is what you want when a stale entry pointing at a dead host would block a real user. The domains_sha1 pair is labelled List of SHA1 and carries the same kind of entries in a hashed form.

Beyond those sit the strict pair, the strict MX pair, the strict SHA1 pair and the forwarding pair, each available as TXT and JSON, so seven pairs in total. A domains_legacy.txt file and two source map files, domains_source_map.txt and domains_strict_source_map.txt, also sit at the top level. The source maps are the reason a disputed entry can be settled rather than argued about, and the forwarding JSON variant is richer than the others: for forwarding hosts it carries the provider name, type and signup verification, while disposable entries list the contributing sources. If you are matching against existing addresses, the metadata is more useful than the bare name, since a domain flagged as an aliasing service and a domain flagged as a trash mail host call for different responses.

The strict list treats freemail as disposable

The strict lists are the option most likely to cause support tickets. The README states that they contain all disposable domains plus legitimate mail providers that allow signup without identity verification, naming alias and forwarding services and freemail with CAPTCHA-only signup such as outlook.com and hotmail.com. Membership is derived from mailservices.json in the disposable static lists and from greylist.txt in the main repository. In other words, the strict variant answers a broader question than you asked, and it answers it in a way that will block a large share of real users who simply signed up through an ordinary consumer mailbox.

The forwarding list is the middle path, and it exists because of a specific refactor. The README says the forwarding list matches what the strict list covered before the 2025-10 mailservices refactor: all disposable domains plus alias and forwarding services such as SimpleLogin, Firefox Relay and Apple Hide My Email, but no freemail mailbox providers. If your policy is to block temporary addresses while still accepting gmail.com or outlook.com signups, this is the file that matches the policy. The project is explicit that if you only want disposable providers, domains.txt is the right answer, and the difference between these two files is large enough that a mistaken choice shows up as a sudden drop in signup conversion rather than a subtle bias.

Autogenerated files make pull requests pointless

Contributing to this repository is a different exercise from contributing to a normal project. The README states that the domain lists are autogenerated and that pull requests editing them directly will be overwritten. Adding or removing a domain means opening an issue or submitting a pull request in the main disposable repository instead, and the same applies to false positives: if your domain is listed and is not actually used for temporary email, the documented route is an issue in the main repository. The top-level file list explains the mechanics, with a disposable submodule, a .gitmodules file, an update.sh script and a generate-cache.py script sitting alongside the generated outputs.

Practically, this means the repository is a build output with a review process attached somewhere else. Your fork is a snapshot, not a contribution. If you want to remove a domain for your own filtering logic, do it in your own code with an exception list rather than by editing domains.txt, because the next regeneration will revert it and any other consumer of the fork will be confused. The same rule applies to additions. Trying to add a domain locally produces a file that differs from upstream for reasons nobody can audit, which is a poor trade for the one or two entries you needed.

The lookup form is the only per-domain record view

When a user reports that a legitimate address was rejected, you need evidence, not opinion. The README points to a lookup form hosted at disposable.github.io/disposable-email-domains/lookup, described as the way to check whether a domain is listed and to check the source for the record. A lookup.md file exists at the top level of the repository, which is the page backing that form.

This matters for a reason the bulk lists cannot serve. domains.txt tells you that a domain is present. It does not tell you why, which list tier it came from, or which source contributed it. The JSON variants come closer, since the forwarding JSON maps each domain to metadata and disposable entries list their contributing sources, but that is still a machine oriented view of a single record. The lookup form is the human facing version of the same data and is the right tool for support tickets and for auditing a rule you are about to ship. Its presence also tells you something about the project: the lists are treated as claims that can be contested, and the project has invested in a way for people to contest them.

Fetching the lists from disposable.github.io

There is no installation step to document, because there is nothing to install. The README points readers to the main repository for further information, and every list is published as a file served from the project's GitHub Pages site under the disposable.github.io/disposable-email-domains path. A plain text variant and a JSON variant exist for each tier, which means the smallest useful integration is a scheduled fetch of the generic JSON file and a lookup of the host part of each address.

https://disposable.github.io/disposable-email-domains/domains.json

That fetch is a snapshot of the list at the moment it ran, and the README describes the repository as daily updated, with the last push recorded on 2026-10-20. That cadence is useful for a filter, because a domain that starts handing out throwaway mail today is usually listed within days, but it is also a warning. The content changes underneath you without a version marker, the repository has no GitHub releases, and there is no changelog to diff. If you cache the list in memory and refresh it once a day, an unbounded growth in list size is possible over time, and if you make decisions on the raw file without keeping your own copy, you cannot explain later why a given address was blocked on a given day.

No releases means no versioned artifact to pin

The repository publishes no GitHub releases, so there is no tag to pin, no version string to log, and no upgrade note to read. The last push was on 2026-10-20, which tells you the project is being worked on, and the description calls the dataset daily updated, so the data is expected to change under you. That combination is fine for a filter and awkward for anything that needs reproducibility, a compliance record or a repeatable test fixture.

The SHA1 file is worth a note here. The README labels it a list of SHA1 and offers no further explanation of what is hashed or how the values are derived, and the metadata in the JSON variants is documented only for the forwarding list. If your plan depends on storing a stable identifier per domain, verify that assumption against the lookup form and the source map files before you build on it, because the repository does not document it.

The practical pattern that works is to keep a dated copy of the file you consume inside your own system, and to record which list tier and which date were in force for each decision you recorded. The upstream project is a good source of current data; it is not an audit log.

Editorial conclusion

Adopt this repository when you run signup or lead-capture filters that need to recognise throwaway mail providers, and pull domains.json rather than the strict or forwarding variants so that ordinary freemail signups keep working. Do not adopt it as a fraud oracle, a reputation service or a domain intelligence source, because it answers only one narrow question and changes without versioned releases. Before wiring it into a production filter, pin a snapshot of domains.json to your own storage, check the lookup form for a specific domain you already have trouble with, and confirm that the domains_forwarding list fits your policy on aliasing services.

Frequently asked questions

Official sources

1. disposable/disposable-email-domains on GitHub
2. Issues
3. License: MIT
4. README