free-email-domains

free-email-domains is a zero-dependency npm package that exports a plain array of known free and disposable email domains — gmail.com, yahoo.com, and hundreds of throwaway/temp-mail providers — as a single JSON file you can require or import directly. It’s built for one job: letting signup forms, CRM pipelines, and lead-scoring systems tell a real corporate email apart from a free consumer inbox or disposable address with a single Array.includes() check.

The domain list isn’t maintained by hand. A postinstall script pulls from three independent sources — HubSpot’s blocked-domains list, Castle’s disposable-email-domains list, and the community-run disposable-email-domains blocklist — merges them with a small set of manually curated regional providers (Japanese carriers, Korean webmail, Norwegian ISPs), dedupes, sorts, and writes the result back to domains.json. A daily GitHub Actions cron job reruns that script and commits the refreshed list, and near-daily patch releases push it to npm automatically, so consumers get an up-to-date blocklist without running any aggregation logic themselves.

What You Get

• A plain JSON array (domains.json) of thousands of known free/disposable email domains, requirable with zero runtime dependencies.
• TypeScript type declarations (index.d.ts) so the array is typed out of the box for import-style consumers.
• The generation script itself (scripts/postinstall.mjs), so you can re-run or fork the aggregation logic instead of trusting only the shipped snapshot.
• Near-daily patch releases as upstream blocklists change, so pinning a caret range keeps the list continuously refreshed without manual upkeep.

Common Use Cases

• Rejecting free/consumer email addresses (Gmail, Yahoo, Outlook) on signup forms that require a work email.
• Filtering disposable/temp-mail domains out of newsletter or trial signups to cut spam and abuse.
• Scoring inbound leads in a CRM by whether the submitted email domain is a real company domain or a free provider.
• Pre-validating email domains client- or server-side before an expensive downstream check, like an SMTP handshake or a verification API call.

Under The Hood

Architecture free-email-domains ships as close to the simplest possible architecture as a package can get: a single JSON file (domains.json) is the canonical data artifact, required directly by the package’s main entry (domains.js: module.exports = require(’./domains.json’)), with index.d.ts providing a matching type export for import-style consumers. Generation is fully decoupled from consumption — scripts/postinstall.mjs is the only place with any logic, fetching three independent domain-list sources, sanitizing and merging them with a small hardcoded array of regional providers, then deduping and sorting the result before writing it back to domains.json. There’s no class hierarchy, no configuration surface, and no dependency injection, because the entire contract with consumers is “require this file and get back a flat array of strings” — the only thing that could break downstream is a change in that shape, which the maintainers have evidently avoided across more than a hundred releases.

Tech Stack The runtime footprint is intentionally zero — dependencies: {} in package.json means importing the package pulls in nothing beyond the JSON/CJS shim itself. All of the real work lives in devDependencies and CI: scripts/postinstall.mjs uses Node’s native fetch (requiring Node >=18, enforced via engines) to pull HubSpot’s blocked-domains CSV, Castle’s disposable-email-domains list, and the community disposable-email-domains blocklist, merging them via a Set. Tooling around that single script is comparatively heavy for a package this size: standard for linting, mocha/should for tests, commitlint/simple-git-hooks/nano-staged for commit hygiene, and standard-version plus ci-publish/github-generate-release to automate versioning and npm publishing end to end. Four GitHub Actions workflows (test, pull_request, a daily cron, and a release pipeline with a healthcheck ping) run this without human involvement — the cron job reruns postinstall daily, commits the regenerated domains.json if it changed, and the release workflow publishes a new patch version automatically.

Code Quality Test coverage is minimal: test/index.js contains exactly one assertion (that domains.includes(‘gmail.com’) is true), with no tests for the aggregation logic in postinstall.mjs and no coverage of case-sensitivity, subdomain handling, or malformed source responses — the script does guard against receiving an HTML error page instead of a domain list, which is the one defensive check present in the codebase. Linting is enforced via standard (zero-config style rules) in both the pretest hook and a pre-commit hook via nano-staged, and commit messages are validated by commitlint against the conventional-commits spec. There’s no TypeScript in the source itself; type safety for consumers is limited to the single hand-written index.d.ts re-export. CI is genuinely thorough for a package this size (a dedicated test workflow, a PR workflow, and a release workflow that reruns tests before publishing), which offsets some of the risk from the thin test suite by catching install/require regressions on every push.

API Design The public API is a single value: a plain array of lowercase domain strings, importable via require(‘free-email-domains’) (CommonJS) or import with the bundled index.d.ts declaration — there’s no configuration object, no initialization step, and no async setup, so integrating it is a one-line Array.includes() call, exactly as shown in the README’s only usage example. That minimalism is also the main developer-experience gap: there’s no exported helper for common needs like case-insensitive lookup, subdomain-aware matching, or distinguishing “free” providers from “disposable” ones (the package doesn’t separate those two categories despite the name implying both), so consumers have to write that logic themselves. Documentation is limited to a short README (install/usage/update-data sections) with no dedicated docs site or inline JSDoc on the exported value, though the CHANGELOG is kept current release over release.