@email-utils/classifier
The API of @email-utils/classifier 1.0.0-rc.5.
Interfaces
ProviderInfo
A mailbox provider in the registry: its domains, MX patterns, and local-part rules.
Properties
canonicalDomain?
optional canonicalDomain?: string;When set, all of domains share mailboxes and keys use this one, e.g. gmail.com.
domains
domains: readonly string[];Domains the provider serves mail for, e.g. gmail.com and googlemail.com. Empty for hosted-domain providers such as Google Workspace, which only validator-dns can recognize, by MX.
dotsSignificant
dotsSignificant: boolean;Whether dots in the local part change the mailbox (false for Gmail).
hyphensSignificant
hyphensSignificant: boolean;Whether a hyphen in the local part is its own character (false for
Yandex, where my-address and my.address are one mailbox).
id
id: string;kind
kind: ProviderKind;mxPatterns
mxPatterns: readonly string[];MX host patterns that validator-dns's detectProviderByMx matches:
lowercase host names without the trailing dot. A leading *. matches
one or more labels, so *.olc.protection.outlook.com matches
hotmail-com.olc.protection.outlook.com but not
olc.protection.outlook.com itself.
name
name: string;subaddressSeparator?
optional subaddressSeparator?: string;The single character that starts a subaddress tag, e.g. '+' or '-'; absent if none.
subdomainAddressing
subdomainAddressing: boolean;Whether tag@user.<domain> delivers to user@<domain>, as on Fastmail.
It applies to the provider's own domains.
Type Aliases
ProviderId
type ProviderId = string;Stable provider identifier, e.g. 'gmail', 'google-workspace', or 'microsoft365'.
ProviderKind
type ProviderKind = "personal" | "business" | "registrar";What a provider's domains are:
personal: a mailbox service anyone can sign up for, free or paid (Gmail, Outlook.com, Fastmail). An address on one isn't tied to an organization.business: hosting for an organization's own domain (Google Workspace, Microsoft 365). These entries have nodomains; validator-dns finds them by MX.registrar: a registrar's default forwarding MX, which a domain gets before its owner sets up mail (Namecheap). Mail may be forwarded anywhere, or nowhere.
Variables
packageName
const packageName: "@email-utils/classifier" = "@email-utils/classifier";The package name, for diagnostics.
Example
import { packageName } from '@email-utils/classifier';
packageName; // => '@email-utils/classifier'Functions
getProvider()
function getProvider(email): ProviderInfo | undefined;The provider whose domains the address is on, e.g. Gmail for
ada@googlemail.com. With subdomainAddressing, one-label subdomains of
the provider's domains match too: news@ada.fastmail.com is Fastmail.
A custom domain hosted on a provider, such as a company's domain on Google
Workspace, can't be told from the domain alone, so it returns undefined;
validator-dns's detectProviderByMx finds those by MX.
Parameters
| Parameter | Type |
|---|---|
email | string | ParsedAddress |
Returns
ProviderInfo | undefined
Example
import { getProvider } from '@email-utils/classifier';
getProvider('ada@googlemail.com');
// => { id: 'gmail', canonicalDomain: 'gmail.com', subaddressSeparator: '+' }
getProvider('news@ada.fastmail.com')?.id; // => 'fastmail'
getProvider('ada@example.com'); // => undefinedThrows
TypeError when email is neither a string nor a parsed address.
isRoleAccount()
function isRoleAccount(email): boolean;Whether the address belongs to a function rather than a person:
postmaster@, noreply@, support@, and the like. The local part is
compared without case and without a + tag, so Admin+alerts@ counts.
Parameters
| Parameter | Type |
|---|---|
email | string | ParsedAddress |
Returns
boolean
Example
import { isRoleAccount } from '@email-utils/classifier';
isRoleAccount('no-reply@example.com'); // => true
isRoleAccount('Admin+alerts@example.com'); // => true
isRoleAccount('ada@example.com'); // => falseThrows
TypeError when email is neither a string nor a parsed address.
suggestCorrection()
function suggestCorrection(email): string | undefined;The address with its domain corrected, when the domain looks like a slip
for a common mailbox domain: ada@gmial.com gives ada@gmail.com, and
ada@example.con gives ada@example.com. undefined when the domain is
one the registry knows, or isn't close enough to one to guess.
Parameters
| Parameter | Type |
|---|---|
email | string | ParsedAddress |
Returns
string | undefined
Remarks
The domain is compared without case, and the suggestion has it in
lowercase; the local part is kept as written. A domain one edit from a
common one is taken for it, where swapping two neighboring letters counts
as one edit, and so does a letter typed for one on a neighboring QWERTY
key; one typed for a letter farther away counts as two. Names of three
letters or fewer, like me.com, are never guessed at. A TLD that isn't in the IANA set but is a common slip
for .com, .net, or .org is fixed on any domain but those in
defaultIgnore, which are never corrected toward. Unlike the other
lookups, a string with an unknown TLD is still read, since those are what
the TLD fix is for.
Example
import { suggestCorrection } from '@email-utils/classifier';
suggestCorrection('ada@gmial.com'); // => 'ada@gmail.com'
suggestCorrection('ada@hotmial.con'); // => 'ada@hotmail.com'
suggestCorrection('ada@gmail.com'); // => undefinedThrows
TypeError when email is neither a string nor a parsed address.