=encoding utf8

=head1 NAME

Mail::Message::Field::Address - One e-mail address

=head1 INHERITANCE

 Mail::Message::Field::Address
   is a Mail::Identity
   is a User::Identity::Item

=head1 SYNOPSIS

  my $addr = Mail::Message::Field::Address->new(...);

  my $ui   = User::Identity->new(...);
  my $addr = Mail::Message::Field::Address->coerce($ui);

  my $mi   = Mail::Identity->new(...);
  my $addr = Mail::Message::Field::Address->coerce($mi);

  print $addr->address;
  print $addr->fullName;   # possibly unicode!
  print $addr->domain;

=head1 DESCRIPTION

Many header fields can contain e-mail addresses.  Each e-mail address
can be represented by an object of this class.  These objects will
handle interpretation and character set encoding and decoding for you.

Extends L<"DESCRIPTION" in Mail::Identity|Mail::Identity/"DESCRIPTION">.

=head1 OVERLOADED

=over 4

=item overload: B<""> stringification

When the object is used in string context, it will return the encoded
representation of the e-mail address, just like L<string()|Mail::Message::Field::Address/"Access to the content"> does.

=item overload: B<boolean> true/falase

The object used as boolean will always return C<true>

=item overload: B<cmp> string comparison

Two address objects are the same when their email addresses are the same.

=back

=head1 METHODS

Extends L<"METHODS" in Mail::Identity|Mail::Identity/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in Mail::Identity|Mail::Identity/"Constructors">.

=over 4

=item $obj-E<gt>B<coerce>( <STRING|$object>, %options )

Try to coerce the C<$object> into a C<Mail::Message::Field::Address>.
In case of a C<STRING>, it is interpreted as an email address.

The C<%options> are passed to the object creation, and overrule the values
found in the C<$object>.  The result may be C<undef> or a newly created
object.  If the C<$object> is already of the correct type, it is returned
unmodified.

The C<$object> may currently be a L<Mail::Address|Mail::Address>, a L<Mail::Identity|Mail::Identity>, or
a L<User::Identity|User::Identity>.  In case of the latter, one of the user's addresses
is chosen at random.

=item $class-E<gt>B<new>( [$name], %options )

Inherited, see L<Mail::Identity/"Constructors">

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

Parse the string for an address.  You never know whether one or more
addresses are specified on a line (often applications are wrong), therefore,
the C<STRING> is first parsed for as many addresses as possible and then the
one is taken at random.

=back

=head2 Attributes

Extends L<"Attributes" in Mail::Identity|Mail::Identity/"Attributes">.

=over 4

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<User::Identity::Item/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<User::Identity::Item/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

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

Inherited, see L<Mail::Identity/"Attributes">

=back

=head2 Collections

Extends L<"Collections" in Mail::Identity|Mail::Identity/"Collections">.

=over 4

=item $obj-E<gt>B<add>($collection, $role)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<addCollection>( $object | <[$type], %options> )

Inherited, see L<User::Identity::Item/"Collections">

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

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<parent>( [$parent] )

Inherited, see L<User::Identity::Item/"Collections">

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

Inherited, see L<User::Identity::Item/"Collections">

=item $any-E<gt>B<type>()

Inherited, see L<User::Identity::Item/"Collections">

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

Inherited, see L<User::Identity::Item/"Collections">

=back

=head2 Searching

Extends L<"Searching" in Mail::Identity|Mail::Identity/"Searching">.

=over 4

=item $obj-E<gt>B<find>($collection, $role)

Inherited, see L<User::Identity::Item/"Searching">

=back

=head2 Accessors

=over 4

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

Character-set encoding, like 'q' and 'b', to be used when non-ascii
characters are to be transmitted.

=back

=head2 Access to the content

=over 4

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

Returns an RFC compliant e-mail address, which will have character
set encoding if needed.  The objects are also overloaded to call
this method in string context.

» example: 

  print $address->string;
  print $address;          # via overloading

=back

=head1 DIAGNOSTICS

=over 4

=item Error: cannot coerce a $type into a $class

When addresses are specified to be included in header fields, they may
be coerced into L<Mail::Message::Field::Address|Mail::Message::Field::Address> objects first.  What
you specify is not accepted as address specification.  This may be an
internal error.
Cast by C<coerce()>

=item Error: cannot load collection module for $type ($class): $@

Either the specified C<$type> does not exist, or that module named C<$class> returns
compilation errors.  If the type as specified in the warning is not
the name of a package, you specified a nickname which was not defined.
Maybe you forgot the 'require' the package which defines the nickname.
Cast by C<addCollection()>

=item Error: invalid collection $name.

The collection with C<$name> does not exist and can not be created.
Cast by C<add()>

=item Error: this $object is not a collection.

Cast by C<addCollection()>

=back

=head1 SEE ALSO

This module is part of Mail-Message version 4.03,
built on January 26, 2026. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer.

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

