1Mail::Box::IMAP4::MessaUgsee(r3)Contributed Perl DocumenMtaaitli:o:nBox::IMAP4::Message(3)
2
3
4

NAME

6       Mail::Box::IMAP4::Message - one message on a IMAP4 server
7

INHERITANCE

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

SYNOPSIS

16        my $folder = new Mail::Box::IMAP4 ...
17        my $message = $folder->message(10);
18

DESCRIPTION

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
25       Extends "DESCRIPTION" in Mail::Box::Net::Message.
26

METHODS

28       Extends "METHODS" in Mail::Box::Net::Message.
29
30   Constructors
31       Extends "Constructors" in Mail::Box::Net::Message.
32
33       $obj->clone(%options)
34           Inherited, see "Constructors" in Mail::Message
35
36       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
58           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
68           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
89   Constructing a message
90       Extends "Constructing a message" in Mail::Box::Net::Message.
91
92       $obj->bounce( [<$rg_object|%options>] )
93           Inherited, see "Constructing a message" in
94           Mail::Message::Construct::Bounce
95
96       Mail::Box::IMAP4::Message->build( [$message|$part|$body], $content )
97           Inherited, see "Constructing a message" in
98           Mail::Message::Construct::Build
99
100       Mail::Box::IMAP4::Message->buildFromBody($body, [$head], $headers)
101           Inherited, see "Constructing a message" in
102           Mail::Message::Construct::Build
103
104       $obj->forward(%options)
105           Inherited, see "Constructing a message" in
106           Mail::Message::Construct::Forward
107
108       $obj->forwardAttach(%options)
109           Inherited, see "Constructing a message" in
110           Mail::Message::Construct::Forward
111
112       $obj->forwardEncapsulate(%options)
113           Inherited, see "Constructing a message" in
114           Mail::Message::Construct::Forward
115
116       $obj->forwardInline(%options)
117           Inherited, see "Constructing a message" in
118           Mail::Message::Construct::Forward
119
120       $obj->forwardNo(%options)
121           Inherited, see "Constructing a message" in
122           Mail::Message::Construct::Forward
123
124       $obj->forwardPostlude()
125           Inherited, see "Constructing a message" in
126           Mail::Message::Construct::Forward
127
128       $obj->forwardPrelude()
129           Inherited, see "Constructing a message" in
130           Mail::Message::Construct::Forward
131
132       $obj->forwardSubject(STRING)
133           Inherited, see "Constructing a message" in
134           Mail::Message::Construct::Forward
135
136       Mail::Box::IMAP4::Message->read($fh|STRING|SCALAR|ARRAY, %options)
137           Inherited, see "Constructing a message" in
138           Mail::Message::Construct::Read
139
140       $obj->rebuild(%options)
141           Inherited, see "Constructing a message" in
142           Mail::Message::Construct::Rebuild
143
144       $obj->reply(%options)
145           Inherited, see "Constructing a message" in
146           Mail::Message::Construct::Reply
147
148       $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
149           Inherited, see "Constructing a message" in
150           Mail::Message::Construct::Reply
151
152       $obj->replySubject(STRING)
153       Mail::Box::IMAP4::Message->replySubject(STRING)
154           Inherited, see "Constructing a message" in
155           Mail::Message::Construct::Reply
156
157   The message
158       Extends "The message" in Mail::Box::Net::Message.
159
160       $obj->container()
161           Inherited, see "The message" in Mail::Message
162
163       $obj->copyTo($folder, %options)
164           Inherited, see "The message" in Mail::Box::Message
165
166       $obj->folder( [$folder] )
167           Inherited, see "The message" in Mail::Box::Message
168
169       $obj->isDummy()
170           Inherited, see "The message" in Mail::Message
171
172       $obj->isPart()
173           Inherited, see "The message" in Mail::Message
174
175       $obj->messageId()
176           Inherited, see "The message" in Mail::Message
177
178       $obj->moveTo($folder, %options)
179           Inherited, see "The message" in Mail::Box::Message
180
181       $obj->partNumber()
182           Inherited, see "The message" in Mail::Message
183
184       $obj->print( [$fh] )
185           Inherited, see "The message" in Mail::Message
186
187       $obj->send( [$mailer], %options )
188           Inherited, see "The message" in Mail::Message
189
190       $obj->seqnr( [$integer] )
191           Inherited, see "The message" in Mail::Box::Message
192
193       $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
200       $obj->toplevel()
201           Inherited, see "The message" in Mail::Message
202
203       $obj->unique( [STRING|undef] )
204           Inherited, see "The message" in Mail::Box::Net::Message
205
206       $obj->write( [$fh] )
207           Inherited, see "The message" in Mail::Message
208
209   The header
210       Extends "The header" in Mail::Box::Net::Message.
211
212       $obj->bcc()
213           Inherited, see "The header" in Mail::Message
214
215       $obj->cc()
216           Inherited, see "The header" in Mail::Message
217
218       $obj->date()
219           Inherited, see "The header" in Mail::Message
220
221       $obj->destinations()
222           Inherited, see "The header" in Mail::Message
223
224       $obj->from()
225           Inherited, see "The header" in Mail::Message
226
227       $obj->get($fieldname)
228           Inherited, see "The header" in Mail::Message
229
230       $obj->guessTimestamp()
231           Inherited, see "The header" in Mail::Message
232
233       $obj->head( [$head] )
234           Inherited, see "The header" in Mail::Message
235
236       $obj->nrLines()
237           Inherited, see "The header" in Mail::Message
238
239       $obj->sender()
240           Inherited, see "The header" in Mail::Message
241
242       $obj->study($fieldname)
243           Inherited, see "The header" in Mail::Message
244
245       $obj->subject()
246           Inherited, see "The header" in Mail::Message
247
248       $obj->timestamp()
249           Inherited, see "The header" in Mail::Message
250
251       $obj->to()
252           Inherited, see "The header" in Mail::Message
253
254   The body
255       Extends "The body" in Mail::Box::Net::Message.
256
257       $obj->body( [$body] )
258           Inherited, see "The body" in Mail::Message
259
260       $obj->contentType()
261           Inherited, see "The body" in Mail::Message
262
263       $obj->decoded(%options)
264           Inherited, see "The body" in Mail::Message
265
266       $obj->encode(%options)
267           Inherited, see "The body" in Mail::Message
268
269       $obj->isMultipart()
270           Inherited, see "The body" in Mail::Message
271
272       $obj->isNested()
273           Inherited, see "The body" in Mail::Message
274
275       $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
276           Inherited, see "The body" in Mail::Message
277
278   Flags
279       Extends "Flags" in Mail::Box::Net::Message.
280
281       $obj->delete()
282           Inherited, see "Flags" in Mail::Message
283
284       $obj->deleted( [BOOLEAN] )
285           Inherited, see "Flags" in Mail::Message
286
287       $obj->isDeleted()
288           Inherited, see "Flags" in Mail::Message
289
290       $obj->isModified()
291           Inherited, see "Flags" in Mail::Message
292
293       $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
298           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
303       $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
309       $obj->labelsToStatus()
310           Inherited, see "Flags" in Mail::Message
311
312       $obj->modified( [BOOLEAN] )
313           Inherited, see "Flags" in Mail::Message
314
315       $obj->statusToLabels()
316           Inherited, see "Flags" in Mail::Message
317
318   The whole message as text
319       Extends "The whole message as text" in Mail::Box::Net::Message.
320
321       $obj->file()
322           Inherited, see "The whole message as text" in
323           Mail::Message::Construct::Text
324
325       $obj->lines()
326           Inherited, see "The whole message as text" in
327           Mail::Message::Construct::Text
328
329       $obj->printStructure( [$fh|undef],[$indent] )
330           Inherited, see "The whole message as text" in
331           Mail::Message::Construct::Text
332
333       $obj->string()
334           Inherited, see "The whole message as text" in
335           Mail::Message::Construct::Text
336
337   Internals
338       Extends "Internals" in Mail::Box::Net::Message.
339
340       $obj->clonedFrom()
341           Inherited, see "Internals" in Mail::Message
342
343       Mail::Box::IMAP4::Message->coerce($message, %options)
344           Inherited, see "Internals" in Mail::Message
345
346       $obj->diskDelete()
347           Inherited, see "Internals" in Mail::Box::Message
348
349       $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
355       $obj->isDelayed()
356           Inherited, see "Internals" in Mail::Message
357
358       $obj->loadBody()
359           Inherited, see "Internals" in Mail::Box::Net::Message
360
361       $obj->readBody( $parser, $head, [$bodytype] )
362           Inherited, see "Internals" in Mail::Box::Message
363
364       $obj->readFromParser( $parser, [$bodytype] )
365           Inherited, see "Internals" in Mail::Message
366
367       $obj->readHead( $parser, [$class] )
368           Inherited, see "Internals" in Mail::Message
369
370       $obj->recursiveRebuildPart($part, %options)
371           Inherited, see "Internals" in Mail::Message::Construct::Rebuild
372
373       $obj->storeBody($body)
374           Inherited, see "Internals" in Mail::Message
375
376       $obj->takeMessageId( [STRING] )
377           Inherited, see "Internals" in Mail::Message
378
379       $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
385           The $imap argument is a Mail::IMAPClient which has the right folder
386           already selected.
387
388           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
394   Error handling
395       Extends "Error handling" in Mail::Box::Net::Message.
396
397       $obj->AUTOLOAD()
398           Inherited, see "METHODS" in Mail::Message::Construct
399
400       $obj->addReport($object)
401           Inherited, see "Error handling" in Mail::Reporter
402
403       $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
409       $obj->errors()
410           Inherited, see "Error handling" in Mail::Reporter
411
412       $obj->log( [$level, [$strings]] )
413       Mail::Box::IMAP4::Message->log( [$level, [$strings]] )
414           Inherited, see "Error handling" in Mail::Reporter
415
416       $obj->logPriority($level)
417       Mail::Box::IMAP4::Message->logPriority($level)
418           Inherited, see "Error handling" in Mail::Reporter
419
420       $obj->logSettings()
421           Inherited, see "Error handling" in Mail::Reporter
422
423       $obj->notImplemented()
424           Inherited, see "Error handling" in Mail::Reporter
425
426       $obj->report( [$level] )
427           Inherited, see "Error handling" in Mail::Reporter
428
429       $obj->reportAll( [$level] )
430           Inherited, see "Error handling" in Mail::Reporter
431
432       $obj->shortSize( [$value] )
433       Mail::Box::IMAP4::Message->shortSize( [$value] )
434           Inherited, see "Error handling" in Mail::Message
435
436       $obj->shortString()
437           Inherited, see "Error handling" in Mail::Message
438
439       $obj->trace( [$level] )
440           Inherited, see "Error handling" in Mail::Reporter
441
442       $obj->warnings()
443           Inherited, see "Error handling" in Mail::Reporter
444
445   Cleanup
446       Extends "Cleanup" in Mail::Box::Net::Message.
447
448       $obj->DESTROY()
449           Inherited, see "Cleanup" in Mail::Reporter
450
451       $obj->destruct()
452           Inherited, see "Cleanup" in Mail::Box::Message
453

