Mail::Identity(3pm)

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

METHODS

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

DIAGNOSTICS

228       Error: $object is not a collection.
229
230       The first argument is an object, but not of a class which extends
231       User::Identity::Collection.
232
233       Error: Cannot load collection module for $type ($class).
234
235       Either the specified $type does not exist, or that module named $class
236       returns compilation errors.  If the type as specified in the warning is
237       not the name of a package, you specified a nickname which was not
238       defined.  Maybe you forgot the 'require' the package which defines the
239       nickname.
240
241       Error: Creation of a collection via $class failed.
242
243       The $class did compile, but it was not possible to create an object of
244       that class using the options you specified.
245
246       Error: Don't know what type of collection you want to add.
247
248       If you add a collection, it must either by a collection object or a
249       list of options which can be used to create a collection object.  In
250       the latter case, the type of collection must be specified.
251
252       Warning: No collection $name
253
254       The collection with $name does not exist and can not be created.
255

LICENSE

261       Copyrights 2003,2004,2007 by Mark Overmeer <perl@overmeer.net>.For
262       other contributors see Changes.
263
264       This program is free software; you can redistribute it and/or modify it
265       under the same terms as Perl itself.  See
266       http://www.perl.com/perl/misc/Artistic.html
267
268
269
270perl v5.8.8                       2007-01-08                 Mail::Identity(3)