@email-utils/sanitizer

InterfacesCopy Anchor Link

NormalizedEmailCopy Anchor Link

The forms of one address, as normalizeEmail returns them.

Extended byCopy Anchor Link

• ValidSanitizerEntry

PropertiesCopy Anchor Link

addressCopy Anchor Link

address: string;

The address to email: local-part case, dots, subaddress tag, and comments kept. Valid in RFC 5322 headers such as To:.

envelopeCopy Anchor Link

envelope: string;

address without comments: valid in the SMTP envelope (RFC 5321).

keyCopy Anchor Link

key: string;

Uniqueness key: two inputs that reach the same mailbox get the same key. Store and compare it; never send mail to it. Normalizing it again, with the same options, gives it back, unless a domain alias lengthened it past a tiny syntax.maxLength.

provider?Copy Anchor Link

optional provider?: string;

The provider whose rules built the key: the provider option, or detected from the domain.

NormalizeOptionsCopy Anchor Link

Options for normalizeEmail and createSanitizer.

PropertiesCopy Anchor Link

provider?Copy Anchor Link

optional provider?: string;

The provider when it's known from elsewhere, usually validator-dns's detectProviderByMx for a custom domain. Takes precedence over detection from the domain. An ID the registry doesn't know is treated as no provider.

providerRules?Copy Anchor Link

optional providerRules?: boolean;

Key only: apply the provider's rules.

Default ValueCopy Anchor Link

true

removePeriods?Copy Anchor Link

optional removePeriods?: boolean;

Key only: force dot removal regardless of provider.

Default ValueCopy Anchor Link

provider-driven

removeSubaddress?Copy Anchor Link

optional removeSubaddress?: boolean;

Key only: force subaddress removal regardless of provider.

Default ValueCopy Anchor Link

provider-driven

subaddressSeparator?Copy Anchor Link

optional subaddressSeparator?: string;

Key only: the separator removeSubaddress uses when the provider has none.

Default ValueCopy Anchor Link

'+'

syntax?Copy Anchor Link

optional syntax?: SyntaxOptions;

How the input is parsed.

Default ValueCopy Anchor Link

the validator-syntax practical preset

SanitizerCopy Anchor Link

normalizeEmail with options bound.

MethodsCopy Anchor Link

normalize()Copy Anchor Link

normalize(email): Result<NormalizedEmail>;

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Result<NormalizedEmail>

Type AliasesCopy Anchor Link

ReasonCodeCopy Anchor Link

type ReasonCode = "sanitizer.address.unparsable";

The sanitizer.* codes from the reason-code catalogue (https://email-utils.github.io/meta/docs/reference/reason-codes#sanitizer).

ResultCopy Anchor Link

type Result<T> = 
  | {
  ok: true;
  value: T;
}
  | {
  message?: string;
  ok: false;
  reason: ReasonCode;
};

A normalization result: the value on success, or why there was nothing to normalize. Branch on reason, never on message, which isn't semver-stable.

Type ParametersCopy Anchor Link

FunctionsCopy Anchor Link

createSanitizer()Copy Anchor Link

function createSanitizer(options?): Sanitizer;

Binds options once, checking them and looking up the provider up front, and returns normalizeEmail with them applied.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Sanitizer

RemarksCopy Anchor Link

As with normalizeEmail, a string longer than the syntax options' maxLength (512 by default) fails before it's trimmed, so surrounding whitespace counts toward it.

ExampleCopy Anchor Link

import { createSanitizer } from '@email-utils/sanitizer';

const sanitize = createSanitizer({ syntax: { allowComments: true } });
sanitize.normalize('Ada.Lovelace+news(work)@googlemail.com');
// => {
//   ok: true,
//   value: {
//     key: 'adalovelace@gmail.com',
//     address: 'Ada.Lovelace+news(work)@googlemail.com',
//     envelope: 'Ada.Lovelace+news@googlemail.com',
//   },
// }

// Malformed options throw here, not on every call.
createSanitizer({ subaddressSeparator: '--' }); // => throws TypeError

ThrowsCopy Anchor Link

TypeError when options are malformed or name an option that doesn't exist.

normalizeEmail()Copy Anchor Link

function normalizeEmail(email, options?): Result<NormalizedEmail>;

Normalizes email into a uniqueness key, the address to email, and its comment-free envelope, all from one parse.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Result<NormalizedEmail>

RemarksCopy Anchor Link

key collapses every spelling that reaches the same mailbox, using the provider's rules for domain aliases, subdomain addressing, dots, hyphens, and subaddress tags; on a domain with no known provider, dots and tags are kept. key is itself an address the same options parse, and normalizes to itself, unless a domain alias lengthens it past a tiny maxLength in the syntax options; the default of 512 is long enough. address and envelope only trim the input and lowercase the domain. A string is trimmed of spaces, tabs, CRs, and LFs and then parsed with the syntax options; a parsed address from validator-syntax's parseAddress is used as is. A string longer than the syntax options' maxLength (512 by default) fails before it's trimmed, so surrounding whitespace counts toward it.

ExampleCopy Anchor Link

import { normalizeEmail } from '@email-utils/sanitizer';

normalizeEmail('Ada.Lovelace+news@GMAIL.com');
// => {
//   ok: true,
//   value: {
//     key: 'adalovelace@gmail.com',
//     address: 'Ada.Lovelace+news@gmail.com',
//     provider: 'gmail',
//   },
// }

normalizeEmail('ada@');
// => { ok: false, reason: 'sanitizer.address.unparsable' }

// Surrounding whitespace counts toward the 512-character `maxLength`.
normalizeEmail(`${' '.repeat(500)}ada@example.com`);
// => { ok: false, reason: 'sanitizer.address.unparsable' }

// A custom domain's provider comes from its MX records.
normalizeEmail('A.da+news@example.com', { provider: 'google-workspace' });
// => { ok: true, value: { key: 'a.da@example.com' } }

ThrowsCopy Anchor Link

TypeError when email is neither a string nor a parsed address, or options are malformed or name an option that doesn't exist.