=encoding utf8

=head1 NAME

Mail::Address - parse mail addresses

=head1 SYNOPSIS

 use Mail::Address;
 my @addrs = Mail::Address->parse($line);

 foreach $addr (@addrs) {
     print $addr->format,"\n";
 }

=head1 DESCRIPTION

C<Mail::Address> extracts and manipulates email addresses from a message
header.  It cannot be used to extract addresses from some random text.
You can use this module to create RFC822 compliant fields.

Although C<Mail::Address> is a very popular subject for books, and is
used in many applications, it does a very poor job on the more complex
message fields.  It does only handle simple address formats (which
covers about 95% of what can be found). Problems are with

=over 4

=item *

no support for address groups, even not with the semi-colon as
separator between addresses;

=item *

limited support for escapes in phrases and comments.  There are
cases where it can get wrong; and

=item *

you have to take care of most escaping when you create an address yourself:
C<Mail::Address> does not do that for you.

=back

Often requests are made to the maintainers of this code improve this
situation, but this is not a good idea, where it will break zillions
of existing applications.  If you wish for a fully RFC2822 compliant
implementation you may take a look at L<Mail::Message::Field::Full>,
part of MailBox.

B<. Example>

  my $s = Mail::Message::Field::Full->new($from_header);
  # ref $s isa Mail::Message::Field::Addresses;

  my @g = $s->groups;          # all groups, at least one
  # ref $g[0] isa Mail::Message::Field::AddrGroup;
  my $ga = $g[0]->addresses;   # group addresses

  my @a = $s->addresses;       # all addresses
  # ref $a[0] isa Mail::Message::Field::Address;

=head1 METHODS

=head2 Constructors

=over 4

=item Mail::Address-E<gt>B<new>( $phrase, $address, [ $comment ] )

Create a new C<Mail::Address> object which represents an address with the
elements given. In a message these 3 elements would be seen like:

 PHRASE <ADDRESS> (COMMENT)
 ADDRESS (COMMENT)

example: 

 Mail::Address->new("Perl5 Porters", "perl5-porters@africa.nicoh.com");

=item $obj-E<gt>B<parse>($line)

Parse the given line a return a list of extracted C<Mail::Address> objects.
The line would normally be one taken from a To,Cc or Bcc line in a message

example: 

 my @addr = Mail::Address->parse($line);

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<address>()

Return the address part of the object.

=item $obj-E<gt>B<comment>()

Return the comment part of the object

=item $obj-E<gt>B<format>(@addresses)

Return a string representing the address in a suitable form to be placed
on a C<To>, C<Cc>, or C<Bcc> line of a message.  This method is called on
the first address to be used; other specified addresses will be appended,
separated by commas.

=item $obj-E<gt>B<phrase>()

Return the phrase part of the object.

=back

=head2 Smart accessors

=over 4

=item $obj-E<gt>B<host>()

Return the address excluding the user id and '@'

=item $obj-E<gt>B<name>()

Using the information contained within the object attempt to identify what
the person or groups name is.

B<Note:> This function tries to be smart with the "phrase" of the
email address, which is probably a very bad idea.  Consider to use
L<phrase()|Mail::Address/"Accessors"> itself.

=item $obj-E<gt>B<user>()

Return the address excluding the '@' and the mail domain

=back

=head1 SEE ALSO

This module is part of the MailTools distribution,
F<http://perl.overmeer.net/mailtools/>.

=head1 AUTHORS

The MailTools bundle was developed by Graham Barr.  Later, Mark
Overmeer took over maintenance without commitment to further development.

Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
For other contributors see ChangeLog.

=head1 LICENSE

Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
2001-2024 Mark Overmeer E<lt>perl@overmeer.netE<gt>.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>