1Mail::Box::IMAP4::MessaUgsee(r3)Contributed Perl DocumenMtaaitli:o:nBox::IMAP4::Message(3)
2
6 Mail::Box::IMAP4::Message - one message on a IMAP4 server
7
9 Mail::Box::IMAP4::Message
10 is a Mail::Box::Net::Message
11 is a Mail::Box::Message
12 is a Mail::Message
13 is a Mail::Reporter
14
16 my $folder = new Mail::Box::IMAP4 ...
17 my $message = $folder->message(10);
18
20 A "Mail::Box::IMAP4::Message" represents one message on a IMAP4 server,
21 maintained by a Mail::Box::IMAP4 folder. Each message is stored as
22 separate entity on the server, and maybe temporarily in your program as
23 well.
24
26 Constructors
27 $obj->clone(OPTIONS)
28 See "Constructors" in Mail::Message
29 Mail::Box::IMAP4::Message->new(OPTIONS)
31 -Option --Defined in --Default
32 body Mail::Message undef
33 body_type Mail::Box::Message Mail::Message::Body::Lines
34 cache_body <false>
35 cache_head <false>
36 cache_labels <false>
37 deleted Mail::Message <false>
38 field_type Mail::Message undef
39 folder Mail::Box::Message <required>
40 head Mail::Message undef
41 head_type Mail::Message Mail::Message::Head::Complete
42 labels Mail::Message {}
43 log Mail::Reporter 'WARNINGS'
44 messageId Mail::Message undef
45 modified Mail::Message <false>
46 size Mail::Box::Message undef
47 trace Mail::Reporter 'WARNINGS'
48 trusted Mail::Message <false>
49 unique Mail::Box::Net::Message <unique string>
50 write_labels <true>
51 body => OBJECT
53 body_type => CODE|CLASS
54 cache_body => BOOLEAN
55 cache_head => BOOLEAN
56 cache_labels => BOOLEAN
57 All standard IMAP labels can be cached on the local server to
58 improve speed. This has the same dangers as setting
59 "write_labels" to false. The caching starts when the first label
60 of the message was read.
61 deleted => BOOLEAN
63 field_type => CLASS
64 folder => FOLDER
65 head => OBJECT
66 head_type => CLASS
67 labels => ARRAY|HASH
68 log => LEVEL
69 messageId => STRING
70 modified => BOOLEAN
71 size => INTEGER
72 trace => LEVEL
73 trusted => BOOLEAN
74 unique => STRING
75 write_labels => BOOLEAN
76 When a label is changed or its value read, using label(), that
77 info should be sent to the IMAP server. But, this action could
78 be superfluous, for instance because the label was already set or
79 clear, and communication is expensive. On the other hand,
80 someone else may use IMAP to make changes in the same folder, and
81 will get the updates too late or never...
82 Constructing a message
84 $obj->bounce([RG-OBJECT|OPTIONS])
85 See "Constructing a message" in Mail::Message::Construct::Bounce
86 Mail::Box::IMAP4::Message->build([MESSAGE|PART|BODY], CONTENT)
88 See "Constructing a message" in Mail::Message::Construct::Build
89 Mail::Box::IMAP4::Message->buildFromBody(BODY, [HEAD], HEADERS)
91 See "Constructing a message" in Mail::Message::Construct::Build
92 $obj->forward(OPTIONS)
94 See "Constructing a message" in Mail::Message::Construct::Forward
95 $obj->forwardAttach(OPTIONS)
97 See "Constructing a message" in Mail::Message::Construct::Forward
98 $obj->forwardEncapsulate(OPTIONS)
100 See "Constructing a message" in Mail::Message::Construct::Forward
101 $obj->forwardInline(OPTIONS)
103 See "Constructing a message" in Mail::Message::Construct::Forward
104 $obj->forwardNo(OPTIONS)
106 See "Constructing a message" in Mail::Message::Construct::Forward
107 $obj->forwardPostlude
109 See "Constructing a message" in Mail::Message::Construct::Forward
110 $obj->forwardPrelude
112 See "Constructing a message" in Mail::Message::Construct::Forward
113 $obj->forwardSubject(STRING)
115 See "Constructing a message" in Mail::Message::Construct::Forward
116 Mail::Box::IMAP4::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
118 OPTIONS)
119 See "Constructing a message" in Mail::Message::Construct::Read
120 $obj->rebuild(OPTIONS)
122 See "Constructing a message" in Mail::Message::Construct::Rebuild
123 $obj->reply(OPTIONS)
125 See "Constructing a message" in Mail::Message::Construct::Reply
126 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
128 See "Constructing a message" in Mail::Message::Construct::Reply
129 $obj->replySubject(STRING)
131 Mail::Box::IMAP4::Message->replySubject(STRING)
132 See "Constructing a message" in Mail::Message::Construct::Reply
134 The message
136 $obj->container
137 See "The message" in Mail::Message
138 $obj->copyTo(FOLDER, OPTIONS)
140 See "The message" in Mail::Box::Message
141 $obj->folder([FOLDER])
143 See "The message" in Mail::Box::Message
144 $obj->isDummy
146 See "The message" in Mail::Message
147 $obj->isPart
149 See "The message" in Mail::Message
150 $obj->messageId
152 See "The message" in Mail::Message
153 $obj->moveTo(FOLDER, OPTIONS)
155 See "The message" in Mail::Box::Message
156 $obj->print([FILEHANDLE])
158 See "The message" in Mail::Message
159 $obj->send([MAILER], OPTIONS)
161 See "The message" in Mail::Message
162 $obj->seqnr([INTEGER])
164 See "The message" in Mail::Box::Message
165 $obj->size
167 Returns the size of this message. If the message is still on the
168 remote server, IMAP is used to ask for the size. When the message
169 is already loaded onto the local system, the size of the parsed
170 message is taken. These sizes can differ because the difference in
171 line-ending representation.
172 $obj->toplevel
174 See "The message" in Mail::Message
175 $obj->unique([STRING|undef])
177 See "The message" in Mail::Box::Net::Message
178 $obj->write([FILEHANDLE])
180 See "The message" in Mail::Message
181 The header
183 $obj->bcc
184 See "The header" in Mail::Message
185 $obj->cc
187 See "The header" in Mail::Message
188 $obj->date
190 See "The header" in Mail::Message
191 $obj->destinations
193 See "The header" in Mail::Message
194 $obj->from
196 See "The header" in Mail::Message
197 $obj->get(FIELDNAME)
199 See "The header" in Mail::Message
200 $obj->guessTimestamp
202 See "The header" in Mail::Message
203 $obj->head([HEAD])
205 See "The header" in Mail::Message
206 $obj->nrLines
208 See "The header" in Mail::Message
209 $obj->sender
211 See "The header" in Mail::Message
212 $obj->study(FIELDNAME)
214 See "The header" in Mail::Message
215 $obj->subject
217 See "The header" in Mail::Message
218 $obj->timestamp
220 See "The header" in Mail::Message
221 $obj->to
223 See "The header" in Mail::Message
224 The body
226 $obj->body([BODY])
227 See "The body" in Mail::Message
228 $obj->contentType
230 See "The body" in Mail::Message
231 $obj->decoded(OPTIONS)
233 See "The body" in Mail::Message
234 $obj->encode(OPTIONS)
236 See "The body" in Mail::Message
237 $obj->isMultipart
239 See "The body" in Mail::Message
240 $obj->isNested
242 See "The body" in Mail::Message
243 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
245 See "The body" in Mail::Message
246 Flags
248 $obj->delete
249 See "Flags" in Mail::Message
250 $obj->deleted([BOOLEAN])
252 See "Flags" in Mail::Message
253 $obj->isDeleted
255 See "Flags" in Mail::Message
256 $obj->isModified
258 See "Flags" in Mail::Message
259 $obj->label(LABEL|PAIRS)
261 With only one argument, the value related to LABEL is returned.
262 With more that one argument, the list is interpreted a label-value
263 PAIRS to be set.
264 The IMAP protocol defines its own names for the labels, which must
266 be set imediately to inform other IMAP clients which may have the
267 same folder open. But that can be changed with new(write_labels).
268 Some labels are translated to the corresponding IMAP system labels.
269 $obj->labels
271 Get the names of all labels (LIST context, not efficient in IMAP4),
272 or a reference to a hash with labels. You should only use the
273 returned hash to read the labels, because changes made to it will
274 not be passed to the remote server. See labels() to set values.
275 $obj->labelsToStatus
277 See "Flags" in Mail::Message
278 $obj->modified([BOOLEAN])
280 See "Flags" in Mail::Message
281 $obj->statusToLabels
283 See "Flags" in Mail::Message
284 The whole message as text
286 $obj->file
287 See "The whole message as text" in Mail::Message::Construct::Text
288 $obj->lines
290 See "The whole message as text" in Mail::Message::Construct::Text
291 $obj->printStructure([FILEHANDLE|undef],[INDENT])
293 See "The whole message as text" in Mail::Message::Construct::Text
294 $obj->string
296 See "The whole message as text" in Mail::Message::Construct::Text
297 Internals
299 $obj->clonedFrom
300 See "Internals" in Mail::Message
301 Mail::Box::IMAP4::Message->coerce(MESSAGE, OPTIONS)
303 See "Internals" in Mail::Message
304 $obj->diskDelete
306 See "Internals" in Mail::Box::Message
307 $obj->fetch([INFO, ...])
309 Use the IMAP's "UID FETCH IMAP" command to get some data about this
310 message. The INFO request is passed to Mail::Box::IMAP4::fetch().
311 Without INFO, "ALL" information is retreived and returned as a
312 HASH.
313 $obj->isDelayed
315 See "Internals" in Mail::Message
316 $obj->loadBody
318 See "Internals" in Mail::Box::Net::Message
319 $obj->readBody(PARSER, HEAD [, BODYTYPE])
321 See "Internals" in Mail::Box::Message
322 $obj->readFromParser(PARSER, [BODYTYPE])
324 See "Internals" in Mail::Message
325 $obj->readHead(PARSER [,CLASS])
327 See "Internals" in Mail::Message
328 $obj->recursiveRebuildPart(PART, OPTIONS)
330 See "Internals" in Mail::Message::Construct::Rebuild
331 $obj->storeBody(BODY)
333 See "Internals" in Mail::Message
334 $obj->takeMessageId([STRING])
336 See "Internals" in Mail::Message
337 $obj->writeDelayed(IMAP)
339 Write all delayed information, like label changes, to the server.
340 This is done under force, so should even be done for folders opened
341 without write-access. This method is called indirectly by a
342 Mail::Box::write() or Mail::Box::close().
343 The IMAP argument is a Mail::IMAPClient which has the right folder
345 already selected.
346 Writing changes to the remote folder is not without hassle: IMAP4
348 (or is it only Mail::IMAPClient doesn't support replacing header or
349 body. Therefore, when either of them change, the whole message is
350 rewritten to the server (which is supported), and the original
351 flagged for deletion.
352 Error handling
354 $obj->AUTOLOAD
355 See "METHODS" in Mail::Message::Construct
356 $obj->addReport(OBJECT)
358 See "Error handling" in Mail::Reporter
359 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
361 Mail::Box::IMAP4::Message->defaultTrace([LEVEL]|[LOGLEVEL,
362 TRACELEVEL]|[LEVEL, CALLBACK])
363 See "Error handling" in Mail::Reporter
365 $obj->errors
367 See "Error handling" in Mail::Reporter
368 $obj->log([LEVEL [,STRINGS]])
370 Mail::Box::IMAP4::Message->log([LEVEL [,STRINGS]])
371 See "Error handling" in Mail::Reporter
373 $obj->logPriority(LEVEL)
375 Mail::Box::IMAP4::Message->logPriority(LEVEL)
376 See "Error handling" in Mail::Reporter
378 $obj->logSettings
380 See "Error handling" in Mail::Reporter
381 $obj->notImplemented
383 See "Error handling" in Mail::Reporter
384 $obj->report([LEVEL])
386 See "Error handling" in Mail::Reporter
387 $obj->reportAll([LEVEL])
389 See "Error handling" in Mail::Reporter
390 $obj->shortSize([VALUE])
392 Mail::Box::IMAP4::Message->shortSize([VALUE])
393 See "Error handling" in Mail::Message
395 $obj->shortString
397 See "Error handling" in Mail::Message
398 $obj->trace([LEVEL])
400 See "Error handling" in Mail::Reporter
401 $obj->warnings
403 See "Error handling" in Mail::Reporter
404 Cleanup
406 $obj->DESTROY
407 See "Cleanup" in Mail::Message
408 $obj->destruct
410 See "Cleanup" in Mail::Box::Message
411 $obj->inGlobalDestruction
413 See "Cleanup" in Mail::Reporter
414
416 Structure of a Message
417 The header
418 The body
420 Message object implementation
422 Message class implementation
423 Labels
424 Predefined labels
425 Status and X-Status fields
427 IMAP protocol flags
429 Labels (or flags) are known to all folder formats, but differ how they
431 are stored. Some folder types use message header lines to keep the
432 labels, other use a separate file. The IMAP protocol does not specify
433 how the labels are kept on the server, but does specify how they are
434 named.
435 The label names as defined by the IMAP protocol are standardized into
437 the MailBox standard to hide folder differences. The following
438 translations are always performed:
439 \Seen => seen
441 \Answered => replied
442 \Flagged => flagged
443 \Deleted => deleted
444 \Draft => draft
445 \Recent => NOT old
446 Other labels
448 Of course, your program may be in need for more labels than those
450 provided by the protocol. You can still use these: they stay locally
451 (and are lost when the folder is closed). Some IMAP4 extensions permit
452 more labels than the basic RFC, but that is not yet supported by this
453 implementation.
454 Caching labels
456 When you ask for one or more flags of a message more than once, you may
458 improve the overall performance by setting new(cache_labels) to "YES".
459 However, this may cause inconsistencies when multiple clients use the
460 same folder on the IMAP server.
461 You may also delay the label updates to the server until the folder is
463 closed (or for ever when read-only is required). When
464 Mail::Box::write() or Mail::Box::close() is called, it is decided
465 whether to throw all changes away or write after all.
466
468 Error: Cannot coerce a $class object into a $class object
469 Error: Cannot include forward source as $include.
470 Unknown alternative for the forward(include). Valid choices are
471 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
472 Error: Cannot include reply source as $include.
474 Unknown alternative for the "include" option of reply(). Valid
475 choices are "NO", "INLINE", and "ATTACH".
476 Error: Method bounce requires To, Cc, or Bcc
478 The message bounce() method forwards a received message off to
479 someone else without modification; you must specified it's new
480 destination. If you have the urge not to specify any destination,
481 you probably are looking for reply(). When you wish to modify the
482 content, use forward().
483 Error: Method forwardAttach requires a preamble
485 Error: Method forwardEncapsulate requires a preamble
486 Error: No address to create forwarded to.
487 If a forward message is created, a destination address must be
488 specified.
489 Error: No default mailer found to send message.
491 The message send() mechanism had not enough information to
492 automatically find a mail transfer agent to sent this message.
493 Specify a mailer explicitly using the "via" options.
494 Error: No rebuild rule $name defined.
496 Error: Only build() Mail::Message's; they are not in a folder yet
497 You may wish to construct a message to be stored in a some kind of
498 folder, but you need to do that in two steps. First, create a
499 normal Mail::Message, and then add it to the folder. During this
500 Mail::Box::addMessage() process, the message will get coerce()-d
501 into the right message type, adding storage information and the
502 like.
503 Error: Package $package does not implement $method.
505 Fatal error: the specific package (or one of its superclasses) does
506 not implement this method where it should. This message means that
507 some other related classes do implement this method however the
508 class at hand does not. Probably you should investigate this and
509 probably inform the author of the package.
510 Error: Unable to read delayed body.
512 Error: Unable to read delayed head.
513 Error: coercion starts with some object
514
516 This module is part of Mail-Box distribution version 2.097, built on
517 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
518
520 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
521 ChangeLog.
522 This program is free software; you can redistribute it and/or modify it
524 under the same terms as Perl itself. See
525 http://www.perl.com/perl/misc/Artistic.html
526perl v5.12.3 2011-01-26 Mail::Box::IMAP4::Message(3)