mail-safe

Validate, normalize, and detect disposable email addresses for Node.js.

mail-safe pulls the upstream disposable domain list from https://github.com/eramitgupta/disposable-email, caches it on disk, and performs fast lookups with sensible defaults.

Features

• Async helpers that refresh and cache domains automatically.
• Sync helpers for when you already have a domain set in memory.
• Normalization utilities that handle casing and trailing dots.
• Safe defaults with fallback to cached data if refresh fails.

Requirements

• Node.js >= 18.17 (native fetch required)
• This package is ESM only.

Installation

npm install mail-safe

Quick start

Async check (fetches and caches if needed):

import { isDisposableEmail } from "mail-safe";

const isDisposable = await isDisposableEmail("[email protected]");
console.log(isDisposable); // true

Sync check with your own domain set (no IO):

import { isDisposableEmailSync } from "mail-safe";

const domains = new Set(["mailinator.com"]);
console.log(isDisposableEmailSync("[email protected]", domains)); // true

Detailed check (returns metadata):

import { checkDisposableEmail } from "mail-safe";

const result = await checkDisposableEmail("[email protected]");
// {
//   email: "[email protected]",
//   domain: "mailinator.com",
//   matchedDomain: "mailinator.com",
//   isDisposable: true,
//   sourceUrl: "...",
//   cacheFile: "...",
//   fetchedAt: "..."
// }

API

Constants

• DEFAULT_SOURCE_URL - default upstream JSON list URL.
• DEFAULT_CACHE_FILE - default cache location on disk.
• DEFAULT_MAX_AGE_MS - default cache staleness window (24 hours).

Async helpers (cached)

• loadDisposableEmailState(options?)

  • Loads the cached snapshot or fetches a fresh one when stale.
  • Returns { fetchedAt, sourceUrl, cacheFile, domains }.
  • Falls back to the cached snapshot if refresh fails.

• refreshDisposableEmailState(options?)

  • Forces a refresh from the upstream list and overwrites the cache.
  • Returns { fetchedAt, sourceUrl, cacheFile, domains }.

• checkDisposableEmail(email, options?)

  • Returns { email, domain, matchedDomain, isDisposable, sourceUrl, cacheFile, fetchedAt }.
  • fetchedAt is null when the email is invalid and no fetch occurs.

• isDisposableEmail(email, options?)

  • Convenience boolean wrapper around checkDisposableEmail.

Sync helpers (no IO)

• isDisposableEmailSync(email, domains)

  • Fast sync check when you already have a Set of domains.

• isDisposableDomain(domain, domains)

  • Checks if a domain (including subdomains) matches a disposable entry.

• extractEmailDomain(email)

  • Normalizes and returns the domain portion of an email, or null if invalid.

Options

All async helpers accept DisposableEmailOptions:

• sourceUrl?: string - override the upstream list URL.
• cacheFile?: string - override the cache file path.
• maxAgeMs?: number - max cache age before refresh (ms).
• forceRefresh?: boolean - bypass cache even if fresh.
• signal?: AbortSignal - cancel network requests.

Cache behavior

• The first async call downloads the list and caches it on disk.
• Subsequent calls reuse the cache until it is stale (default 24h).
• If refresh fails, the last cached snapshot is used instead.
• Default cache location uses XDG on Linux, ~/Library/Caches on macOS, and %LOCALAPPDATA% (fallback to %APPDATA%) on Windows.

Error handling

• Invalid emails short-circuit without network or filesystem IO.
• Network errors surface as thrown exceptions from async helpers.
• When a refresh fails but a cached snapshot exists, the cached snapshot is used.

TypeScript

• All public functions and types are fully typed.
• JSDoc comments show up in IntelliSense for parameters and return values.

Testing

npm install
npm test

Typecheck

npm run check

Build

npm run build

Contributing

See CONTRIBUTING.md for the contribution guide and local development steps.

License

ISC - see LICENSE.