Registry / serialization / address-rfc2821

address-rfc2821

library2.1.5jsnpmunverified

address-rfc2821 is a JavaScript/TypeScript library designed for parsing email addresses conforming to RFC-5321 (formerly RFC-821/2821) specifically for the SMTP envelope, found in `MAIL FROM:` and `RCPT TO:` commands. This module focuses on the nuances of envelope addressing, including handling null senders (`<>`) and correctly managing quoted local-parts. Since version 2.0.0, it transitioned from a regex-based parser to one built with Nearley, providing more robust and accurate parsing. It also supports UTF-8 email addresses according to RFCs 5890-5892, providing the domain in punycode when necessary. The current stable version is 2.1.5, with recent updates including the addition of TypeScript type definitions in v2.1.4 and a fix to `isNull()`'s return type in v2.1.5. The library maintains an active release cadence, reflecting ongoing development and maintenance for Haraka mail server components.

serialization

npm install address-rfc2821

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ADDRESS-RFC2821

address-rfc2821

serializationjavascriptv2.1.5

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.

Address

✓ import { Address } from 'address-rfc2821';

✗ const Address = require('address-rfc2821').Address;

While CommonJS `require` still works for basic usage, the package's `engines` field (>= 20.20.0) and TypeScript types strongly encourage ESM `import`.

Address (CommonJS)

✓ const { Address } = require('address-rfc2821');

The original documentation shows `require('address-rfc2821').Address`. Destructuring is also common. ESM `import` is preferred for modern Node.js environments.

Address (Type)

✓ import type { Address } from 'address-rfc2821';

TypeScript type definitions were added in version 2.1.4. Use `import type` for type-only imports to ensure they are stripped from the compiled JavaScript output.

Demonstrates parsing various RFC-5321 compliant email addresses, including null senders and quoted local-parts. It shows how to access user and host components, format the address, and handle internationalized domains with punycode.

import { Address } from 'address-rfc2821'; try { // Parse a standard email address const addr1 = new Address('<user@example.com>'); console.log(`Parsed: ${addr1.format()} | User: ${addr1.user}, Host: ${addr1.host}`); // Parse an address with a quoted local-part (handled correctly since v2.0.0) const addr2 = new Address('<"first.last+tag"@sub.domain.com>'); console.log(`Parsed: ${addr2.format()} | User: ${addr2.user}, Host: ${addr2.host}`); // Handle the null sender ('<>') const nullSender = new Address('<>'); console.log(`Null Sender: ${nullSender.format()} | Is Null: ${nullSender.isNull()}`); // Example with an internationalized domain name (IDN) const internationalEmail = new Address('test@bücher.example'); console.log(`IDN Email (original host): ${internationalEmail.format()} (Host: ${internationalEmail.original_host})`); console.log(`IDN Email (punycode host): ${internationalEmail.format(true)} (Host: ${internationalEmail.host})`); // Create a new Address object from user and host parts const newAddr = new Address('info', 'my-service.dev'); console.log(`Created: ${newAddr.toString()}`); // This would throw an exception for unparseable addresses // new Address('not-a-valid-email-address'); } catch (error) { console.error('An error occurred during parsing:', error instanceof Error ? error.message : String(error)); }

Debug

Known issues

breakingVersion 2.0.0 completely replaced the regular expression parser with a Nearley-based grammar. This resulted in more accurate parsing but could introduce subtle behavioral changes for edge cases. Double quote characters in the local-part are no longer stripped.

fix

Review parsing logic, especially for local-parts with double quotes or other non-standard characters. Ensure existing tests cover these cases.

affects: >=2.0.0

breakingVersion 2.0.0 increased the minimum required Node.js version to 11+.

fix

Ensure your Node.js environment is version 11 or higher. The current recommended `engines` field specifies `>= 20.20.0`.

affects: >=2.0.0

gotchaTypeScript type definitions were officially added in version 2.1.4. Prior to this, users either had to use `any` or provide custom type declarations. If upgrading from pre-2.1.4, remove any custom types.

fix

Remove manual `@types/address-rfc2821` or local `.d.ts` files, and use the types shipped with the package: `import type { Address } from 'address-rfc2821';`

affects: <2.1.4

breakingIn version 2.1.5, the `isNull()` method was updated to return a strict boolean (`true`/`false`) instead of a 'perlism' truthy/falsy value (e.g., `1`/`0`).

fix

Ensure any code checking `address.isNull()` expects a boolean result. Most JavaScript truthy/falsy checks will continue to work, but strict type comparisons (`===`) might fail if they expected a non-boolean value.

affects: >=2.1.5

Errors

Common errors & fixes

Error: Address cannot be parsed

The input string provided to the `Address` constructor does not conform to RFC-5321 email address syntax (e.g., missing '@', invalid characters, or malformed structure).

fix

Ensure the email string strictly follows the RFC-5321 envelope address format. For header addresses (To, From, CC), use a parser like `address-rfc2822` or `email-addresses` instead.

TypeError: Address is not a constructor

This error typically occurs when trying to use `require('address-rfc2821')` directly as a constructor, or if the import path is incorrect, or if using CommonJS `require` with a package that is ESM-only (though this package supports both).

fix

If using CommonJS, ensure you're accessing the `Address` class correctly: `const { Address } = require('address-rfc2821');` or `const Address = require('address-rfc2821').Address;`. If using ESM, make sure to use named import: `import { Address } from 'address-rfc2821';`.

Upgrade

Version history

2.1.5latest on npm

Audit

Dependencies

punycoderequiredUsed for converting internationalized domain names (IDNs) to ASCII Compatible Encoding (ACE) as per RFC 3492.

Agent activity

34 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/haraka/node-address-rfc2821 ↗

packagehttps://www.npmjs.com/package/address-rfc2821 ↗

homepagehttps://haraka.github.io ↗