Registry / communication / email-addresses

email-addresses

library5.0.0jsnpmunverified

email-addresses is a JavaScript/TypeScript library designed for parsing email addresses strictly according to RFC 5322. At version 5.0.0, this package provides functions to extract display names, addresses, local parts, and domains from email strings, even supporting complex forms like `"Bob Example" <bob@example.com>`. Unlike regular expression-based solutions, it uses a recursive descent parser that maps directly to RFC 5322 productions, ensuring robust and spec-compliant parsing. It explicitly states that it does *not* perform RFC 5321 validation (which involves checking for deliverability), focusing solely on the grammatical correctness defined by RFC 5322. The library also supports RFC 6532 for Unicode email addresses and offers options for strictness, partial parsing, and custom address list separators. It is actively maintained and ships with TypeScript types, facilitating its use in modern JavaScript and TypeScript projects.

communication serialization

npm install email-addresses

github ↗package ↗

INSTALL

IMPORT

SIG · EMAIL-ADDRESSES

email-addresses

communicationjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

emailAddresses

✓ import emailAddresses from 'email-addresses';

✗ const emailAddresses = require('email-addresses');

The default export is a callable function (`parse5322`) for parsing general address lists or single addresses, and also serves as an object holding named parsing utilities.

parseOneAddress

✓ import { parseOneAddress } from 'email-addresses';

✗ const { parseOneAddress } = require('email-addresses');

This named export is specifically for parsing a single email address.

parseAddressList

✓ import { parseAddressList } from 'email-addresses';

✗ const { parseAddressList } = require('email-addresses');

This named export is designed for parsing a comma-separated list of email addresses.

Any Parse Option

✓ import emailAddresses from 'email-addresses'; emailAddresses({ input: 'test@example.com', rfc6532: true });

✗ import { parseOneAddress } from 'email-addresses'; parseOneAddress('test@example.com', { rfc6532: true });

Options like `rfc6532` must be passed within an options object when calling the main `emailAddresses` function, or `parseOneAddress`, `parseAddressList` if they support options (which they do by default).

Demonstrates parsing single and multiple email addresses, accessing structured address data (name, address, local, domain), and retrieving the Abstract Syntax Tree (AST) for detailed parsing insights. Also shows behavior for invalid input.

import emailAddresses from 'email-addresses'; // Parse a single email address with a display name const singleAddress = '"Jack Bowman" <jack@fogcreek.com>'; const parsedSingle = emailAddresses.parseOneAddress(singleAddress); if (parsedSingle) { console.log('Parsed Single Address:'); console.log(` Name: ${parsedSingle.name}`); console.log(` Address: ${parsedSingle.address}`); console.log(` Local Part: ${parsedSingle.local}`); console.log(` Domain: ${parsedSingle.domain}`); } else { console.log(`Failed to parse: ${singleAddress}`); } console.log('\n---'); // Parse a list of email addresses const addressList = 'jack@fogcreek.com, Bob <bob@example.com>'; const parsedList = emailAddresses.parseAddressList(addressList); if (parsedList) { console.log('Parsed Address List:'); parsedList.forEach((addr, index) => { console.log(` Address ${index + 1}:`); console.log(` Name: ${addr.name}`); console.log(` Address: ${addr.address}`); }); } else { console.log(`Failed to parse: ${addressList}`); } console.log('\n---'); // Get access to the full AST (Abstract Syntax Tree) for detailed analysis const astResult = emailAddresses({ input: 'user@domain.com', simple: false }); if (astResult && astResult.ast) { console.log('AST for user@domain.com:'); console.log(JSON.stringify(astResult.ast, null, 2)); } else { console.log('Failed to get AST for user@domain.com'); } // Example of invalid input const invalidInput = "bogus"; const invalidParsed = emailAddresses(invalidInput); console.log(`\nParsing "${invalidInput}" yields: ${invalidParsed}`);

Debug

Known issues

breakingMajor version 5.0.0 often introduces breaking changes in APIs, internal structures, or module system compatibility (e.g., transition to pure ESM or dual package support). Always consult the changelog for specific migration steps when upgrading from older major versions.

fix

Review the official changelog or migration guide for `email-addresses` v5.x.x for specific API changes. Update import statements, function calls, and option handling as necessary.

affects: >=5.0.0

gotchaThis library performs RFC 5322 *parsing* but does not perform RFC 5321 *validation* (which checks for actual deliverability via DNS records and SMTP handshakes). RFC 5322 is very liberal, meaning an address might parse successfully but still be undeliverable or invalid for common use cases.

fix

If you require stricter validation (e.g., checking MX records, disposable email detection, or deliverability), use an additional library like `node-email-verifier` or a dedicated email validation service in conjunction with `email-addresses`.

affects: >=1.0.0

gotchaRFC 5322 allows complex display names and comments, such as `"Bob Example" <bob@example.com>` or `bob(comment)@example.com`. This library will parse these correctly. If your application expects only simple `local@domain` formats, be aware that these structures are valid according to the RFC.

fix

After parsing, inspect the `name` property or other `parts` to determine if a display name or comments were present. If only the `local@domain` part is desired, always use the `address` property of the parsed object.

affects: >=1.0.0

gotchaThe library returns `null` for any input string that fails to parse as a valid RFC 5322 email address. It does not throw an error, which might be unexpected if you typically use try/catch for invalid inputs.

fix

Always check for `null` after calling `emailAddresses(...)`, `emailAddresses.parseOneAddress(...)`, or `emailAddresses.parseAddressList(...)` before attempting to access properties of the returned object to avoid `TypeError: Cannot read properties of null (reading '...')`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: emailAddresses(...) is not a function

Attempting to call the imported module directly as a function when it was imported as a named export, or vice-versa, or incorrect CommonJS require usage.

fix

Ensure you are using the correct import style for your module environment (ESM `import` or CommonJS `require`). If using CommonJS, `const addrs = require('email-addresses')` makes `addrs` a callable object. For ESM, `import emailAddresses from 'email-addresses'` makes `emailAddresses` the callable function.

ReferenceError: require is not defined

This error occurs in an ECMAScript Module (ESM) environment when you try to use `require()` for a package that expects `import`.

fix

Update your code to use ESM `import` statements (e.g., `import emailAddresses from 'email-addresses';`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: Cannot read properties of null (reading 'address')

Attempting to access properties (like `address`, `name`, `local`, `domain`) on a `null` value returned by the parsing functions when the input email string was invalid.

fix

Always check if the result of `emailAddresses(...)`, `parseOneAddress(...)`, or `parseAddressList(...)` is not `null` before trying to access its properties. For example: `const parsed = emailAddresses('invalid'); if (parsed) { /* use parsed */ } else { /* handle invalid input */ }`.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jackbearheart/email-addresses ↗

packagehttps://www.npmjs.com/package/email-addresses ↗