PHPackages mmucklo/email-parse - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. mmucklo/email-parse ActiveLibrary[Mail & Notifications](/categories/mail) mmucklo/email-parse =================== RFC 5322 / RFC 6531-compliant library for batch parsing multiple (and single) email addresses 3.3.1(2mo ago)46881.7k↓27%14[2 issues](https://github.com/mmucklo/email-parse/issues)1MITPHPPHP ^8.1CI passing Since Jul 8Pushed 2mo ago8 watchersCompare [ Source](https://github.com/mmucklo/email-parse)[ Packagist](https://packagist.org/packages/mmucklo/email-parse)[ RSS](/packages/mmucklo-email-parse/feed)WikiDiscussions master Synced 3d ago READMEChangelogDependencies (14)Versions (31)Used By (1) email-parse =========== [](#email-parse) [![Support on Patreon](https://camo.githubusercontent.com/ad2f9db89dbf03d0efcb9c1efbd9a815ef15d76004f5aeedd7f25cfc84c5d42b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50617472656f6e2d537570706f72742532304d652d6639363835343f6c6f676f3d70617472656f6e)](https://www.patreon.com/cw/MatthewJMucklo) [![CI](https://github.com/mmucklo/email-parse/workflows/CI/badge.svg)](https://github.com/mmucklo/email-parse/actions)[![codecov](https://camo.githubusercontent.com/50a8868f8fa35ef3ecffae486442389587a177058fc91d47ecfd5ddee19e5727/68747470733a2f2f636f6465636f762e696f2f67682f6d6d75636b6c6f2f656d61696c2d70617273652f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/mmucklo/email-parse)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/e725de2a8997bea4e23731aaf1274e2b80561ea6e3621ca2275a746b075e6c09/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6d6d75636b6c6f2f656d61696c2d70617273652f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/mmucklo/email-parse/?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/31950afee4fc77687029da4088058993772e98fa21d089c7ddfa723008925c43/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6d75636b6c6f2f656d61696c2d70617273652e737667)](https://packagist.org/packages/mmucklo/email-parse)[![Total Downloads](https://camo.githubusercontent.com/66bc8d69f8b8e56a87f9eecd34d99bfa02c3538318130b23cd6e2f6c65906526/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6d75636b6c6f2f656d61696c2d70617273652e737667)](https://packagist.org/packages/mmucklo/email-parse)[![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://www.php.net)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE) Email\\Parse is a batch email address parser with configurable RFC compliance levels (RFC 5322, RFC 6531/6532, RFC 2822). Supports internationalized email addresses (UTF-8 local parts and IDN domains). It parses a list of 1 to n email addresses separated by comma and whitespace by default, with configurable separators (e.g. semicolon). **Other docs:** [CHANGELOG](CHANGELOG.md) · [UPGRADE guide (v2.x → v3.0)](UPGRADE.md) · [DESIGN / RFC reference](DESIGN.md) · [ROADMAP](ROADMAP.md) Installation: ------------- [](#installation) ``` composer require mmucklo/email-parse ``` Usage: ------ [](#usage) ### Basic Usage [](#basic-usage) ``` use Email\Parse; // Array-based API (v2.x-compatible) $result = Parse::getInstance()->parse("a@aaa.com b@bbb.com"); // Typed value objects (v3.1+, recommended for new code) $address = Parse::getInstance()->parseSingle('john@example.com'); echo $address->localPart; // "john" echo $address->domain; // "example.com" if ($address->invalid) { echo $address->invalidReasonCode->value; } $result = Parse::getInstance()->parseMultiple('a@a.com, b@b.com'); foreach ($result->emailAddresses as $addr) { /* ... */ } // Streaming for large batches (v3.2+) — yields one address at a time. foreach (Parse::getInstance()->parseStream($csvRows) as $addr) { if ($addr->invalid) continue; // ... } // Serialization (v3.3+) $parsed = Parse::getInstance()->parseSingle('"J Doe" '); (string) $parsed; // "j@example.com" — Stringable returns simple_address $parsed->canonical(); // 'J Doe ' — minimal RFC 5322 quoting $parsed->toArray(); // legacy array shape, for mixed-API code $parsed->toJson(); // JSON string ``` ### Advanced Usage with ParseOptions [](#advanced-usage-with-parseoptions) You can configure separator behavior and other parsing options using `ParseOptions`: ``` use Email\Parse; use Email\ParseOptions; // Example 1: Use comma and semicolon as separators (default behavior includes whitespace) $options = new ParseOptions([], [',', ';']); $parser = new Parse(null, $options); $result = $parser->parse("a@aaa.com; b@bbb.com, c@ccc.com"); // Example 2: Disable whitespace as separator (only comma and semicolon work) $options = new ParseOptions([], [',', ';'], false); $parser = new Parse(null, $options); $result = $parser->parse("a@aaa.com; b@bbb.com"); // Works - uses semicolon $result = $parser->parse("a@aaa.com b@bbb.com"); // Won't split - whitespace not a separator // Example 3: Names with spaces always work regardless of whitespace separator setting $options = new ParseOptions([], [',', ';'], false); $parser = new Parse(null, $options); $result = $parser->parse("John Doe , Jane Smith "); // Returns 2 valid emails with names preserved ``` ### RFC Compliance Presets [](#rfc-compliance-presets) The parser provides factory methods on `ParseOptions` for common RFC compliance levels: ``` use Email\Parse; use Email\ParseOptions; // RFC 5321 — Strict ASCII (SMTP Mailbox syntax) $options = ParseOptions::rfc5321(); $parser = new Parse(null, $options); // RFC 6531 — Strict Internationalized (full UTF-8 + NFC normalization) $options = ParseOptions::rfc6531(); $parser = new Parse(null, $options); $result = $parser->parseSingle('müller@münchen.de'); // Valid UTF-8 address // RFC 5322 — Standard with obsolete syntax support (recommended) $options = ParseOptions::rfc5322(); $parser = new Parse(null, $options); // RFC 2822 — Maximum compatibility $options = ParseOptions::rfc2822(); $parser = new Parse(null, $options); // Legacy — v2.x default behavior $options = new ParseOptions(); $parser = new Parse(null, $options); ``` **Preset Comparison:** PresetStandardUTF-8 SupportObsolete SyntaxUse Case`rfc6531()`RFC 6531/6532Full (NFC normalization)NoInternational apps with UTF-8 emails`rfc5321()`RFC 5321ASCII onlyNoModern ASCII-only SMTP validation`rfc5322()`RFC 5322 + obsoleteASCII onlyYes**Recommended default** (v3.0+)`rfc2822()`RFC 2822ASCII onlyYesLegacy system integration`new ParseOptions()`LegacyPermissiveNo**v2.x backward-compatible default****RFC 6531 Features (`rfc6531()`):** - UTF-8 characters in local-part and domain (e.g., `日本語@example.jp`) - Unicode normalization (NFC per RFC 6532 §3.1) - C0/C1 control character rejection (RFC 6530 §10.1) - Internationalized domains (IDN) with punycode output (`includeDomainAscii = true`) - Length limits in octets (multi-byte UTF-8 counts as multiple octets) - Requires PHP Intl extension for full functionality **Example:** ``` // UTF-8 email address validation $options = ParseOptions::rfc6531(); $parser = new Parse(null, $options); $result = $parser->parseSingle('José.García@españa.es'); // Valid: UTF-8 characters allowed in rfc6531() preset $result = $parser->parseSingle('.user@example.com'); // Invalid: Leading dot not allowed (dot-atom restrictions still apply) ``` ### Customizing Rules [](#customizing-rules) Each preset sets a combination of boolean rule properties. Rule properties are **readonly** (v3.1+) — override them via fluent `withX()` builders that return new instances: ``` $options = ParseOptions::rfc6531() ->withRequireFqdn(false) // Allow single-label domains ->withIncludeDomainAscii(false); // Don't output punycode domain $parser = new Parse(null, $options); ``` **Available Rule Properties:** PropertyDefaultDescription**Local-Part Rules**`allowUtf8LocalPart``true`Allow UTF-8 characters in local-part (RFC 6531)`allowObsLocalPart``false`Allow obsolete syntax: leading/trailing/consecutive dots (RFC 5322 §4.4)`allowQuotedString``true`Allow quoted-string form in local-part`validateQuotedContent``false`Validate qtext/quoted-pair rules in quoted strings`rejectEmptyQuotedLocalPart``false`Reject `""@domain` (RFC 5321 EID 5414)**Domain Rules**`allowUtf8Domain``true`Allow Unicode (U-label) domain names (RFC 5890/5891)`allowDomainLiteral``true`Allow address-literal form `[IP]` or `[IPv6:addr]` in domain (RFC 5321 §4.1.3)`requireFqdn``false`Require at least two domain labels (RFC 5321 §2.3.5)`validateIpGlobalRange``true`Validate IP addresses are in global range**Character Validation**`rejectC0Controls``false`Reject C0 control characters U+0000-U+001F (RFC 5321)`rejectC1Controls``false`Reject C1 control characters U+0080-U+009F (RFC 6530)`applyNfcNormalization``false`Apply NFC Unicode normalization (RFC 6532 §3.1)`validateDisplayNamePhrase``false`Enforce RFC 5322 §3.2.5 phrase syntax on unquoted display names`strictIdna``false`Apply full IDNA2008 conformance on U-label domains (RFC 5891/5892/5893)`allowObsRoute``false`Accept RFC 5322 §4.4 obs-route source-routes like ```localPartNormalizer``null``?callable(string $local, string $domain): string` — domain-specific canonicalization hook (v3.3+); set via `withLocalPartNormalizer()`**Length & Output**`enforceLengthLimits``true`Enforce RFC 5321 length limits (64/254/63)`includeDomainAscii``false`Include punycode `domain_ascii` in outputThe defaults shown above are for `new ParseOptions()` (legacy). Each factory method sets its own combination — see the [source code](src/ParseOptions.php) for exact values. ### ParseOptions Constructor [](#parseoptions-constructor) ``` /** * @param array $bannedChars Array of characters to ban from email addresses (e.g., ['%', '!']) * @param array $separators Array of separator characters (default: [',']) * @param bool $useWhitespaceAsSeparator Whether to treat whitespace/newlines as separators (default: true) * @param LengthLimits|null $lengthLimits Email length limits. Uses RFC defaults if not provided */ public function __construct( array $bannedChars = [], array $separators = [','], bool $useWhitespaceAsSeparator = true, ?LengthLimits $lengthLimits = null ) ``` ### Configuring Length Limits [](#configuring-length-limits) You can customize RFC 5321 length limits using the `LengthLimits` class: ``` use Email\Parse; use Email\ParseOptions; use Email\LengthLimits; // Use default RFC-compliant limits (64, 254, 63) $options = new ParseOptions([], [','], true, LengthLimits::createDefault()); // Use relaxed limits for legacy systems (128, 512, 128) $options = new ParseOptions([], [','], true, LengthLimits::createRelaxed()); // Custom limits $limits = new LengthLimits( 100, // maxLocalPartLength (before @) 300, // maxTotalLength (entire email) 100 // maxDomainLabelLength (each domain label) ); $options = new ParseOptions([], [','], true, $limits); $parser = new Parse(null, $options); ``` **Default RFC Limits:** - Local part (before `@`): 64 octets (RFC 5321) - Total email length: 254 octets (RFC 3696 EID 1690) - Domain label: 63 octets (RFC 1035) ### Supported Separators [](#supported-separators) - **Comma (`,`)** - Configured via `$separators` parameter - **Semicolon (`;`)** - Configured via `$separators` parameter - **Whitespace (space, tab, newlines)** - Controlled by `$useWhitespaceAsSeparator` parameter - **Mixed separators** - All configured separators work together seamlessly **Note:** When `useWhitespaceAsSeparator` is `false`, whitespace is still properly cleaned up and names with spaces (like "John Doe") continue to work correctly. ### Internationalized Domains (IDN) [](#internationalized-domains-idn) The parser supports internationalized domain names per RFC 5890/5891. Unicode domains are normalized to ASCII (punycode) for validation and length enforcement, while the original Unicode domain is preserved. The `domain_ascii` field is included in the output when `includeDomainAscii` is `true` on the `ParseOptions` instance. This is enabled by default in the `rfc6531()` preset. ``` $options = ParseOptions::rfc6531(); $parser = new Parse(null, $options); $result = $parser->parseSingle('user@bücher.de'); // $result->domain === 'bücher.de' // $result->domainAscii === 'xn--bcher-kva.de' ``` ### Comment Extraction [](#comment-extraction) RFC 5322 allows comments in email addresses using parentheses. The parser automatically extracts these comments and returns them in the `comments` array: ``` use Email\Parse; // Single comment $result = Parse::getInstance()->parseSingle('john@example.com (home address)'); // $result->comments === ['home address'] // Multiple comments $result = Parse::getInstance()->parseSingle('test(comment1)(comment2)@example.com'); // $result->comments === ['comment1', 'comment2'] // Nested comments $result = Parse::getInstance()->parseSingle('test@example.com (comment with (nested) parens)'); // $result->comments === ['comment with (nested) parens'] // No comments $result = Parse::getInstance()->parseSingle('test@example.com'); // $result->comments === [] ``` Comments are stripped from the `address` field but preserved in `original_address`. ### Migration Guide [](#migration-guide) **Migrating from v2.x to v3.0:** See [UPGRADE.md](UPGRADE.md) for the complete list of breaking changes, deprecations, and bug-fix behavior changes. **Quick start:** ``` // v2.x default (legacy behavior — still works in v3.0) $parser = Parse::getInstance(); // v3.0 recommended default $options = ParseOptions::rfc5322(); $parser = new Parse(null, $options); ``` **Key differences between legacy and `rfc5322()`:** - `rfc5322()` rejects C0 control characters (`rejectC0Controls = true`) - `rfc5322()` allows obsolete local-part syntax (consecutive dots, etc.) - `rfc5322()` enforces RFC 5321 length limits - Legacy mode (`new ParseOptions()`) accepts UTF-8 by default; `rfc5322()` does not **Adding UTF-8 support:** ``` // Use the rfc6531() preset for full internationalized email support $options = ParseOptions::rfc6531(); $parser = new Parse(null, $options); $result = $parser->parseSingle('müller@münchen.de'); ``` #### Function Spec [](#function-spec) ``` /** * function parse($emails, $multiple = true, $encoding = 'UTF-8') * @param string $emails List of Email addresses separated by configured separators (comma, semicolon, whitespace by default) * @param bool $multiple (optional, default: true) Whether to parse for multiple email addresses or not * @param string $encoding (optional, default: 'UTF-8') The encoding if not 'UTF-8' * @return: see below: */ if ($multiple): array('success' => boolean, // whether totally successful or not 'reason' => string|null, // if unsuccessful, the reason why; null if successful 'email_addresses' => array('address' => string, // the full address (not including comments) 'original_address' => string, // the full address including comments 'simple_address' => string, // simply local_part@domain_part (e.g. someone@somewhere.com) 'name' => string, // the name on the email if given (e.g.: John Q. Public), including any quotes 'name_parsed' => string, // the name on the email if given (e.g.: John Q. Public), excluding any quotes 'local_part' => string, // the local part (before the '@' sign - e.g. johnpublic) 'local_part_parsed' => string, // the local part (before the '@' sign - e.g. johnpublic), excluding any quotes 'domain' => string, // the domain after the '@' if given (may be Unicode) 'domain_ascii' => string|null, // punycode ASCII domain (when includeDomainAscii is true) 'ip' => string, // the IP after the '@' if given 'domain_part' => string, // either domain or IP depending on what given 'invalid' => boolean, // if the email is valid or not 'invalid_reason' => string|null, // if the email is invalid, the reason why; null if valid 'comments' => array), // array of extracted comments (e.g. ['comment1', 'comment2']) array( .... ) // the next email address matched ) else: array('address' => string, // the full address (not including comments) 'original_address' => string, // the full address including comments 'simple_address' => string, // simply local_part@domain_part 'name' => string, // the name on the email if given (e.g.: John Q. Public) 'name_parsed' => string, // the name excluding quotes 'local_part' => string, // the local part (before the '@' sign - e.g. johnpublic) 'local_part_parsed' => string, // the local part excluding quotes 'domain' => string, // the domain after the '@' if given (may be Unicode) 'domain_ascii' => string|null, // punycode ASCII domain (when includeDomainAscii is true) 'ip' => string, // the IP after the '@' if given 'domain_part' => string, // either domain or IP depending on what given 'invalid' => boolean, // if the email is valid or not 'invalid_reason' => string|null, // if the email is invalid, the reason why; null if valid 'comments' => array) // array of extracted comments (e.g. ['comment1', 'comment2']) endif; ``` Other Examples: --------------- [](#other-examples) The following examples use the legacy array-returning `parse()` method to document its full output shape. New code should prefer `parseSingle()` / `parseMultiple()` (see Basic Usage) for typed return values; both APIs expose the same underlying fields. ``` $email = '"J Doe" '; $result = Email\Parse::getInstance()->parse($email, false); $result == array( 'address' => '"J Doe" ', 'original_address' => '"J Doe" ', 'simple_address' => 'johndoe@xyz.com', 'name' => '"J Doe"', 'name_parsed' => 'J Doe', 'local_part' => 'johndoe', 'local_part_parsed' => 'johndoe', 'domain_part' => 'xyz.com', 'domain' => 'xyz.com', 'domain_ascii' => null, 'ip' => '', 'invalid' => false, 'invalid_reason' => null, 'comments' => []); $emails = 'testing@[8.8.8.8] testing@xyz.com, "test.2"@xyz.com (comment)'; $result = Email\Parse::getInstance()->parse($emails); $result == array( 'success' => true, 'reason' => null, 'email_addresses' => array( array( 'address' => 'testing@[8.8.8.8]', 'original_address' => 'testing@[8.8.8.8]', 'simple_address' => 'testing@[8.8.8.8]', 'name' => '', 'name_parsed' => '', 'local_part' => 'testing', 'local_part_parsed' => 'testing', 'domain_part' => '[8.8.8.8]', 'domain' => '', 'domain_ascii' => null, 'ip' => '8.8.8.8', 'invalid' => false, 'invalid_reason' => null, 'comments' => []), array( 'address' => 'testing@xyz.com', 'original_address' => 'testing@xyz.com', 'simple_address' => 'testing@xyz.com', 'name' => '', 'name_parsed' => '', 'local_part' => 'testing', 'local_part_parsed' => 'testing', 'domain_part' => 'xyz.com', 'domain' => 'xyz.com', 'domain_ascii' => null, 'ip' => '', 'invalid' => false, 'invalid_reason' => null, 'comments' => []), array( 'address' => '"test.2"@xyz.com', 'original_address' => '"test.2"@xyz.com (comment)', 'simple_address' => '"test.2"@xyz.com', 'name' => '', 'name_parsed' => '', 'local_part' => '"test.2"', 'local_part_parsed' => 'test.2', 'domain_part' => 'xyz.com', 'domain' => 'xyz.com', 'domain_ascii' => null, 'ip' => '', 'invalid' => false, 'invalid_reason' => null, 'comments' => ['comment']) ) ); ``` ### Health Score 65 — FairBetter than 99% of packages Maintenance85 Actively maintained with recent releases Popularity51 Moderate usage in the ecosystem Community25 Small or concentrated contributor base Maturity83 Battle-tested with a long release history Bus Factor1 Top contributor holds 87.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~151 days Recently: every ~2 days Total 27 Last Release 75d ago Major Versions 0.4.3 → 1.0.02015-09-15 1.0.0 → 2.0.02017-04-15 2.8.0 → 3.0.02026-04-12 PHP version history (6 changes)0.2.0PHP >=5.4.0 2.0.0PHP >=5.6.0 2.1.0PHP >=7.1 2.3.0PHP ^8.2 2.5.0PHP ^8.1 2.2.x-devPHP ^7.1|^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/f05a1e018633083f2618b189473318e14d14d921216188d36c52e582244340c7?d=identicon)[mmucklo](/maintainers/mmucklo) --- Top Contributors [![mmucklo](https://avatars.githubusercontent.com/u/245122?v=4)](https://github.com/mmucklo "mmucklo (69 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (3 commits)")[![glensc](https://avatars.githubusercontent.com/u/199095?v=4)](https://github.com/glensc "glensc (2 commits)")[![mkraemer](https://avatars.githubusercontent.com/u/1070200?v=4)](https://github.com/mkraemer "mkraemer (2 commits)")[![ArthurHoaro](https://avatars.githubusercontent.com/u/1962678?v=4)](https://github.com/ArthurHoaro "ArthurHoaro (1 commits)")[![compwright](https://avatars.githubusercontent.com/u/138688?v=4)](https://github.com/compwright "compwright (1 commits)")[![arnested](https://avatars.githubusercontent.com/u/190005?v=4)](https://github.com/arnested "arnested (1 commits)") --- Tags utf-8emailparseRFC822RFC2822email-parsemultiple-emailbatch-emailRFC5322RFC6531internationalized-email ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/mmucklo-email-parse/health.svg) ``` [![Health](https://phpackages.com/badges/mmucklo-email-parse/health.svg)](https://phpackages.com/packages/mmucklo-email-parse) ``` ### Alternatives [symfony/symfony The Symfony PHP framework 31.4k87.2M2.2k](/packages/symfony-symfony)[symfony/mime Allows manipulating MIME messages 2.8k716.9M1.4k](/packages/symfony-mime)[symfony/mailer Helps sending emails 1.6k409.1M1.4k](/packages/symfony-mailer)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[zbateson/mail-mime-parser MIME email message parser 54753.3M90](/packages/zbateson-mail-mime-parser)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6942.5M420](/packages/drupal-core-recommended) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)