1Mail::Identity(3) User Contributed Perl Documentation Mail::Identity(3)
2
6 Mail::Identity - an e-mail role
7
9 Mail::Identity
10 is an User::Identity::Item
11
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 # Simpler
20 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 # Conversion
28 my $ma = Mail::Address->new(...);
29 my $mi = Mail::Identity->coerce($ma);
30
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 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 Extends "DESCRIPTION" in User::Identity::Item.
44
46 Extends "METHODS" in User::Identity::Item.
47 Constructors
49 Extends "Constructors" in User::Identity::Item.
50 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 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 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 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 parent => OBJECT
90 pgp_key => STRING|FILENAME
91 phrase => STRING
92 signature => STRING
93 username => STRING
94 Attributes
96 Extends "Attributes" in User::Identity::Item.
97 $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 $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 $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 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 $obj->description()
122 Inherited, see "Attributes" in User::Identity::Item
123 $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 $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 $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 $obj->name( [$newname] )
141 Inherited, see "Attributes" in User::Identity::Item
142 $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 $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 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 $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 Collections
165 Extends "Collections" in User::Identity::Item.
166 $obj->add($collection, $role)
168 Inherited, see "Collections" in User::Identity::Item
169 $obj->addCollection( $object | <[$type], %options> )
171 Inherited, see "Collections" in User::Identity::Item
172 $obj->collection($name)
174 Inherited, see "Collections" in User::Identity::Item
175 $obj->parent( [$parent] )
177 Inherited, see "Collections" in User::Identity::Item
178 $obj->removeCollection($object|$name)
180 Inherited, see "Collections" in User::Identity::Item
181 $obj->type()
183 Mail::Identity->type()
184 Inherited, see "Collections" in User::Identity::Item
185 $obj->user()
187 Inherited, see "Collections" in User::Identity::Item
188 Searching
190 Extends "Searching" in User::Identity::Item.
191 $obj->find($collection, $role)
193 Inherited, see "Searching" in User::Identity::Item
194
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 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 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 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 Warning: No collection $name
217 The collection with $name does not exist and can not be created.
218
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
224 Copyrights 2003-2020 by [Mark Overmeer <markov@cpan.org>]. For other
225 contributors see ChangeLog.
226 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/
229perl v5.32.1 2021-01-27 Mail::Identity(3)