Mail::Box::IMAP4::Message(3pm)

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 sep‐
22       arate entity on the server, and maybe temporarily in your program as
23       well.
24

METHODS

26       Constructors
27
28       $obj->clone(OPTIONS)
29
30           See "Constructors" in Mail::Message
31
32       Mail::Box::IMAP4::Message->new(OPTIONS)
33
34        Option      --Defined in     --Default
35        body          Mail::Message    undef
36        body_type     Mail::Box::Message  Mail::Message::Body::Lines
37        cache_body                     <false>
38        cache_head                     <false>
39        cache_labels                   <false>
40        deleted       Mail::Message    <false>
41        field_type    Mail::Message    undef
42        folder        Mail::Box::Message  <required>
43        head          Mail::Message    undef
44        head_type     Mail::Message    Mail::Message::Head::Complete
45        labels        Mail::Message    {}
46        log           Mail::Reporter   'WARNINGS'
47        messageId     Mail::Message    undef
48        modified      Mail::Message    <false>
49        size          Mail::Box::Message  undef
50        trace         Mail::Reporter   'WARNINGS'
51        trusted       Mail::Message    <false>
52        unique        Mail::Box::Net::Message  <unique string>
53        write_labels                   <true>
54
55           . body OBJECT
56
57           . body_type CODE⎪CLASS
58
59           . cache_body BOOLEAN
60
61           . cache_head BOOLEAN
62
63           . cache_labels BOOLEAN
64
65               All standard IMAP labels can be cached on the local server to
66               improve speed.  This has the same dangers as setting
67               "write_labels" to false.  The caching starts when the first
68               label of the message was read.
69
70           . deleted BOOLEAN
71
72           . field_type CLASS
73
74           . folder FOLDER
75
76           . head OBJECT
77
78           . head_type CLASS
79
80           . labels ARRAY⎪HASH
81
82           . log LEVEL
83
84           . messageId STRING
85
86           . modified BOOLEAN
87
88           . size INTEGER
89
90           . trace LEVEL
91
92           . trusted BOOLEAN
93
94           . unique STRING
95
96           . write_labels BOOLEAN
97
98               When a label is changed or its value read, using label(), that
99               info should be sent to the IMAP server.  But, this action could
100               be superfluous, for instance because the label was already set
101               or clear, and communication is expensive.  On the other hand,
102               someone else may use IMAP to make changes in the same folder,
103               and will get the updates too late or never...
104
105       Constructing a message
106
107       $obj->bounce([RG-OBJECT⎪OPTIONS])
108
109           See "Constructing a message" in Mail::Message::Construct::Bounce
110
111       Mail::Box::IMAP4::Message->build([MESSAGE⎪PART⎪BODY], CONTENT)
112
113           See "Constructing a message" in Mail::Message::Construct::Build
114
115       Mail::Box::IMAP4::Message->buildFromBody(BODY, [HEAD], HEADERS)
116
117           See "Constructing a message" in Mail::Message::Construct::Build
118
119       $obj->forward(OPTIONS)
120
121           See "Constructing a message" in Mail::Message::Construct::Forward
122
123       $obj->forwardAttach(OPTIONS)
124
125           See "Constructing a message" in Mail::Message::Construct::Forward
126
127       $obj->forwardEncapsulate(OPTIONS)
128
129           See "Constructing a message" in Mail::Message::Construct::Forward
130
131       $obj->forwardInline(OPTIONS)
132
133           See "Constructing a message" in Mail::Message::Construct::Forward
134
135       $obj->forwardNo(OPTIONS)
136
137           See "Constructing a message" in Mail::Message::Construct::Forward
138
139       $obj->forwardPostlude
140
141           See "Constructing a message" in Mail::Message::Construct::Forward
142
143       $obj->forwardPrelude
144
145           See "Constructing a message" in Mail::Message::Construct::Forward
146
147       $obj->forwardSubject(STRING)
148
149           See "Constructing a message" in Mail::Message::Construct::Forward
150
151       Mail::Box::IMAP4::Message->read(FILEHAN‐
152       DLE⎪SCALAR⎪REF-SCALAR⎪ARRAY-OF-LINES, OPTIONS)
153
154           See "Constructing a message" in Mail::Message::Construct::Read
155
156       $obj->rebuild(OPTIONS)
157
158           See "Constructing a message" in Mail::Message::Construct::Rebuild
159
160       $obj->reply(OPTIONS)
161
162           See "Constructing a message" in Mail::Message::Construct::Reply
163
164       $obj->replyPrelude([STRING⎪FIELD⎪ADDRESS⎪ARRAY-OF-THINGS])
165
166           See "Constructing a message" in Mail::Message::Construct::Reply
167
168       $obj->replySubject(STRING)
169
170       Mail::Box::IMAP4::Message->replySubject(STRING)
171
172           See "Constructing a message" in Mail::Message::Construct::Reply
173
174       The message
175
176       $obj->container
177
178           See "The message" in Mail::Message
179
180       $obj->copyTo(FOLDER, OPTIONS)
181
182           See "The message" in Mail::Box::Message
183
184       $obj->folder([FOLDER])
185
186           See "The message" in Mail::Box::Message
187
188       $obj->isDummy
189
190           See "The message" in Mail::Message
191
192       $obj->isPart
193
194           See "The message" in Mail::Message
195
196       $obj->messageId
197
198           See "The message" in Mail::Message
199
200       $obj->moveTo(FOLDER, OPTIONS)
201
202           See "The message" in Mail::Box::Message
203
204       $obj->print([FILEHANDLE])
205
206           See "The message" in Mail::Message
207
208       $obj->send([MAILER], OPTIONS)
209
210           See "The message" in Mail::Message
211
212       $obj->seqnr([INTEGER])
213
214           See "The message" in Mail::Box::Message
215
216       $obj->size
217
218           Returns the size of this message.  If the message is still on the
219           remote server, IMAP is used to ask for the size.  When the message
220           is already loaded onto the local system, the size of the parsed
221           message is taken.  These sizes can differ because the difference in
222           line-ending representation.
223
224       $obj->toplevel
225
226           See "The message" in Mail::Message
227
228       $obj->unique([STRING⎪undef])
229
230           See "The message" in Mail::Box::Net::Message
231
232       $obj->write([FILEHANDLE])
233
234           See "The message" in Mail::Message
235
236       The header
237
238       $obj->bcc
239
240           See "The header" in Mail::Message
241
242       $obj->cc
243
244           See "The header" in Mail::Message
245
246       $obj->date
247
248           See "The header" in Mail::Message
249
250       $obj->destinations
251
252           See "The header" in Mail::Message
253
254       $obj->from
255
256           See "The header" in Mail::Message
257
258       $obj->get(FIELDNAME)
259
260           See "The header" in Mail::Message
261
262       $obj->guessTimestamp
263
264           See "The header" in Mail::Message
265
266       $obj->head([HEAD])
267
268           See "The header" in Mail::Message
269
270       $obj->nrLines
271
272           See "The header" in Mail::Message
273
274       $obj->sender
275
276           See "The header" in Mail::Message
277
278       $obj->study(FIELDNAME)
279
280           See "The header" in Mail::Message
281
282       $obj->subject
283
284           See "The header" in Mail::Message
285
286       $obj->timestamp
287
288           See "The header" in Mail::Message
289
290       $obj->to
291
292           See "The header" in Mail::Message
293
294       The body
295
296       $obj->body([BODY])
297
298           See "The body" in Mail::Message
299
300       $obj->decoded(OPTIONS)
301
302           See "The body" in Mail::Message
303
304       $obj->encode(OPTIONS)
305
306           See "The body" in Mail::Message
307
308       $obj->isMultipart
309
310           See "The body" in Mail::Message
311
312       $obj->isNested
313
314           See "The body" in Mail::Message
315
316       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
317
318           See "The body" in Mail::Message
319
320       Flags
321
322       $obj->delete
323
324           See "Flags" in Mail::Message
325
326       $obj->deleted([BOOLEAN])
327
328           See "Flags" in Mail::Message
329
330       $obj->isDeleted
331
332           See "Flags" in Mail::Message
333
334       $obj->isModified
335
336           See "Flags" in Mail::Message
337
338       $obj->label(LABEL⎪PAIRS)
339
340           With only one argument, the value related to LABEL is returned.
341           With more that one argument, the list is interpreted a label-value
342           PAIRS to be set.
343
344           The IMAP protocol defines its own names for the labels, which must
345           be set imediately to inform other IMAP clients which may have the
346           same folder open. But that can be changed with new(write_labels).
347           Some labels are translated to the corresponding IMAP system labels.
348
349       $obj->labels
350
351           Get the names of all labels (LIST context, not efficient in IMAP4),
352           or a reference to a hash with labels.  You should only use the
353           returned hash to read the labels, because changes made to it will
354           not be passed to the remote server.  See labels() to set values.
355
356       $obj->labelsToStatus
357
358           See "Flags" in Mail::Message
359
360       $obj->modified([BOOLEAN])
361
362           See "Flags" in Mail::Message
363
364       $obj->statusToLabels
365
366           See "Flags" in Mail::Message
367
368       The whole message as text
369
370       $obj->file
371
372           See "The whole message as text" in Mail::Message::Construct::Text
373
374       $obj->lines
375
376           See "The whole message as text" in Mail::Message::Construct::Text
377
378       $obj->printStructure([FILEHANDLE⎪undef],[INDENT])
379
380           See "The whole message as text" in Mail::Message::Construct::Text
381
382       $obj->string
383
384           See "The whole message as text" in Mail::Message::Construct::Text
385
386       Internals
387
388       $obj->clonedFrom
389
390           See "Internals" in Mail::Message
391
392       Mail::Box::IMAP4::Message->coerce(MESSAGE, OPTIONS)
393
394           See "Internals" in Mail::Message
395
396       $obj->diskDelete
397
398           See "Internals" in Mail::Box::Message
399
400       $obj->fetch([INFO, ...])
401
402           Use the IMAP's "UID FETCH IMAP" command to get some data about this
403           message.  The INFO request is passed to Mail::Box::IMAP4::fetch().
404           Without INFO, "ALL" information is retreived and returned as a
405           HASH.
406
407       $obj->isDelayed
408
409           See "Internals" in Mail::Message
410
411       $obj->loadBody
412
413           See "Internals" in Mail::Box::Net::Message
414
415       $obj->readBody(PARSER, HEAD [, BODYTYPE])
416
417           See "Internals" in Mail::Box::Message
418
419       $obj->readFromParser(PARSER, [BODYTYPE])
420
421           See "Internals" in Mail::Message
422
423       $obj->readHead(PARSER [,CLASS])
424
425           See "Internals" in Mail::Message
426
427       $obj->recursiveRebuildPart(PART, OPTIONS)
428
429           See "Internals" in Mail::Message::Construct::Rebuild
430
431       $obj->storeBody(BODY)
432
433           See "Internals" in Mail::Message
434
435       $obj->takeMessageId([STRING])
436
437           See "Internals" in Mail::Message
438
439       $obj->writeDelayed(IMAP)
440
441           Write all delayed information, like label changes, to the server.
442           This is done under force, so should even be done for folders opened
443           without write-access. This method is called indirectly by a
444           Mail::Box::write() or Mail::Box::close().
445
446           The IMAP argument is a Mail::IMAPClient which has the right folder
447           already selected.
448
449           Writing changes to the remote folder is not without hassle: IMAP4
450           (or is it only Mail::IMAPClient doesn't support replacing header or
451           body.  Therefore, when either of them change, the whole message is
452           rewritten to the server (which is supported), and the original
453           flagged for deletion.
454
455       Error handling
456
457       $obj->AUTOLOAD
458
459           See "METHODS" in Mail::Message::Construct
460
461       $obj->addReport(OBJECT)
462
463           See "Error handling" in Mail::Reporter
464
465       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
466
467       Mail::Box::IMAP4::Message->defaultTrace([LEVEL]⎪[LOGLEVEL,
468       TRACELEVEL]⎪[LEVEL, CALLBACK])
469
470           See "Error handling" in Mail::Reporter
471
472       $obj->errors
473
474           See "Error handling" in Mail::Reporter
475
476       $obj->log([LEVEL [,STRINGS]])
477
478       Mail::Box::IMAP4::Message->log([LEVEL [,STRINGS]])
479
480           See "Error handling" in Mail::Reporter
481
482       $obj->logPriority(LEVEL)
483
484       Mail::Box::IMAP4::Message->logPriority(LEVEL)
485
486           See "Error handling" in Mail::Reporter
487
488       $obj->logSettings
489
490           See "Error handling" in Mail::Reporter
491
492       $obj->notImplemented
493
494           See "Error handling" in Mail::Reporter
495
496       $obj->report([LEVEL])
497
498           See "Error handling" in Mail::Reporter
499
500       $obj->reportAll([LEVEL])
501
502           See "Error handling" in Mail::Reporter
503
504       $obj->shortSize([VALUE])
505
506       Mail::Box::IMAP4::Message->shortSize([VALUE])
507
508           See "Error handling" in Mail::Message
509
510       $obj->shortString
511
512           See "Error handling" in Mail::Message
513
514       $obj->trace([LEVEL])
515
516           See "Error handling" in Mail::Reporter
517
518       $obj->warnings
519
520           See "Error handling" in Mail::Reporter
521
522       Cleanup
523
524       $obj->DESTROY
525
526           See "Cleanup" in Mail::Message
527
528       $obj->destruct
529
530           See "Cleanup" in Mail::Box::Message
531
532       $obj->inGlobalDestruction
533
534           See "Cleanup" in Mail::Reporter
535

DETAILS

537       Labels
538
539       IMAP protocol flags
540
541       Labels (or flags) are known to all folder formats, but differ how they
542       are stored.  Some folder types use message header lines to keep the
543       labels, other use a seperate file.  The IMAP protocol does not specify
544       how the labels are kept on the server, but does specify how they are
545       named.
546
547       The label names as defined by the IMAP protocol are standardized into
548       the MailBox standard to hide folder differences.  The following trans‐
549       lations are always performed:
550
551        \Seen     => seen
552        \Answered => replied
553        \Flagged  => flagged
554        \Deleted  => deleted
555        \Draft    => draft
556        \Recent   => NOT old
557
558       Example: of label translations
559
560        $imap->message(3)->label(replied => 1, draft => 0);
561
562       will result in a IMAP protocol statements like
563
564        A003 STORE 4 +FLAGS (\Answered)
565        A003 STORE 4 -FLAGS (\Draft)
566
567       Other labels
568
569       Of course, your program may be in need for more labels than those pro‐
570       vided by the protocol.  You can still use these: they stay locally (and
571       are lost when the folder is closed).  Some IMAP4 extensions permit more
572       labels than the basic RFC, but that is not yet supported by this imple‐
573       mentation.
574
575       Caching labels
576
577       When you ask for one or more flags of a message more than once, you may
578       improve the overall performance by setting new(cache_labels) to "YES".
579       However, this may cause inconsistencies when multiple clients use the
580       same folder on the IMAP server.
581
582       You may also delay the label updates to the server until the folder is
583       closed (or for ever when read-only is required).  When
584       Mail::Box::write() or Mail::Box::close() is called, it is decided
585       whether to throw all changes away or write after all.
586

DIAGNOSTICS

588       Error: Cannot include forward source as $include.
589
590       Unknown alternative for the forward(include).  Valid choices are "NO",
591       "INLINE", "ATTACH", and "ENCAPSULATE".
592
593       Error: Cannot include reply source as $include.
594
595       Unknown alternative for the "include" option of reply().  Valid choices
596       are "NO", "INLINE", and "ATTACH".
597
598       Error: Method bounce requires To, Cc, or Bcc
599
600       The message bounce() method forwards a received message off to someone
601       else without modification; you must specified it's new destination.  If
602       you have the urge not to specify any destination, you probably are
603       looking for reply(). When you wish to modify the content, use for‐
604       ward().
605
606       Error: Method forwardAttach requires a preamble
607
608       Error: Method forwardEncapsulate requires a preamble
609
610       Error: No address to create forwarded to.
611
612       If a forward message is created, a destination address must be speci‐
613       fied.
614
615       Error: No default mailer found to send message.
616
617       The message send() mechanism had not enough information to automati‐
618       cally find a mail transfer agent to sent this message.  Specify a
619       mailer explicitly using the "via" options.
620
621       Error: No rebuild rule $name defined.
622
623       Error: Only build() Mail::Message's; they are not in a folder yet
624
625       You may wish to construct a message to be stored in a some kind of
626       folder, but you need to do that in two steps.  First, create a normal
627       Mail::Message, and then add it to the folder.  During this
628       Mail::Box::addMessage() process, the message will get coerce()-d into
629       the right message type, adding storage information and the like.
630
631       Error: Package $package does not implement $method.
632
633       Fatal error: the specific package (or one of its superclasses) does not
634       implement this method where it should. This message means that some
635       other related classes do implement this method however the class at
636       hand does not.  Probably you should investigate this and probably
637       inform the author of the package.
638
639       Error: Unable to read delayed body.
640
641       Error: Unable to read delayed head.
642

LICENSE

648       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
649       ChangeLog.
650
651       This program is free software; you can redistribute it and/or modify it
652       under the same terms as Perl itself.  See
653       http://www.perl.com/perl/misc/Artistic.html
654
655
656
657perl v5.8.8                       2007-03-25      Mail::Box::IMAP4::Message(3)