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

NAME

6       Mail::Identity - an e-mail role
7

INHERITANCE

9        Mail::Identity
10          is an User::Identity::Item
11

SYNOPSIS

13        use User::Identity;
14        use Mail::Identity;
15        my $me   = User::Identity->new(...);
16        my $addr = Mail::Identity->new(address => 'x@y');
17        $me->add(email => $addr);
18
19        # Simpler
20
21        use User::Identity;
22        my $me   = User::Identity->new(...);
23        my $addr = $me->add(email => 'x@y');
24        my $addr = $me->add( email => 'home'
25                           , address => 'x@y');
26
27        # Conversion
28        my $ma   = Mail::Address->new(...);
29        my $mi   = Mail::Identity->coerce($ma);
30

DESCRIPTION

32       The "Mail::Identity" object contains the description of role played by
33       a human when sending e-mail.  Most people have more than one role these
34       days: for instance, a private and a company role with different e-mail
35       addresses.
36
37       An "Mail::Identity" object combines an e-mail address, user description
38       ("phrase"), a signature, pgp-key, and so on.  All fields are optional,
39       and some fields are smart.  One such set of data represents one role.
40       "Mail::Identity" is therefore the smart cousine of the Mail::Address
41       object.
42
43       Extends "DESCRIPTION" in User::Identity::Item.
44

METHODS

46       Extends "METHODS" in User::Identity::Item.
47
48   Constructors
49       Extends "Constructors" in User::Identity::Item.
50
51       Mail::Identity->new( [$name], %options )
52            -Option      --Defined in          --Default
53             address                             <username@domain or name>
54             charset                             <user's charset>
55             comment                             <user's fullname if phrase is different>
56             description   User::Identity::Item  undef
57             domain                              <from email or localhost>
58             language                            <from user>
59             location                            <random user's location>
60             name          User::Identity::Item  <phrase or user's fullName>
61             organization                        <location's organization>
62             parent        User::Identity::Item  undef
63             pgp_key                             undef
64             phrase                              <user's fullName>
65             signature                           undef
66             username                            <from address or user's nickname>
67
68           address => STRING
69             The e-mail address is constructed from the username/domain, but
70             when both do not exist, the name is taken.
71
72           charset => STRING
73           comment => STRING
74           description => STRING
75           domain => STRING
76           language => STRING
77           location => NAME|OBJECT
78             The user's location which relates to this mail identity.  This
79             can be specified as location name (which will be looked-up when
80             needed), or as User::Identity::Location object.
81
82           name => STRING
83           organization => STRING
84             Usually defined for e-mail addresses which are used by a company
85             or other organization, but less common for personal addresses.
86             This value will be used to fill the "Organization" header field
87             of messages.
88
89           parent => OBJECT
90           pgp_key => STRING|FILENAME
91           phrase => STRING
92           signature => STRING
93           username => STRING
94
95   Attributes
96       Extends "Attributes" in User::Identity::Item.
97
98       $obj->address()
99           Returns the e-mail address for this role.  If none was specified,
100           it will be constructed from the username and domain.  If those are
101           not present as well, then the name() is used when it contains a
102           "@", else the user's nickname is taken.
103
104       $obj->charset()
105           Returns the character set used in comment and phrase.  When set to
106           "undef", the strings (are already encoded to) contain only ASCII
107           characters.  This defaults to the value of the user's charset, if a
108           user is defined.
109
110       $obj->comment( [STRING] )
111           E-mail address -when included in message MIME headers- can contain
112           a comment.  The RFCs advice not to store useful information in
113           these comments, but it you really want to, you can do it.  The
114           comment defaults to the user's fullname if the phrase is not the
115           fullname and there is a user defined.
116
117           Comments will be enclosed in parenthesis when used. Parenthesis
118           (matching) or non-matching) which are already in the string will
119           carefully escaped when needed.  You do not need to worry.
120
121       $obj->description()
122           Inherited, see "Attributes" in User::Identity::Item
123
124       $obj->domain()
125           The domain is the part of the e-mail address after the "@"-sign.
126           When this is not defined, it can be deducted from the email address
127           (see address()).  If nothing is known, "localhost" is returned.
128
129       $obj->language()
130           Returns the language which is used for the description fields of
131           this e-mail address, which defaults to the user's language.
132
133       $obj->location()
134           Returns the object which describes to which location this mail
135           address relates.  The location may be used to find the name of the
136           organization involved, or to create a signature.  If no location is
137           specified, but a user is defined which has locations, one of those
138           is randomly chosen.
139
140       $obj->name( [$newname] )
141           Inherited, see "Attributes" in User::Identity::Item
142
143       $obj->organization()
144           Returns the organization which relates to this e-mail identity.  If
145           not explicitly specified, it is tried to be found via the location.
146
147       $obj->phrase()
148           The phrase is used in an e-mail address to explain who is sending
149           the message.  This usually is the fullname (the user's fullname is
150           used by default), description of your function (Webmaster), or any
151           other text.
152
153           When an email string is produced, the phase will be quoted if
154           needed.  Quotes which are within the string will automatically be
155           escaped, so you do no need to worry: input cannot break the
156           outcome!
157
158       $obj->username()
159           Returns the username of this e-mail address.  If none is specified,
160           first it is tried to extract it from the specified e-mail address.
161           If there is also no username in the e-mail address, the user
162           identity's nickname is taken.
163
164   Collections
165       Extends "Collections" in User::Identity::Item.
166
167       $obj->add($collection, $role)
168           Inherited, see "Collections" in User::Identity::Item
169
170       $obj->addCollection( $object | <[$type], %options> )
171           Inherited, see "Collections" in User::Identity::Item
172
173       $obj->collection($name)
174           Inherited, see "Collections" in User::Identity::Item
175
176       $obj->parent( [$parent] )
177           Inherited, see "Collections" in User::Identity::Item
178
179       $obj->removeCollection($object|$name)
180           Inherited, see "Collections" in User::Identity::Item
181
182       $obj->type()
183       Mail::Identity->type()
184           Inherited, see "Collections" in User::Identity::Item
185
186       $obj->user()
187           Inherited, see "Collections" in User::Identity::Item
188
189   Searching
190       Extends "Searching" in User::Identity::Item.
191
192       $obj->find($collection, $role)
193           Inherited, see "Searching" in User::Identity::Item
194

DIAGNOSTICS

196       Error: $object is not a collection.
197           The first argument is an object, but not of a class which extends
198           User::Identity::Collection.
199
200       Error: Cannot load collection module for $type ($class).
201           Either the specified $type does not exist, or that module named
202           $class returns compilation errors.  If the type as specified in the
203           warning is not the name of a package, you specified a nickname
204           which was not defined.  Maybe you forgot the 'require' the package
205           which defines the nickname.
206
207       Error: Creation of a collection via $class failed.
208           The $class did compile, but it was not possible to create an object
209           of that class using the options you specified.
210
211       Error: Don't know what type of collection you want to add.
212           If you add a collection, it must either by a collection object or a
213           list of options which can be used to create a collection object.
214           In the latter case, the type of collection must be specified.
215
216       Warning: No collection $name
217           The collection with $name does not exist and can not be created.
218

SEE ALSO

220       This module is part of User-Identity distribution version 1.00, built
221       on October 14, 2020. Website: http://perl.overmeer.net/CPAN/
222

LICENSE

224       Copyrights 2003-2020 by [Mark Overmeer <markov@cpan.org>]. For other
225       contributors see ChangeLog.
226
227       This program is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
229
230
231
232perl v5.32.1                      2021-01-27                 Mail::Identity(3)
Impressum