fakeout

Catch disposable emails before they catch you.

A tiny, zero-dependency library that detects disposable (burner) email domains. The blocklist auto-updates daily — no manual maintenance required.

Install · Usage · API · How it works

---

Why?

Disposable email services like Mailinator, Guerrilla Mail, and thousands of others let users sign up with throwaway addresses. This means fake accounts, abused trials, and wasted resources. fakeout lets you detect them with a single function call.

• 5,000+ domains tracked and growing
• Zero dependencies — just a Set lookup
• Auto-updated — new domains added daily via CI
• TypeScript-first — full type safety and JSDoc

Install

# npm
npm install fakeout

# pnpm
pnpm add fakeout

# yarn
yarn add fakeout

Requires Node.js 18+

Usage

import { isDisposableEmail, isDisposableDomain, getDisposableDomains } from "fakeout";

// Check a full email address
isDisposableEmail("[email protected]");  // true
isDisposableEmail("[email protected]");       // false
isDisposableEmail("not-an-email");         // false (invalid → false)

// Check a bare domain
isDisposableDomain("guerrillamail.com");   // true
isDisposableDomain("outlook.com");         // false

// Get the full list
const domains = getDisposableDomains();    // string[] — sorted, ~5000+ entries

Common patterns

Express middleware:

import { isDisposableEmail } from "fakeout";

app.post("/signup", (req, res) => {
  if (isDisposableEmail(req.body.email)) {
    return res.status(422).json({ error: "Disposable emails are not allowed" });
  }
  // proceed with signup...
});

Form validation:

import { isDisposableEmail } from "fakeout";

function validateEmail(email: string): string | null {
  if (isDisposableEmail(email)) {
    return "Please use a permanent email address";
  }
  return null;
}

API

isDisposableEmail(email: string): boolean

Checks if an email address belongs to a known disposable provider.

Input	Output
"[email protected]"	true
"[email protected]"	false
"bad-input"	false

Returns false for invalid emails rather than throwing.

isDisposableDomain(domain: string): boolean

Checks if a bare domain is in the blocklist. Handles uppercase and extra whitespace.

Input	Output
"guerrillamail.com"	true
" YOPMAIL.COM "	true
"gmail.com"	false

getDisposableDomains(): string[]

Returns a sorted array of all known disposable domains. Each call returns a fresh copy, so mutations won't affect the internal dataset.

How it works

                    ┌─────────────────────────┐
                    │  Upstream blocklist      │
                    │  (disposable-email-      │
                    │   domains/disposable-    │
                    │   email-domains)         │
                    └────────────┬────────────┘
                                 │ daily cron
                                 ▼
                    ┌─────────────────────────┐
                    │  sync-domains script    │
                    │  fetch → clean → hash   │
                    │  → compare → generate   │
                    └────────────┬────────────┘
                                 │ if changed
                                 ▼
                    ┌─────────────────────────┐
                    │  semantic-release       │
                    │  patch bump → publish   │
                    │  to npm                 │
                    └─────────────────────────┘

1. A GitHub Actions cron job runs daily
2. It fetches the latest domain list from upstream
3. If the list changed (SHA-256 comparison), tests run and a new patch version is auto-published to npm
4. If nothing changed, the job exits silently

The domain list is compiled into a ReadonlySet<string> at build time — zero file I/O at runtime, just a fast hash lookup.

Credits

The disposable domain dataset is sourced from the community-maintained disposable-email-domains project. Huge thanks to all its contributors for keeping the list comprehensive and up to date.

Contributing

Contributions are welcome! If you find a domain that should be blocked:

• For new disposable domains, please submit them upstream to disposable-email-domains — they'll be picked up automatically on the next sync
• For bugs or feature requests in fakeout itself, open an issue

License

MIT — use it however you like.