{"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,"search_vec":"'-5321':2,21,153 '-5892':92 '-8':85 '-821':24 '/2821':25 '2.0.0':61 '2.1.5':105 '5890':91 'accord':88 'accur':79 'activ':132 'addit':111 'address':4,7,17,47,87,148 'address-rfc2821':6 'also':82 'base':68 'built':72 'cadenc':134 'command':38 'compon':144 'conform':18 'correct':53 'current':101 'definit':115 'design':13 'develop':137 'domain':95 'email':3,16,86,146 'envelop':30,46,147 'fix':120 'focus':41 'former':22 'found':31 'handl':49 'haraka':141 'includ':48,109 'isnul':122 'javascript':145 'javascript/typescript':11 'librari':12,129 'local':57 'local-part':56 'mail':33,142,154 'maintain':130 'mainten':139 'manag':54 'modul':40 'nearley':74 'necessari':99 'nuanc':44 'null':50 'one':71 'ongo':136 'pars':15,80 'parser':5,69 'part':58 'provid':75,93 'punycod':97 'quot':55 'rcpt':36 'recent':107 'reflect':135 'regex':67 'regex-bas':66 'releas':133 'return':124 'rfc':1,20,23,152 'rfc2821':8,150 'rfc5321':151 'rfc821':149 'rfcs':90 'robust':77 'sender':51 'server':143 'sinc':59 'smtp':29 'specif':26 'stabl':102 'support':83 'transit':63 'type':114,125 'typescript':113,155 'updat':108 'utf':84 'v2.1.4':117 'v2.1.5':127 'version':60,103","created_at":"2026-04-20T01:51:08.574288+00:00","updated_at":"2026-04-20T01:51:08.574288+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://haraka.github.io","github":"https://github.com/haraka/node-address-rfc2821","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/address-rfc2821","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}