Email:...::List(3pm)

📦
version 0.07 · 8 versions
, in ubuntu stonking

💖 Email::Address::List — RFC close address list parsing 💖

okay bestie, so the module name line said Email:...::List(3pm) (it's Email::Address::List, the header just gets truncated like that 🙈) — and it lives in the User Contributed Perl Documentation family. Basically: this is the girl who reads your email headers and hands you back a list. Let's go. 🫶

✨ SYNOPSIS ✨

use Email::Address::List;

my $header = <<'END';
Foo Bar <simple@example.com>, (an obsolete comment),,,
 a group:
  a . weird . address @
  for-real .biz
 ; invalid thingy, <
 more@example.com
>
END

my @list = Email::Address::List->parse($header);
foreach my $e ( @list ) {
    if ($e->{'type'} eq 'mailbox') {
        print "an address: ", $e->{'value'}->format ,"\n";
    }
    else {
        print $e->{'type'}, "\n"
    }
}

# prints:
# an address: "Foo Bar" <simple@example.com>
# comment
# group start
# an address: a.weird.address@forreal.biz
# group end
# unknown
# an address: more@example.com

like, look at that header. it's a mess. it's giving "written by a 2004 mail client having a crisis". and this module just... handles it. no notes. 👑

🌸 DESCRIPTION 🌸

She's a parser for From, To, Cc, Bcc, Reply-To, Sender and all of those prefixed with Resent- (eg Resent-From) headers. that's the job. that's the whole job. 💅

🧚 REASONING 🧚

so Email::Address is lowkey great at pulling addresses out of literally any text, even text that just mentions headers — and ngl, this module is derived work from Email::Address. credit where credit is due, bestie. 🎀

BUT. the headers we talked about are structured, okay? they're not vibes, they're lists of addresses. and most of the time you wanna parse that whole field from start to end, keeping everything, even if an entry is invalid input. no throwing away the messy parts. we keep them. we archive them. we put them in the group chat. ✨

🌈 METHODS 🌈

💌 parse

a class method that takes a header value (w/o name and :) plus a set of named options, like so:

my @list = Email::Address::List->parse( $line, option => 1 );

it returns a list of hashes. every hash has at least a 'type' key that tells you what that entry is. the types are:

📬 mailbox

a mailbox entry, with an Email::Address object hanging out under the value key.

if the mailbox has obsolete parts, then 'obsolete' is true. 👀

if the address — and bestie I mean the actual address (local-part@domain), not the display-name/phrase, not the comments — contains not-ASCII chars, then 'not_ascii' gets set to true. per RFC 5322, not-ASCII chars are not allowed inside a mailbox. however, it's not a big deal if people use them, and honestly RFC 6532 extends a few rules from 5322 with UTF8-non-ascii, so. either use the feature, or just yeet those addresses away with the skip_not_ascii option. your call, you're the main character. 💅

whitespace and Unicode format characters (category "\p{Cf}": ZERO WIDTH SPACE, ZWJ, ZWNJ, BOM, soft hyphen, bidi marks, etc.) are stripped from "local-part" and "domain". why? because those characters typically get introduced by copy/paste, and if you leave them in, you produce undeliverable mail. not the vibe. 😭 the stripping does not apply inside quoted local-parts (their contents are preserved literally), and it does not touch the display-name or the comments.

👯 group start

some headers with mailboxes may contain groupped addresses. this element comes back at the position where a group starts. under the value key you find the name of the group.

NOTE that value is not post processed at the moment, so it may contain spaces, comments, quoted strings and other noise. the author is willing to take patches and warns that this will be changed at some point without additional notifications — so if you need groups info, you better send a patch :) 💀

groups can not be nested, but one field may have multiple groups, or a mix of addresses that are in a group and addresses that aren't in any group.

see the skip_groups option.

🏁 group end

returned when a group ends. that's it. that's the whole thing. slay. ✨

💬 comment

obsolete syntax allows standalone comments between mailboxes that can not be addressed to any mailbox. in those situations a comment comes back as an entry of this type. the comment itself is under value.

❓ unknown

returned if the parser met something that shouldn't be there. she tries to recover by jumping over to the next comma (or semicolon if inside a group) that is out quoted string or comment — so the string "foo, bar, baz" results in three unknown entries. jumping over comments and quoted strings means the parser is very sensitive to unbalanced quotes and parens, but it's on purpose. periodt. 🔥

it can be controlled which elements are skipped, for example:

Email::Address::List->parse($line, skip_unknown => 1, ...);

🚫 skip_comments

skips comments between mailboxes. comments inside and next to a mailbox are not skipped — they come back as part of the mailbox entry.

🚫 skip_not_ascii

skips mailboxes where the address part has not ASCII characters.

🚫 skip_groups

skips group start and group end elements — however, emails within groups are still returned. 💖

🚫 skip_unknown

skip anything that is not recognizable. it still tries to recover as described earlier. no cap.

👑 AUTHOR 👑

Best Practical Solutions, LLC <modules@bestpractical.com>

🐛 BUGS 🐛

all bugs should be reported via email to

L<bug-Email-Address-List@rt.cpan.org|mailto:bug-Email-Address-List@rt.cpan.org>

or via the web at

L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=Email-Address-List>.

Copyright (C) 2012-2026 Best Practical Solutions, LLC.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page bestie 🫶 this beauty shipped as perl v5.40.1 and got dated 2026-06-12 down there in the footer next to that Email:...::List(3pm) tag — so yeah, iconic, historic, and she knows it. 🌟💜

📦 where this page comes from