DETAILS

455       Extends "DETAILS" in Mail::Box::Net::Message.
456
457   Structure of a Message
458       Extends "Structure of a Message" in Mail::Box::Net::Message.
459
460   Message object implementation
461       Extends "Message object implementation" in Mail::Box::Net::Message.
462
463   Message class implementation
464       Extends "Message class implementation" in Mail::Box::Net::Message.
465
466   Labels
467       Extends "Labels" in Mail::Box::Net::Message.
468
469       Predefined labels
470
471       Extends "Predefined labels" in Mail::Box::Net::Message.
472
473       Status and X-Status fields
474
475       Extends "Status and X-Status fields" in Mail::Box::Net::Message.
476
477       IMAP protocol flags
478
479       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
485       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
489        \Seen     => seen
490        \Answered => replied
491        \Flagged  => flagged
492        \Deleted  => deleted
493        \Draft    => draft
494        \Recent   => NOT old
495
496       . Example: of label translations
497
498        $imap->message(3)->label(replied => 1, draft => 0);
499
500       will result in a IMAP protocol statements like
501
502        A003 STORE 4 +FLAGS (\Answered)
503        A003 STORE 4 -FLAGS (\Draft)
504
505       Other labels
506
507       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
513       Caching labels
514
515       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
520       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

DIAGNOSTICS

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
531       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
535       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
542       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
548       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
553       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
562       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
569       Error: Unable to read delayed body.
570       Error: Unable to read delayed head.
571       Error: coercion starts with some object
572

SEE ALSO

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

LICENSE

578       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
579       ChangeLog.
580
581       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/
583
584
585
586perl v5.32.1                      2021-01-27      Mail::Box::IMAP4::Message(3)
Impressum