{"id":13113,"library":"email-addresses","title":"Email Address RFC 5322 Parser","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jackbearheart/email-addresses","tags":["javascript","email address","parser","rfc5322","5322","typescript"],"install":[{"cmd":"npm install email-addresses","lang":"bash","label":"npm"},{"cmd":"yarn add email-addresses","lang":"bash","label":"yarn"},{"cmd":"pnpm add email-addresses","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const emailAddresses = require('email-addresses');","symbol":"emailAddresses","correct":"import emailAddresses from 'email-addresses';"},{"note":"This named export is specifically for parsing a single email address.","wrong":"const { parseOneAddress } = require('email-addresses');","symbol":"parseOneAddress","correct":"import { parseOneAddress } from 'email-addresses';"},{"note":"This named export is designed for parsing a comma-separated list of email addresses.","wrong":"const { parseAddressList } = require('email-addresses');","symbol":"parseAddressList","correct":"import { parseAddressList } from 'email-addresses';"},{"note":"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).","wrong":"import { parseOneAddress } from 'email-addresses'; parseOneAddress('test@example.com', { rfc6532: true });","symbol":"Any Parse Option","correct":"import emailAddresses from 'email-addresses'; emailAddresses({ input: 'test@example.com', rfc6532: true });"}],"quickstart":{"code":"import emailAddresses from 'email-addresses';\n\n// Parse a single email address with a display name\nconst singleAddress = '\"Jack Bowman\" <jack@fogcreek.com>';\nconst parsedSingle = emailAddresses.parseOneAddress(singleAddress);\n\nif (parsedSingle) {\n  console.log('Parsed Single Address:');\n  console.log(`  Name: ${parsedSingle.name}`);\n  console.log(`  Address: ${parsedSingle.address}`);\n  console.log(`  Local Part: ${parsedSingle.local}`);\n  console.log(`  Domain: ${parsedSingle.domain}`);\n} else {\n  console.log(`Failed to parse: ${singleAddress}`);\n}\n\nconsole.log('\\n---');\n\n// Parse a list of email addresses\nconst addressList = 'jack@fogcreek.com, Bob <bob@example.com>';\nconst parsedList = emailAddresses.parseAddressList(addressList);\n\nif (parsedList) {\n  console.log('Parsed Address List:');\n  parsedList.forEach((addr, index) => {\n    console.log(`  Address ${index + 1}:`);\n    console.log(`    Name: ${addr.name}`);\n    console.log(`    Address: ${addr.address}`);\n  });\n} else {\n  console.log(`Failed to parse: ${addressList}`);\n}\n\nconsole.log('\\n---');\n\n// Get access to the full AST (Abstract Syntax Tree) for detailed analysis\nconst astResult = emailAddresses({ input: 'user@domain.com', simple: false });\n\nif (astResult && astResult.ast) {\n  console.log('AST for user@domain.com:');\n  console.log(JSON.stringify(astResult.ast, null, 2));\n} else {\n  console.log('Failed to get AST for user@domain.com');\n}\n\n// Example of invalid input\nconst invalidInput = \"bogus\";\nconst invalidParsed = emailAddresses(invalidInput);\nconsole.log(`\\nParsing \"${invalidInput}\" yields: ${invalidParsed}`);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Major 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"RFC 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 '...')`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: emailAddresses(...) is not a function"},{"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`).","cause":"This error occurs in an ECMAScript Module (ESM) environment when you try to use `require()` for a package that expects `import`.","error":"ReferenceError: require is not defined"},{"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 */ }`.","cause":"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.","error":"TypeError: Cannot read properties of null (reading 'address')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}