
=head1 NAME

Mail::Identity - an e-mail role

=head1 CLASS INHERITANCE

 Mail::Identity
   is a User::Identity::Collection::Item

=head1 SYNOPSIS

 use User::Identity;
 use Mail::Identity;
 my $me   = User::Indentity->new(...);
 my $addr = Mail::Identity->new(...);
 $me->add(email => $addr);

 # Simpler

 use User::Identity;
 my $me   = User::Indentity->new(...);
 my $addr = $me->add(email => ...);

=head1 DESCRIPTION

The Mail::Identity object contains the description of role played by
a human when sending e-mail.  Most people have more than one role these
days: for instance, a private and a company role with different e-mail
addresses.

An Mail::Internet object combines an e-mail address, user description
("phrase"), a signature, pgp-key, and so on.  All fields are optional,
and some fields are smart.  One such set of data represents one role.
Mail::Internet is therefore the smart cousine of the Mail::Address object.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> [NAME], OPTIONS

(Class method)

 OPTION               DEFAULT
 comment              <user's fullname if phrase is different>
 domainname           <from email or localhost>
 email                <username@domainname>
 location             <random user's location>
 name                 <required>
 organization         <location's organization>
 pgp_key              undef
 phrase               <user's fullName>
 signature            undef
 user                 undef
 username             <from email or user's nickname>

=over 4

=item B<comment> =E<gt> STRING

=item B<domainname> =E<gt> STRING

=item B<email> =E<gt> STRING

=item B<location> =E<gt> NAME|OBJECT

The user's location which relates to this mail identity.  This can be
specified as location name (which will be looked-up when needed), or
as User::Identity::Location object.

=item B<name> =E<gt> STRING

See User::Identity::Collection::Item::new(name)

=item B<organization> =E<gt> STRING

Usually defined for e-mail addresses which are used by a company or
other organization, but less common for personal addresses.  This
value will be used to fill the C<Organization> header field of messages.

=item B<pgp_key> =E<gt> STRING|FILENAME

=item B<phrase> =E<gt> STRING

=item B<signature> =E<gt> STRING

=item B<user> =E<gt> OBJECT

See User::Identity::Collection::Item::new(user)

=item B<username> =E<gt> STRING

=back

=back

=head2 Attributes

=over 4

=item B<comment> 

E-mail address -when included in message MIME headers- can contain a comment.
The RFCs advice not to store useful information in these comments, but it
you really want to, you can do it.  The comment defaults to the user's
fuilname if the phrase is not the fullname and there is a user defined.

=item B<domainname> 

The domainname is the part of the e-mail address after the C<@>-sign.  When this
is not defined, it can be deducted from the email address (see email()).  If
nothing is known, C<localhost> is returned.

=item B<email> 

Returns the e-mail address for this role.  If none was specified, it will
be constructed from the username and domainname.

=item B<location> 

Returns the object which describes to which location this mail address relates.
The location may be used to find the name of the organization involved, or
to create a signature.  If no location is specified, but a user is defined
which has locations, one of those is randomly chosen.

=item B<name> 

See User::Identity::Collection::Item::name()

=item B<organization> 

Returns the organization which relates to this e-mail identity.  If not
explicitly specified, it is tried to be found via the location.

=item B<phrase> 

The phrase is used in an e-mail address to explain who is sending the
message.  This usually is the fullname (the user's fullname is used by
default), description of your function (Webmaster), or any other text.

=item B<user> [USER]

See User::Identity::Collection::Item::user()

=item B<username> 

Returns the username of this e-mail address.  If none is specified, first
it is tried to extract it from the specified e-mail address.  If there is
also no username in the e-mail address, the user identity's nickname is
taken.

=back

=head1 SEE ALSO

See the website at L<http://perl.overmeer.net/userid/>.

=head1 AUTHOR

Written by Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 0.02.

Copyright (c) 2003 by the authors. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
