{"id":12794,"library":"address-rfc2821","title":"RFC-5321 Email Address Parser","description":"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.","status":"active","version":"2.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/haraka/node-address-rfc2821","tags":["javascript","email","envelope","address","rfc821","rfc2821","rfc5321","RFC-5321","mail","typescript"],"install":[{"cmd":"npm install address-rfc2821","lang":"bash","label":"npm"},{"cmd":"yarn add address-rfc2821","lang":"bash","label":"yarn"},{"cmd":"pnpm add address-rfc2821","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for converting internationalized domain names (IDNs) to ASCII Compatible Encoding (ACE) as per RFC 3492.","package":"punycode","optional":false}],"imports":[{"note":"While CommonJS `require` still works for basic usage, the package's `engines` field (>= 20.20.0) and TypeScript types strongly encourage ESM `import`.","wrong":"const Address = require('address-rfc2821').Address;","symbol":"Address","correct":"import { Address } from 'address-rfc2821';"},{"note":"The original documentation shows `require('address-rfc2821').Address`. Destructuring is also common. ESM `import` is preferred for modern Node.js environments.","symbol":"Address (CommonJS)","correct":"const { Address } = require('address-rfc2821');"},{"note":"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.","symbol":"Address (Type)","correct":"import type { Address } from 'address-rfc2821';"}],"quickstart":{"code":"import { Address } from 'address-rfc2821';\n\ntry {\n  // Parse a standard email address\n  const addr1 = new Address('<user@example.com>');\n  console.log(`Parsed: ${addr1.format()} | User: ${addr1.user}, Host: ${addr1.host}`);\n\n  // Parse an address with a quoted local-part (handled correctly since v2.0.0)\n  const addr2 = new Address('<\"first.last+tag\"@sub.domain.com>');\n  console.log(`Parsed: ${addr2.format()} | User: ${addr2.user}, Host: ${addr2.host}`);\n\n  // Handle the null sender ('<>')\n  const nullSender = new Address('<>');\n  console.log(`Null Sender: ${nullSender.format()} | Is Null: ${nullSender.isNull()}`);\n\n  // Example with an internationalized domain name (IDN)\n  const internationalEmail = new Address('test@bücher.example');\n  console.log(`IDN Email (original host): ${internationalEmail.format()} (Host: ${internationalEmail.original_host})`);\n  console.log(`IDN Email (punycode host): ${internationalEmail.format(true)} (Host: ${internationalEmail.host})`);\n\n  // Create a new Address object from user and host parts\n  const newAddr = new Address('info', 'my-service.dev');\n  console.log(`Created: ${newAddr.toString()}`);\n\n  // This would throw an exception for unparseable addresses\n  // new Address('not-a-valid-email-address');\n\n} catch (error) {\n  console.error('An error occurred during parsing:', error instanceof Error ? error.message : String(error));\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Review parsing logic, especially for local-parts with double quotes or other non-standard characters. Ensure existing tests cover these cases.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment is version 11 or higher. The current recommended `engines` field specifies `>= 20.20.0`.","message":"Version 2.0.0 increased the minimum required Node.js version to 11+.","severity":"breaking","affected_versions":">=2.0.0"},{"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';`","message":"TypeScript 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.","severity":"gotcha","affected_versions":"<2.1.4"},{"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.","message":"In 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`).","severity":"breaking","affected_versions":">=2.1.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"Error: Address cannot be parsed"},{"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';`.","cause":"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).","error":"TypeError: Address is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}