nomadic

Provider-aware email normalization and canonicalization for the browser and the server. Pure ESM, zero runtime dependencies, fully typed.

Two addresses can point to the same mailbox even when they look different. [email protected] and [email protected] both deliver to the same Gmail inbox. nomadic resolves any address to a single canonical form using per-provider rules, and lets you configure rules for your own providers.

Use it to deduplicate sign-ups, prevent disposable/aliased re-registration, compare addresses for equality, or simply clean user input.

Table of contents

• Installation
• Quick start
• Why canonicalization?
• API reference
  • normalizeEmail
  • normalizeEmailDetailed
  • isSameEmail
  • getEmailProvider
  • DEFAULT_PROVIDERS
• Built-in providers
• Configuration
  • Add your own provider
  • Override a built-in provider
  • Replace all providers
  • A default rule for every domain
  • Options reference
• Recipes
• Edge cases & guarantees
• Limitations
• Development
• License

Installation

npm install @grml/nomadic

nomadic ships as ESM ("type": "module"). It runs in modern browsers and in Node 18+, and has no runtime dependencies.

Quick start

import { normalizeEmail, isSameEmail, getEmailProvider } from "@grml/nomadic";

normalizeEmail("[email protected]"); // "[email protected]"
normalizeEmail("[email protected]");          // "[email protected]" (dots kept)
normalizeEmail("[email protected]");            // "[email protected]"  (Yahoo uses '-')
normalizeEmail("[email protected]");                   // "[email protected]" (unknown domain: conservative)

isSameEmail("[email protected]", "[email protected]");   // true
getEmailProvider("[email protected]");                  // "microsoft"

Why canonicalization?

Mail providers apply their own rules to decide which mailbox an address reaches:

| Behavior | Example | Same mailbox? | | ------------------------------ | ---------------------------------------------------- | ------------- | | Plus/sub-address tagging | [email protected] -> [email protected] | yes | | Dot-insensitivity (Gmail) | [email protected] -> [email protected] | yes | | Alias domains (Gmail) | [email protected] -> [email protected] | yes | | Case-insensitivity | [email protected] -> [email protected] | yes |

nomadic applies the right rules for each provider and returns one canonical string, so equal mailboxes compare equal.

API reference

Every function takes an optional options object (see Configuration).

normalizeEmail(email, options?) => string

Returns the canonical form of email. Throws TypeError if email is not a string. Malformed input (no @, empty local/domain) is returned trimmed and unchanged.

normalizeEmail("  [email protected] "); // "[email protected]"

normalizeEmailDetailed(email, options?) => NormalizedEmail

Like normalizeEmail, but returns the full breakdown:

normalizeEmailDetailed("[email protected]");
// {
//   normalized: "[email protected]",
//   local: "johndoe",
//   domain: "gmail.com",
//   providerId: "gmail",   // null for unknown domains
//   subaddress: "promo",   // the stripped tag, or null
//   valid: true,           // does it look like a syntactically valid address?
// }

isSameEmail(a, b, options?) => boolean

true when a and b normalize to the same canonical address (i.e. deliver to the same mailbox under the configured rules).

isSameEmail("[email protected]", "[email protected]"); // true
isSameEmail("[email protected]", "[email protected]");              // false (distinct mailboxes)

getEmailProvider(email, options?) => string | null

Returns the id of the provider that owns the address's domain, or null if no provider matches (or the input is not a valid address). Never throws.

getEmailProvider("[email protected]");   // "proton"
getEmailProvider("[email protected]"); // null

DEFAULT_PROVIDERS

The read-only array of built-in ProviderRule objects, exported so you can inspect or build on top of it.

import { DEFAULT_PROVIDERS } from "@grml/nomadic";
DEFAULT_PROVIDERS.flatMap((p) => p.domains); // every recognized domain

Built-in providers

| id | Separator | Removes dots | Alias domain | Notable domains | | ----------- | :-------: | :----------: | ------------ | ---------------------------------------- | | gmail | + | yes | gmail.com | gmail.com, googlemail.com | | microsoft | + | no | none | outlook.*, hotmail.*, live.*, msn.com | | yahoo | - | no | none | yahoo.*, ymail.com, rocketmail.com | | icloud | + | no | none | icloud.com, me.com, mac.com | | fastmail | + | no | none | fastmail.com, fastmail.fm | | proton | + | no | none | protonmail.com, proton.me, pm.me | | yandex | + | no | none | yandex.*, ya.ru | | zoho | + | no | none | zoho.com, zohomail.com, zoho.eu | | mailfence | + | no | none | mailfence.com | | runbox | + | no | none | runbox.com | | pobox | + | no | none | pobox.com | | tutanota | + | no | none | tuta.com, tutanota.com, keemail.me | | posteo | + | no | none | posteo.de, posteo.net | | mailbox | + | no | none | mailbox.org | | aol | none | no | none | aol.com, aim.com |

