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 Extends "DESCRIPTION" in Mail::Box::Net::Message.
26
28 Extends "METHODS" in Mail::Box::Net::Message.
29 Constructors
31 Extends "Constructors" in Mail::Box::Net::Message.
32 $obj->clone(%options)
34 Inherited, see "Constructors" in Mail::Message
35 Mail::Box::IMAP4::Message->new(%options)
37 -Option --Defined in --Default
38 body Mail::Message undef
39 body_type Mail::Box::Message Mail::Message::Body::Lines
40 cache_body <false>
41 cache_head <false>
42 cache_labels <false>
43 deleted Mail::Message <false>
44 field_type Mail::Message undef
45 folder Mail::Box::Message <required>
46 head Mail::Message undef
47 head_type Mail::Message Mail::Message::Head::Complete
48 labels Mail::Message {}
49 log Mail::Reporter 'WARNINGS'
50 messageId Mail::Message undef
51 modified Mail::Message <false>
52 size Mail::Box::Message undef
53 trace Mail::Reporter 'WARNINGS'
54 trusted Mail::Message <false>
55 unique Mail::Box::Net::Message <unique string>
56 write_labels <true>
57 body => OBJECT
59 body_type => CODE|CLASS
60 cache_body => BOOLEAN
61 cache_head => BOOLEAN
62 cache_labels => BOOLEAN
63 All standard IMAP labels can be cached on the local server to
64 improve speed. This has the same dangers as setting
65 "write_labels" to false. The caching starts when the first label
66 of the message was read.
67 deleted => BOOLEAN
69 field_type => CLASS
70 folder => FOLDER
71 head => OBJECT
72 head_type => CLASS
73 labels => ARRAY|HASH
74 log => LEVEL
75 messageId => STRING
76 modified => BOOLEAN
77 size => INTEGER
78 trace => LEVEL
79 trusted => BOOLEAN
80 unique => STRING
81 write_labels => BOOLEAN
82 When a label is changed or its value read, using label(), that
83 info should be sent to the IMAP server. But, this action could
84 be superfluous, for instance because the label was already set or
85 clear, and communication is expensive. On the other hand,
86 someone else may use IMAP to make changes in the same folder, and
87 will get the updates too late or never...
88 Constructing a message
90 Extends "Constructing a message" in Mail::Box::Net::Message.
91 $obj->bounce( [<$rg_object|%options>] )
93 Inherited, see "Constructing a message" in
94 Mail::Message::Construct::Bounce
95 Mail::Box::IMAP4::Message->build( [$message|$part|$body], $content )
97 Inherited, see "Constructing a message" in
98 Mail::Message::Construct::Build
99 Mail::Box::IMAP4::Message->buildFromBody($body, [$head], $headers)
101 Inherited, see "Constructing a message" in
102 Mail::Message::Construct::Build
103 $obj->forward(%options)
105 Inherited, see "Constructing a message" in
106 Mail::Message::Construct::Forward
107 $obj->forwardAttach(%options)
109 Inherited, see "Constructing a message" in
110 Mail::Message::Construct::Forward
111 $obj->forwardEncapsulate(%options)
113 Inherited, see "Constructing a message" in
114 Mail::Message::Construct::Forward
115 $obj->forwardInline(%options)
117 Inherited, see "Constructing a message" in
118 Mail::Message::Construct::Forward
119 $obj->forwardNo(%options)
121 Inherited, see "Constructing a message" in
122 Mail::Message::Construct::Forward
123 $obj->forwardPostlude()
125 Inherited, see "Constructing a message" in
126 Mail::Message::Construct::Forward
127 $obj->forwardPrelude()
129 Inherited, see "Constructing a message" in
130 Mail::Message::Construct::Forward
131 $obj->forwardSubject(STRING)
133 Inherited, see "Constructing a message" in
134 Mail::Message::Construct::Forward
135 Mail::Box::IMAP4::Message->read($fh|STRING|SCALAR|ARRAY, %options)
137 Inherited, see "Constructing a message" in
138 Mail::Message::Construct::Read
139 $obj->rebuild(%options)
141 Inherited, see "Constructing a message" in
142 Mail::Message::Construct::Rebuild
143 $obj->reply(%options)
145 Inherited, see "Constructing a message" in
146 Mail::Message::Construct::Reply
147 $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
149 Inherited, see "Constructing a message" in
150 Mail::Message::Construct::Reply
151 $obj->replySubject(STRING)
153 Mail::Box::IMAP4::Message->replySubject(STRING)
154 Inherited, see "Constructing a message" in
155 Mail::Message::Construct::Reply
156 The message
158 Extends "The message" in Mail::Box::Net::Message.
159 $obj->container()
161 Inherited, see "The message" in Mail::Message
162 $obj->copyTo($folder, %options)
164 Inherited, see "The message" in Mail::Box::Message
165 $obj->folder( [$folder] )
167 Inherited, see "The message" in Mail::Box::Message
168 $obj->isDummy()
170 Inherited, see "The message" in Mail::Message
171 $obj->isPart()
173 Inherited, see "The message" in Mail::Message
174 $obj->messageId()
176 Inherited, see "The message" in Mail::Message
177 $obj->moveTo($folder, %options)
179 Inherited, see "The message" in Mail::Box::Message
180 $obj->partNumber()
182 Inherited, see "The message" in Mail::Message
183 $obj->print( [$fh] )
185 Inherited, see "The message" in Mail::Message
186 $obj->send( [$mailer], %options )
188 Inherited, see "The message" in Mail::Message
189 $obj->seqnr( [$integer] )
191 Inherited, see "The message" in Mail::Box::Message
192 $obj->size()
194 Returns the size of this message. If the message is still on the
195 remote server, IMAP is used to ask for the size. When the message
196 is already loaded onto the local system, the size of the parsed
197 message is taken. These sizes can differ because the difference in
198 line-ending representation.
199 $obj->toplevel()
201 Inherited, see "The message" in Mail::Message
202 $obj->unique( [STRING|undef] )
204 Inherited, see "The message" in Mail::Box::Net::Message
205 $obj->write( [$fh] )
207 Inherited, see "The message" in Mail::Message
208 The header
210 Extends "The header" in Mail::Box::Net::Message.
211 $obj->bcc()
213 Inherited, see "The header" in Mail::Message
214 $obj->cc()
216 Inherited, see "The header" in Mail::Message
217 $obj->date()
219 Inherited, see "The header" in Mail::Message
220 $obj->destinations()
222 Inherited, see "The header" in Mail::Message
223 $obj->from()
225 Inherited, see "The header" in Mail::Message
226 $obj->get($fieldname)
228 Inherited, see "The header" in Mail::Message
229 $obj->guessTimestamp()
231 Inherited, see "The header" in Mail::Message
232 $obj->head( [$head] )
234 Inherited, see "The header" in Mail::Message
235 $obj->nrLines()
237 Inherited, see "The header" in Mail::Message
238 $obj->sender()
240 Inherited, see "The header" in Mail::Message
241 $obj->study($fieldname)
243 Inherited, see "The header" in Mail::Message
244 $obj->subject()
246 Inherited, see "The header" in Mail::Message
247 $obj->timestamp()
249 Inherited, see "The header" in Mail::Message
250 $obj->to()
252 Inherited, see "The header" in Mail::Message
253 The body
255 Extends "The body" in Mail::Box::Net::Message.
256 $obj->body( [$body] )
258 Inherited, see "The body" in Mail::Message
259 $obj->contentType()
261 Inherited, see "The body" in Mail::Message
262 $obj->decoded(%options)
264 Inherited, see "The body" in Mail::Message
265 $obj->encode(%options)
267 Inherited, see "The body" in Mail::Message
268 $obj->isMultipart()
270 Inherited, see "The body" in Mail::Message
271 $obj->isNested()
273 Inherited, see "The body" in Mail::Message
274 $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
276 Inherited, see "The body" in Mail::Message
277 Flags
279 Extends "Flags" in Mail::Box::Net::Message.
280 $obj->delete()
282 Inherited, see "Flags" in Mail::Message
283 $obj->deleted( [BOOLEAN] )
285 Inherited, see "Flags" in Mail::Message
286 $obj->isDeleted()
288 Inherited, see "Flags" in Mail::Message
289 $obj->isModified()
291 Inherited, see "Flags" in Mail::Message
292 $obj->label($label|PAIRS)
294 With only one argument, the value related to $label is returned.
295 With more that one argument, the list is interpreted a label-value
296 PAIRS to be set.
297 The IMAP protocol defines its own names for the labels, which must
299 be set immediately to inform other IMAP clients which may have the
300 same folder open. But that can be changed with new(write_labels).
301 Some labels are translated to the corresponding IMAP system labels.
302 $obj->labels()
304 Get the names of all labels (LIST context, not efficient in IMAP4),
305 or a reference to a hash with labels. You should only use the
306 returned hash to read the labels, because changes made to it will
307 not be passed to the remote server. See labels() to set values.
308 $obj->labelsToStatus()
310 Inherited, see "Flags" in Mail::Message
311 $obj->modified( [BOOLEAN] )
313 Inherited, see "Flags" in Mail::Message
314 $obj->statusToLabels()
316 Inherited, see "Flags" in Mail::Message
317 The whole message as text
319 Extends "The whole message as text" in Mail::Box::Net::Message.
320 $obj->file()
322 Inherited, see "The whole message as text" in
323 Mail::Message::Construct::Text
324 $obj->lines()
326 Inherited, see "The whole message as text" in
327 Mail::Message::Construct::Text
328 $obj->printStructure( [$fh|undef],[$indent] )
330 Inherited, see "The whole message as text" in
331 Mail::Message::Construct::Text
332 $obj->string()
334 Inherited, see "The whole message as text" in
335 Mail::Message::Construct::Text
336 Internals
338 Extends "Internals" in Mail::Box::Net::Message.
339 $obj->clonedFrom()
341 Inherited, see "Internals" in Mail::Message
342 Mail::Box::IMAP4::Message->coerce($message, %options)
344 Inherited, see "Internals" in Mail::Message
345 $obj->diskDelete()
347 Inherited, see "Internals" in Mail::Box::Message
348 $obj->fetch( [$info, ...] )
350 Use the IMAP's "UID FETCH IMAP" command to get some data about this
351 message. The $info request is passed to Mail::Box::IMAP4::fetch().
352 Without $info, "ALL" information is retrieved and returned as a
353 HASH.
354 $obj->isDelayed()
356 Inherited, see "Internals" in Mail::Message
357 $obj->loadBody()
359 Inherited, see "Internals" in Mail::Box::Net::Message
360 $obj->readBody( $parser, $head, [$bodytype] )
362 Inherited, see "Internals" in Mail::Box::Message
363 $obj->readFromParser( $parser, [$bodytype] )
365 Inherited, see "Internals" in Mail::Message
366 $obj->readHead( $parser, [$class] )
368 Inherited, see "Internals" in Mail::Message
369 $obj->recursiveRebuildPart($part, %options)
371 Inherited, see "Internals" in Mail::Message::Construct::Rebuild
372 $obj->storeBody($body)
374 Inherited, see "Internals" in Mail::Message
375 $obj->takeMessageId( [STRING] )
377 Inherited, see "Internals" in Mail::Message
378 $obj->writeDelayed($imap)
380 Write all delayed information, like label changes, to the server.
381 This is done under force, so should even be done for folders opened
382 without write-access. This method is called indirectly by a
383 Mail::Box::write() or Mail::Box::close().
384 The $imap argument is a Mail::IMAPClient which has the right folder
386 already selected.
387 Writing changes to the remote folder is not without hassle: IMAP4
389 (or is it only Mail::IMAPClient doesn't support replacing header or
390 body. Therefore, when either of them change, the whole message is
391 rewritten to the server (which is supported), and the original
392 flagged for deletion.
393 Error handling
395 Extends "Error handling" in Mail::Box::Net::Message.
396 $obj->AUTOLOAD()
398 Inherited, see "METHODS" in Mail::Message::Construct
399 $obj->addReport($object)
401 Inherited, see "Error handling" in Mail::Reporter
402 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
404 $callback] )
405 Mail::Box::IMAP4::Message->defaultTrace( [$level]|[$loglevel,
406 $tracelevel]|[$level, $callback] )
407 Inherited, see "Error handling" in Mail::Reporter
408 $obj->errors()
410 Inherited, see "Error handling" in Mail::Reporter
411 $obj->log( [$level, [$strings]] )
413 Mail::Box::IMAP4::Message->log( [$level, [$strings]] )
414 Inherited, see "Error handling" in Mail::Reporter
415 $obj->logPriority($level)
417 Mail::Box::IMAP4::Message->logPriority($level)
418 Inherited, see "Error handling" in Mail::Reporter
419 $obj->logSettings()
421 Inherited, see "Error handling" in Mail::Reporter
422 $obj->notImplemented()
424 Inherited, see "Error handling" in Mail::Reporter
425 $obj->report( [$level] )
427 Inherited, see "Error handling" in Mail::Reporter
428 $obj->reportAll( [$level] )
430 Inherited, see "Error handling" in Mail::Reporter
431 $obj->shortSize( [$value] )
433 Mail::Box::IMAP4::Message->shortSize( [$value] )
434 Inherited, see "Error handling" in Mail::Message
435 $obj->shortString()
437 Inherited, see "Error handling" in Mail::Message
438 $obj->trace( [$level] )
440 Inherited, see "Error handling" in Mail::Reporter
441 $obj->warnings()
443 Inherited, see "Error handling" in Mail::Reporter
444 Cleanup
446 Extends "Cleanup" in Mail::Box::Net::Message.
447 $obj->DESTROY()
449 Inherited, see "Cleanup" in Mail::Reporter
450 $obj->destruct()
452 Inherited, see "Cleanup" in Mail::Box::Message
453
455 Extends "DETAILS" in Mail::Box::Net::Message.
456 Structure of a Message
458 Extends "Structure of a Message" in Mail::Box::Net::Message.
459 Message object implementation
461 Extends "Message object implementation" in Mail::Box::Net::Message.
462 Message class implementation
464 Extends "Message class implementation" in Mail::Box::Net::Message.
465 Labels
467 Extends "Labels" in Mail::Box::Net::Message.
468 Predefined labels
470 Extends "Predefined labels" in Mail::Box::Net::Message.
472 Status and X-Status fields
474 Extends "Status and X-Status fields" in Mail::Box::Net::Message.
476 IMAP protocol flags
478 Labels (or flags) are known to all folder formats, but differ how they
480 are stored. Some folder types use message header lines to keep the
481 labels, other use a separate file. The IMAP protocol does not specify
482 how the labels are kept on the server, but does specify how they are
483 named.
484 The label names as defined by the IMAP protocol are standardized into
486 the MailBox standard to hide folder differences. The following
487 translations are always performed:
488 \Seen => seen
490 \Answered => replied
491 \Flagged => flagged
492 \Deleted => deleted
493 \Draft => draft
494 \Recent => NOT old
495 . Example: of label translations
497 $imap->message(3)->label(replied => 1, draft => 0);
499 will result in a IMAP protocol statements like
501 A003 STORE 4 +FLAGS (\Answered)
503 A003 STORE 4 -FLAGS (\Draft)
504 Other labels
506 Of course, your program may be in need for more labels than those
508 provided by the protocol. You can still use these: they stay locally
509 (and are lost when the folder is closed). Some IMAP4 extensions permit
510 more labels than the basic RFC, but that is not yet supported by this
511 implementation.
512 Caching labels
514 When you ask for one or more flags of a message more than once, you may
516 improve the overall performance by setting new(cache_labels) to "YES".
517 However, this may cause inconsistencies when multiple clients use the
518 same folder on the IMAP server.
519 You may also delay the label updates to the server until the folder is
521 closed (or for ever when read-only is required). When
522 Mail::Box::write() or Mail::Box::close() is called, it is decided
523 whether to throw all changes away or write after all.
524
526 Error: Cannot coerce a $class object into a $class object
527 Error: Cannot include forward source as $include.
528 Unknown alternative for the forward(include). Valid choices are
529 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
530 Error: Cannot include reply source as $include.
532 Unknown alternative for the "include" option of reply(). Valid
533 choices are "NO", "INLINE", and "ATTACH".
534 Error: Method bounce requires To, Cc, or Bcc
536 The message bounce() method forwards a received message off to
537 someone else without modification; you must specified it's new
538 destination. If you have the urge not to specify any destination,
539 you probably are looking for reply(). When you wish to modify the
540 content, use forward().
541 Error: Method forwardAttach requires a preamble
543 Error: Method forwardEncapsulate requires a preamble
544 Error: No address to create forwarded to.
545 If a forward message is created, a destination address must be
546 specified.
547 Error: No default mailer found to send message.
549 The message send() mechanism had not enough information to
550 automatically find a mail transfer agent to sent this message.
551 Specify a mailer explicitly using the "via" options.
552 Error: No rebuild rule $name defined.
554 Error: Only build() Mail::Message's; they are not in a folder yet
555 You may wish to construct a message to be stored in a some kind of
556 folder, but you need to do that in two steps. First, create a
557 normal Mail::Message, and then add it to the folder. During this
558 Mail::Box::addMessage() process, the message will get coerce()-d
559 into the right message type, adding storage information and the
560 like.
561 Error: Package $package does not implement $method.
563 Fatal error: the specific package (or one of its superclasses) does
564 not implement this method where it should. This message means that
565 some other related classes do implement this method however the
566 class at hand does not. Probably you should investigate this and
567 probably inform the author of the package.
568 Error: Unable to read delayed body.
570 Error: Unable to read delayed head.
571 Error: coercion starts with some object
572
574 This module is part of Mail-Box-IMAP4 distribution version 3.007, built
575 on June 13, 2019. Website: http://perl.overmeer.net/CPAN/
576
578 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
579 ChangeLog.
580 This program is free software; you can redistribute it and/or modify it
582 under the same terms as Perl itself. See http://dev.perl.org/licenses/
583perl v5.36.0 2023-01-20 Mail::Box::IMAP4::Message(3)