mail-safe

Validate, normalise & detect disposable email addresses

Small Node library that caches and checks disposable email domains from the upstream blocklist (https://github.com/eramitgupta/disposable-email).

Installation

npm install mail-safe

Quick start

Importing and checking an email (async — will fetch & cache if needed):

import { isDisposableEmail } from 'mail-safe';

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

Synchronous check against an in-memory set (fast, no IO):

import { isDisposableEmailSync } from 'mail-safe';

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

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 a detailed result: { email, domain, matchedDomain, isDisposable, sourceUrl, cacheFile, fetchedAt }.

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.

TypeScript

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

Testing

Run the test suite (Jest + ts-jest):

npm install
npm test

Build

npm run build

Publishing

The package is prepared for publishing with a prepublish step that builds the TypeScript sources. See npm publish for details — if you use automation tokens, store them in CI secrets and never commit them to the repo.

Contributing

See CONTRIBUTING.md for the contribution guide and running tests locally.

License

ISC — see LICENSE.