All built-in providers lowercase the local part (they are case-insensitive in practice).

Unknown domains get a conservative treatment: the domain is lowercased and the local part is left untouched. The email spec (RFC 5321) permits case-sensitive local parts, and distinct mailboxes must not be merged by accident. Opt into more aggressive behavior with defaultRule.

Configuration

Add your own provider

Pass extra rules via providers. They are matched by domain and take precedence over the built-ins.

import { normalizeEmail, type ProviderRule } from "@grml/nomadic";

const corporate: ProviderRule = {
  id: "corp",
  domains: ["mycompany.com", "mycompany.co"],
  canonicalDomain: "mycompany.com", // collapse the alias
  lowercaseLocal: true,
  removeDots: true,
  subaddressSeparators: ["+"],
};

normalizeEmail("[email protected]", { providers: [corporate] });
// "[email protected]"

Override a built-in provider

A user provider that lists an existing domain wins, letting you change behavior per domain:

// Treat gmail.com strictly: keep dots, don't collapse googlemail, just lowercase.
normalizeEmail("[email protected]", {
  providers: [{ id: "gmail-strict", domains: ["gmail.com"], lowercaseLocal: true }],
});
// "[email protected]"

Replace all providers

Ignore the built-ins entirely and use only your own:

normalizeEmail("[email protected]", {
  replaceDefaultProviders: true,
  providers: [{ id: "only", domains: ["only.com"], subaddressSeparators: ["+"] }],
});
// gmail.com now matches nothing -> conservative default

A default rule for every domain

Apply rules to domains that match no provider, e.g. strip +tags everywhere:

normalizeEmail("[email protected]", {
  defaultRule: { lowercaseLocal: true, subaddressSeparators: ["+"] },
});
// "[email protected]"

A defaultRule never overrides a matched provider (Yahoo still uses -, etc.).

Options reference

interface NormalizeOptions {
  providers?: ProviderRule[];        // extra/override rules (win by domain)
  replaceDefaultProviders?: boolean; // ignore the built-ins entirely (default: false)
  defaultRule?: DefaultRule;         // rule for unmatched domains
  lowercaseDomain?: boolean;         // default: true
}

interface ProviderRule {
  id: string;                        // stable identifier, e.g. "gmail"
  domains: string[];                 // domains this rule applies to (case-insensitive)
  canonicalDomain?: string;          // collapse all matched domains to this one
  lowercaseLocal?: boolean;          // lowercase the local part
  removeDots?: boolean;              // strip dots from the local part (Gmail)
  subaddressSeparators?: string[];   // tag separators, e.g. ["+"] or ["-"]
}

// DefaultRule is a ProviderRule without `id`, `domains`, or `canonicalDomain`.

Recipes

Deduplicate a list of addresses

import { normalizeEmail } from "@grml/nomadic";

const unique = [...new Map(
  rawEmails.map((e) => [normalizeEmail(e), e]),
).values()];

Block re-registration with an aliased address

import { isSameEmail } from "@grml/nomadic";

const alreadyUsed = existingUsers.some((u) => isSameEmail(u.email, signup.email));

Store a canonical key alongside the original

const { normalized, valid } = normalizeEmailDetailed(input);
if (!valid) throw new Error("Invalid email");
await db.users.insert({ email: input, emailKey: normalized });

Edge cases & guarantees

• The address is split on the last @.
• Quoted local parts ("a..b"@x.com) are preserved verbatim, with no dot/tag transforms.
• A separator at index 0 ([email protected]) is ignored; stripping it would empty the local part.
• Only the first separator is used as the cut point (a+b+c becomes a).
• Domains are lowercased by default; the matched provider's canonicalDomain (if any) wins.
• Non-string input throws TypeError. Malformed input is returned unchanged with valid: false.

Limitations

• valid is a lightweight syntactic check, not full RFC 5322 validation or MX verification.
• Provider rules reflect widely-documented behavior at the time of writing; providers can change. Everything is overridable via options.
• Fastmail-style subdomain addressing ([email protected]) is not resolved, because it depends on the account's domain layout.

Development

npm install      # install dependencies
npm run build    # compile TypeScript to dist/ (tsc)
npm test         # build output is run as node scripts (dist/tests/*.js)

Tests live in tests/ as standalone scripts and run against the compiled output. CI (.github/workflows/ci.yml) builds and runs them on every push/PR.

License

ISC