Mail::Box::Message(3pm)

1Mail::Box::Message(3) User Contributed Perl DocumentationMail::Box::Message(3)
2
3
4

NAME

6       Mail::Box::Message - manage one message within a mail-folder
7

INHERITANCE

9        Mail::Box::Message
10          is a Mail::Message
11          is a Mail::Reporter
12
13        Mail::Box::Message is extended by
14          Mail::Box::Dir::Message
15          Mail::Box::File::Message
16          Mail::Box::Message::Destructed
17          Mail::Box::Net::Message
18

SYNOPSIS

20        # Usually these message objects are created indirectly
21        use Mail::Box::Manager;
22        my $manager = Mail::Box::Manager->new;
23        my $folder  = $manager->open(folder => 'Mail/Drafts');
24        my $msg     = $folder->message(1);
25        $msg->delete;
26        $msg->size;   # and much more
27

DESCRIPTION

29       These pages do only describe methods which relate to folders.  If you
30       access the knowledge of a message, then read Mail::Message.
31
32       During its life, a message will pass through certain stages.  These
33       stages were introduced to reduce the access-time to the folder.  Chang‐
34       ing from stage, the message's body and head objects may change.
35

METHODS

37       Constructors
38
39       $obj->clone(OPTIONS)
40
41           See "Constructors" in Mail::Message
42
43       Mail::Box::Message->new(OPTIONS)
44
45        Option    --Defined in     --Default
46        body        Mail::Message    undef
47        body_type                    <from folder>
48        deleted     Mail::Message    <false>
49        field_type  Mail::Message    undef
50        folder                       <required>
51        head        Mail::Message    undef
52        head_type   Mail::Message    Mail::Message::Head::Complete
53        labels      Mail::Message    {}
54        log         Mail::Reporter   'WARNINGS'
55        messageId   Mail::Message    undef
56        modified    Mail::Message    <false>
57        size                         undef
58        trace       Mail::Reporter   'WARNINGS'
59        trusted     Mail::Message    <false>
60
61           . body OBJECT
62
63           . body_type CODE⎪CLASS
64
65               If the body of a message is used delay-loaded, the message must
66               what type of message to become when it finally gets parsed.
67               The folder which is delaying the load must specify the algo‐
68               rithm to determine that type.
69
70           . deleted BOOLEAN
71
72           . field_type CLASS
73
74           . folder FOLDER
75
76               The folder where this message appeared in.  The argument is an
77               instance of (a sub-class of) a Mail::Box.
78
79           . head OBJECT
80
81           . head_type CLASS
82
83           . labels ARRAY⎪HASH
84
85           . log LEVEL
86
87           . messageId STRING
88
89           . modified BOOLEAN
90
91           . size INTEGER
92
93               The size of the message, which includes head and body, but
94               without the message separators which may be used by the folder
95               type.
96
97           . trace LEVEL
98
99           . trusted BOOLEAN
100
101       Constructing a message
102
103       $obj->bounce([RG-OBJECT⎪OPTIONS])
104
105           See "Constructing a message" in Mail::Message::Construct::Bounce
106
107       Mail::Box::Message->build([MESSAGE⎪PART⎪BODY], CONTENT)
108
109           See "Constructing a message" in Mail::Message::Construct::Build
110
111       Mail::Box::Message->buildFromBody(BODY, [HEAD], HEADERS)
112
113           See "Constructing a message" in Mail::Message::Construct::Build
114
115       $obj->forward(OPTIONS)
116
117           See "Constructing a message" in Mail::Message::Construct::Forward
118
119       $obj->forwardAttach(OPTIONS)
120
121           See "Constructing a message" in Mail::Message::Construct::Forward
122
123       $obj->forwardEncapsulate(OPTIONS)
124
125           See "Constructing a message" in Mail::Message::Construct::Forward
126
127       $obj->forwardInline(OPTIONS)
128
129           See "Constructing a message" in Mail::Message::Construct::Forward
130
131       $obj->forwardNo(OPTIONS)
132
133           See "Constructing a message" in Mail::Message::Construct::Forward
134
135       $obj->forwardPostlude
136
137           See "Constructing a message" in Mail::Message::Construct::Forward
138
139       $obj->forwardPrelude
140
141           See "Constructing a message" in Mail::Message::Construct::Forward
142
143       $obj->forwardSubject(STRING)
144
145           See "Constructing a message" in Mail::Message::Construct::Forward
146
147       Mail::Box::Message->read(FILEHANDLE⎪SCALAR⎪REF-SCALAR⎪ARRAY-OF-LINES,
148       OPTIONS)
149
150           See "Constructing a message" in Mail::Message::Construct::Read
151
152       $obj->rebuild(OPTIONS)
153
154           See "Constructing a message" in Mail::Message::Construct::Rebuild
155
156       $obj->reply(OPTIONS)
157
158           See "Constructing a message" in Mail::Message::Construct::Reply
159
160       $obj->replyPrelude([STRING⎪FIELD⎪ADDRESS⎪ARRAY-OF-THINGS])
161
162           See "Constructing a message" in Mail::Message::Construct::Reply
163
164       $obj->replySubject(STRING)
165
166       Mail::Box::Message->replySubject(STRING)
167
168           See "Constructing a message" in Mail::Message::Construct::Reply
169
170       The message
171
172       $obj->container
173
174           See "The message" in Mail::Message
175
176       $obj->copyTo(FOLDER, OPTIONS)
177
178           Copy the message to the indicated opened FOLDER, without deleting
179           the original.  The coerced message (the clone in the destination
180           folder) is returned.
181
182            Option      --Default
183            shallow       <false>
184            shallow_body  <false>
185            shallow_head  <false>
186            share         <false>
187
188           . shallow BOOLEAN
189
190               Used for clone(shallow).
191
192           . shallow_body BOOLEAN
193
194               Used for clone(shallow_body).
195
196           . shallow_head BOOLEAN
197
198               Used for clone(shallow_head).
199
200           . share BOOLEAN
201
202               Try to share the physical storage of the message between the
203               two folders.  Sometimes, they even may be of different types.
204               When not possible, this options will be silently ignored.
205
206           Example:
207
208            my $draft = $mgr->open(folder => 'Draft');
209            $message->copyTo($draft, share => 1);
210
211       $obj->folder([FOLDER])
212
213           In with folder did we detect this message/dummy?  This is a refer‐
214           ence to the folder-object.
215
216       $obj->isDummy
217
218           See "The message" in Mail::Message
219
220       $obj->isPart
221
222           See "The message" in Mail::Message
223
224       $obj->messageId
225
226           See "The message" in Mail::Message
227
228       $obj->moveTo(FOLDER, OPTIONS)
229
230           Move the message from this folder to the FOLDER specified.  This
231           will create a copy using clone() first.  Then, this original mes‐
232           sage is flagged to get deleted.  So until the source folder is
233           closed, two copies of the message may stay in memory.
234
235           The newly created message clone (part of the destination folder) is
236           returned.  All OPTIONS are passed to copyTo()
237
238            Option      --Default
239            shallow_body  <undef>
240            share         <true unless shallow_body exists>
241
242           . shallow_body BOOLEAN
243
244               Only create a shallow body, which means that the header can not
245               be reused.  A message can therefore not be shared in storage
246               unless explicitly stated.
247
248           . share BOOLEAN
249
250               When there is a chance that the original message can be
251               undeleted, then this must be set to false.  Otherwise a shallow
252               clone will be made, which will share the header which can be
253               modified in the undeleted message.
254
255           Example: of moving a message
256
257            my $t = $msg->moveTo('trash');
258
259           is equivalent to
260
261            my $t = $msg->copyTo('trash', share => 1);
262            $msg->delete;
263
264       $obj->print([FILEHANDLE])
265
266           See "The message" in Mail::Message
267
268       $obj->send([MAILER], OPTIONS)
269
270           See "The message" in Mail::Message
271
272       $obj->seqnr([INTEGER])
273
274           Get the number of this message is the current folder.  It starts
275           counting from zero.  Do not change the number.
276
277       $obj->size
278
279           See "The message" in Mail::Message
280
281       $obj->toplevel
282
283           See "The message" in Mail::Message
284
285       $obj->write([FILEHANDLE])
286
287           See "The message" in Mail::Message
288
289       The header
290
291       $obj->bcc
292
293           See "The header" in Mail::Message
294
295       $obj->cc
296
297           See "The header" in Mail::Message
298
299       $obj->date
300
301           See "The header" in Mail::Message
302
303       $obj->destinations
304
305           See "The header" in Mail::Message
306
307       $obj->from
308
309           See "The header" in Mail::Message
310
311       $obj->get(FIELDNAME)
312
313           See "The header" in Mail::Message
314
315       $obj->guessTimestamp
316
317           See "The header" in Mail::Message
318
319       $obj->head([HEAD])
320
321           See "The header" in Mail::Message
322
323       $obj->nrLines
324
325           See "The header" in Mail::Message
326
327       $obj->sender
328
329           See "The header" in Mail::Message
330
331       $obj->study(FIELDNAME)
332
333           See "The header" in Mail::Message
334
335       $obj->subject
336
337           See "The header" in Mail::Message
338
339       $obj->timestamp
340
341           See "The header" in Mail::Message
342
343       $obj->to
344
345           See "The header" in Mail::Message
346
347       The body
348
349       $obj->body([BODY])
350
351           See "The body" in Mail::Message
352
353       $obj->decoded(OPTIONS)
354
355           See "The body" in Mail::Message
356
357       $obj->encode(OPTIONS)
358
359           See "The body" in Mail::Message
360
361       $obj->isMultipart
362
363           See "The body" in Mail::Message
364
365       $obj->isNested
366
367           See "The body" in Mail::Message
368
369       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
370
371           See "The body" in Mail::Message
372
373       Flags
374
375       $obj->delete
376
377           See "Flags" in Mail::Message
378
379       $obj->deleted([BOOLEAN])
380
381           See "Flags" in Mail::Message
382
383       $obj->isDeleted
384
385           See "Flags" in Mail::Message
386
387       $obj->isModified
388
389           See "Flags" in Mail::Message
390
391       $obj->label(LABEL⎪PAIRS)
392
393           See "Flags" in Mail::Message
394
395       $obj->labels
396
397           See "Flags" in Mail::Message
398
399       $obj->labelsToStatus
400
401           See "Flags" in Mail::Message
402
403       $obj->modified([BOOLEAN])
404
405           See "Flags" in Mail::Message
406
407       $obj->statusToLabels
408
409           See "Flags" in Mail::Message
410
411       The whole message as text
412
413       $obj->file
414
415           See "The whole message as text" in Mail::Message::Construct::Text
416
417       $obj->lines
418
419           See "The whole message as text" in Mail::Message::Construct::Text
420
421       $obj->printStructure([FILEHANDLE⎪undef],[INDENT])
422
423           See "The whole message as text" in Mail::Message::Construct::Text
424
425       $obj->string
426
427           See "The whole message as text" in Mail::Message::Construct::Text
428
429       Internals
430
431       $obj->clonedFrom
432
433           See "Internals" in Mail::Message
434
435       Mail::Box::Message->coerce(MESSAGE, OPTIONS)
436
437           See "Internals" in Mail::Message
438
439       $obj->diskDelete
440
441           Remove a message from disk.  This is not from the folder, but
442           everything else, like parts of the message which are stored outside
443           from the folder.
444
445       $obj->isDelayed
446
447           See "Internals" in Mail::Message
448
449       $obj->readBody(PARSER, HEAD [, BODYTYPE])
450
451           Read the body of one message.  The PARSER gives access to the
452           folder file.  The HEAD has been read with readHead().  The optional
453           BODYTYPE supplies the class name of the body to be created, or a
454           code reference to a routine which can produce a body type based on
455           the head (passed as first argument).
456
457           By default, the BODYTYPE will call Mail::Box::determineBodyType()
458           where the message will be added to.
459
460       $obj->readFromParser(PARSER, [BODYTYPE])
461
462           See "Internals" in Mail::Message
463
464       $obj->readHead(PARSER [,CLASS])
465
466           See "Internals" in Mail::Message
467
468       $obj->recursiveRebuildPart(PART, OPTIONS)
469
470           See "Internals" in Mail::Message::Construct::Rebuild
471
472       $obj->storeBody(BODY)
473
474           See "Internals" in Mail::Message
475
476       $obj->takeMessageId([STRING])
477
478           See "Internals" in Mail::Message
479
480       Error handling
481
482       $obj->AUTOLOAD
483
484           See "METHODS" in Mail::Message::Construct
485
486       $obj->addReport(OBJECT)
487
488           See "Error handling" in Mail::Reporter
489
490       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
491
492       Mail::Box::Message->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
493       CALLBACK])
494
495           See "Error handling" in Mail::Reporter
496
497       $obj->errors
498
499           See "Error handling" in Mail::Reporter
500
501       $obj->log([LEVEL [,STRINGS]])
502
503       Mail::Box::Message->log([LEVEL [,STRINGS]])
504
505           See "Error handling" in Mail::Reporter
506
507       $obj->logPriority(LEVEL)
508
509       Mail::Box::Message->logPriority(LEVEL)
510
511           See "Error handling" in Mail::Reporter
512
513       $obj->logSettings
514
515           See "Error handling" in Mail::Reporter
516
517       $obj->notImplemented
518
519           See "Error handling" in Mail::Reporter
520
521       $obj->report([LEVEL])
522
523           See "Error handling" in Mail::Reporter
524
525       $obj->reportAll([LEVEL])
526
527           See "Error handling" in Mail::Reporter
528
529       $obj->shortSize([VALUE])
530
531       Mail::Box::Message->shortSize([VALUE])
532
533           See "Error handling" in Mail::Message
534
535       $obj->shortString
536
537           See "Error handling" in Mail::Message
538
539       $obj->trace([LEVEL])
540
541           See "Error handling" in Mail::Reporter
542
543       $obj->warnings
544
545           See "Error handling" in Mail::Reporter
546
547       Cleanup
548
549       $obj->DESTROY
550
551           See "Cleanup" in Mail::Message
552
553       $obj->destruct
554
555           Removes most of the memory occupied by the message by detaching the
556           header and body.  Then, the object changes into a Mail::Box::Mes‐
557           sage::Destructed which will catch all attempts to access the header
558           and body.  Be careful with the usage of this method.
559
560       $obj->inGlobalDestruction
561
562           See "Cleanup" in Mail::Reporter
563

