Mail::Address(3pm)

1Mail::Address(3)      User Contributed Perl Documentation     Mail::Address(3)
2
3
4

NAME

6       Mail::Address - Parse mail addresses
7

INHERITANCE

SYNOPSIS

10        use Mail::Address;
11        my @addrs = Mail::Address->parse($line);
12
13        foreach $addr (@addrs) {
14            print $addr->format,"\n";
15        }
16

DESCRIPTION

18       "Mail::Address" extracts and manipulates email addresses from a message
19       header.  It cannot be used to extract addresses from some random text.
20       You can use this module to create RFC822 compliant fields.
21
22       Although "Mail::Address" is a very popular subject for books, and is
23       used in many applications, it does a very poor job on the more complex
24       message fields.  It does only handle simple address formats (which
25       covers about 95% of what can be found). Problems are with
26
27       ·   no support for address groups, even not with the semi-colon as
28           separator between addresses;
29
30       ·   limitted support for escapes in phrases and comments.  There are
31           cases where it can get wrong; and
32
33       ·   you have to take care of most escaping when you create an address
34           yourself: "Mail::Address" does not do that for you.
35
36       Often requests are made to the maintainers of this code improve this
37       situation, but this is not a good idea, where it will break zillions of
38       existing applications.  If you wish for a fully RFC2822 compliant
39       implementation you may take a look at Mail::Message::Field::Full, part
40       of MailBox.
41
42       example:
43
44         my $s = Mail::Message::Field::Full->parse($header);
45         # ref $s isa Mail::Message::Field::Addresses;
46
47         my @g = $s->groups;          # all groups, at least one
48         # ref $g[0] isa Mail::Message::Field::AddrGroup;
49         my $ga = $g[0]->addresses;   # group addresses
50
51         my @a = $s->addresses;       # all addresses
52         # ref $a[0] isa Mail::Message::Field::Address;
53

METHODS

55   Constructors
56       Mail::Address->new(PHRASE, ADDRESS, [ COMMENT ])
57
58           Create a new "Mail::Address" object which represents an address
59           with the elements given. In a message these 3 elements would be
60           seen like:
61
62            PHRASE <ADDRESS> (COMMENT)
63            ADDRESS (COMMENT)
64
65           example:
66
67            Mail::Address->new("Perl5 Porters", "perl5-porters@africa.nicoh.com");
68
69       $obj->parse(LINE)
70
71           Parse the given line a return a list of extracted "Mail::Address"
72           objects.  The line would normally be one taken from a To,Cc or Bcc
73           line in a message
74
75           example:
76
77            my @addr = Mail::Address->parse($line);
78
79   Accessors
80       $obj->address
81
82           Return the address part of the object.
83
84       $obj->comment
85
86           Return the comment part of the object
87
88       $obj->format([ADDRESSes])
89
90           Return a string representing the address in a suitable form to be
91           placed on a "To", "Cc", or "Bcc" line of a message.  This method is
92           called on the first ADDRESS to be used; other specified ADDRESSes
93           will be appended, separated with commas.
94
95       $obj->phrase
96
97           Return the phrase part of the object.
98
99   Smart accessors
100       $obj->host
101
102           Return the address excluding the user id and '@'
103
104       $obj->name
105
106           Using the information contained within the object attempt to
107           identify what the person or groups name is.
108
109       $obj->user
110
111           Return the address excluding the '@' and the mail domain
112

AUTHORS

118       The MailTools bundle was developed by Graham Barr.  Later, Mark
119       Overmeer took over maintenance without commitment to further
120       development.
121
122       Mail::Cap by Gisle Aas <aas@oslonett.no>.  Mail::Field::AddrList by
123       Peter Orbaek <poe@cit.dk>.  Mail::Mailer and Mail::Send by Tim Bunce
124       <Tim.Bunce@ig.co.uk>.  For other contributors see ChangeLog.
125

LICENSE

127       Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2007 Mark
128       Overmeer <perl@overmeer.net>.
129
130       This program is free software; you can redistribute it and/or modify it
131       under the same terms as Perl itself.  See
132       http://www.perl.com/perl/misc/Artistic.html
133
134
135
136perl v5.10.1                      2008-07-29                  Mail::Address(3)