1Email::Address::List(3)User Contributed Perl DocumentatioEnmail::Address::List(3)
2
6 Email::Address::List - RFC close address list parsing
7
9 use Email::Address::List;
10 my $header = <<'END';
12 Foo Bar <simple@example.com>, (an obsolete comment),,,
13 a group:
14 a . weird . address @
15 for-real .biz
16 ; invalid thingy, <
17 more@example.com
18 >
19 END
20 my @list = Email::Address::List->parse($header);
22 foreach my $e ( @list ) {
23 if ($e->{'type'} eq 'mailbox') {
24 print "an address: ", $e->{'value'}->format ,"\n";
25 }
26 else {
27 print $e->{'type'}, "\n"
28 }
29 }
30 # prints:
32 # an address: "Foo Bar" <simple@example.com>
33 # comment
34 # group start
35 # an address: a.weird.address@forreal.biz
36 # group end
37 # unknown
38 # an address: more@example.com
39
41 Parser for From, To, Cc, Bcc, Reply-To, Sender and previous prefixed
42 with Resent- (eg Resent-From) headers.
43
45 Email::Address is good at parsing addresses out of any text even
46 mentioned headers and this module is derived work from Email::Address.
47 However, mentioned headers are structured and contain lists of
49 addresses. Most of the time you want to parse such field from start to
50 end keeping everything even if it's an invalid input.
51
53 parse
54 A class method that takes a header value (w/o name and :) and a set of
55 named options, for example:
56 my @list = Email::Address::List->parse( $line, option => 1 );
58 Returns list of hashes. Each hash at least has 'type' key that
60 describes the entry. Types:
61 mailbox
63 A mailbox entry with Email::Address object under value key.
64 If mailbox has obsolete parts then 'obsolete' is true.
66 If address (not display-name/phrase or comments, but
68 local-part@domain) contains not ASCII chars then 'not_ascii' is set
69 to true. According to RFC 5322 not ASCII chars are not allowed
70 within mailbox. However, there are no big problems if those are
71 used and actually RFC 6532 extends a few rules from 5322 with
72 UTF8-non-ascii. Either use the feature or just skip such addresses
73 with skip_not_ascii option.
74 group start
76 Some headers with mailboxes may contain groupped addresses. This
77 element is returned for position where group starts. Under value
78 key you find name of the group. NOTE that value is not post
79 processed at the moment, so it may contain spaces, comments, quoted
80 strings and other noise. Author willing to take patches and warns
81 that this will be changed at some point without additional
82 notifications, so if you need groups info then you better send a
83 patch :)
84 Groups can not be nested, but one field may have multiple groups or
86 mix of addresses that are in a group and not in any.
87 See skip_groups option.
89 group end
91 Returned when a group ends.
92 comment
94 Obsolete syntax allows one to use standalone comments between
95 mailboxes that can not be addressed to any mailbox. In such
96 situations a comment returned as an entry of this type. Comment
97 itself is under value.
98 unknown
100 Returned if parser met something that shouldn't be there. Parser
101 tries to recover by jumping over to next comma (or semicolon if
102 inside group) that is out quoted string or comment, so "foo, bar,
103 baz" string results in three unknown entries. Jumping over comments
104 and quoted strings means that parser is very sensitive to
105 unbalanced quotes and parens, but it's on purpose.
106 It can be controlled which elements are skipped, for example:
108 Email::Address::List->parse($line, skip_unknown => 1, ...);
110 skip_comments
112 Skips comments between mailboxes. Comments inside and next to a
113 mailbox are not skipped, but returned as part of mailbox entry.
114 skip_not_ascii
116 Skips mailboxes where address part has not ASCII characters.
117 skip_groups
119 Skips group starts and end elements, however emails within groups
120 are still returned.
121 skip_unknown
123 Skip anything that is not recognizable. It still tries to recover
124 as described earlier.
125
127 Ruslan Zakirov <ruz@bestpractical.com>
128
130 Under the same terms as Perl itself.
131perl v5.36.0 2023-01-20 Email::Address::List(3)