DETAILS

DIAGNOSTICS

566       Error: Cannot include forward source as $include.
567
568       Unknown alternative for the forward(include).  Valid choices are "NO",
569       "INLINE", "ATTACH", and "ENCAPSULATE".
570
571       Error: Cannot include reply source as $include.
572
573       Unknown alternative for the "include" option of reply().  Valid choices
574       are "NO", "INLINE", and "ATTACH".
575
576       Error: Method bounce requires To, Cc, or Bcc
577
578       The message bounce() method forwards a received message off to someone
579       else without modification; you must specified it's new destination.  If
580       you have the urge not to specify any destination, you probably are
581       looking for reply(). When you wish to modify the content, use for‐
582       ward().
583
584       Error: Method forwardAttach requires a preamble
585
586       Error: Method forwardEncapsulate requires a preamble
587
588       Error: No address to create forwarded to.
589
590       If a forward message is created, a destination address must be speci‐
591       fied.
592
593       Error: No default mailer found to send message.
594
595       The message send() mechanism had not enough information to automati‐
596       cally find a mail transfer agent to sent this message.  Specify a
597       mailer explicitly using the "via" options.
598
599       Error: No rebuild rule $name defined.
600
601       Error: Only build() Mail::Message's; they are not in a folder yet
602
603       You may wish to construct a message to be stored in a some kind of
604       folder, but you need to do that in two steps.  First, create a normal
605       Mail::Message, and then add it to the folder.  During this
606       Mail::Box::addMessage() process, the message will get coerce()-d into
607       the right message type, adding storage information and the like.
608
609       Error: Package $package does not implement $method.
610
611       Fatal error: the specific package (or one of its superclasses) does not
612       implement this method where it should. This message means that some
613       other related classes do implement this method however the class at
614       hand does not.  Probably you should investigate this and probably
615       inform the author of the package.
616

LICENSE

622       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
623       ChangeLog.
624
625       This program is free software; you can redistribute it and/or modify it
626       under the same terms as Perl itself.  See
627       http://www.perl.com/perl/misc/Artistic.html
628
629
630
631perl v5.8.8                       2007-03-25             Mail::Box::Message(3)