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.
34       Changing from stage, the message's body and head objects may change.
35
36       Extends "DESCRIPTION" in Mail::Message.
37

METHODS

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

DETAILS

489       Extends "DETAILS" in Mail::Message.
490

DIAGNOSTICS

492       Error: Cannot coerce a $class object into a $class object
493       Error: Cannot include forward source as $include.
494           Unknown alternative for the forward(include).  Valid choices are
495           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
496
497       Error: Cannot include reply source as $include.
498           Unknown alternative for the "include" option of reply().  Valid
499           choices are "NO", "INLINE", and "ATTACH".
500
501       Error: Method bounce requires To, Cc, or Bcc
502           The message bounce() method forwards a received message off to
503           someone else without modification; you must specified it's new
504           destination.  If you have the urge not to specify any destination,
505           you probably are looking for reply(). When you wish to modify the
506           content, use forward().
507
508       Error: Method forwardAttach requires a preamble
509       Error: Method forwardEncapsulate requires a preamble
510       Error: No address to create forwarded to.
511           If a forward message is created, a destination address must be
512           specified.
513
514       Error: No default mailer found to send message.
515           The message send() mechanism had not enough information to
516           automatically find a mail transfer agent to sent this message.
517           Specify a mailer explicitly using the "via" options.
518
519       Error: No rebuild rule $name defined.
520       Error: Only build() Mail::Message's; they are not in a folder yet
521           You may wish to construct a message to be stored in a some kind of
522           folder, but you need to do that in two steps.  First, create a
523           normal Mail::Message, and then add it to the folder.  During this
524           Mail::Box::addMessage() process, the message will get coerce()-d
525           into the right message type, adding storage information and the
526           like.
527
528       Error: Package $package does not implement $method.
529           Fatal error: the specific package (or one of its superclasses) does
530           not implement this method where it should. This message means that
531           some other related classes do implement this method however the
532           class at hand does not.  Probably you should investigate this and
533           probably inform the author of the package.
534
535       Error: coercion starts with some object
536

SEE ALSO

538       This module is part of Mail-Box distribution version 3.009, built on
539       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
540

LICENSE

542       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
543       ChangeLog.
544
545       This program is free software; you can redistribute it and/or modify it
546       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
547
548
549
550perl v5.34.0                      2022-01-21             Mail::Box::Message(3)
Impressum