1Mail::Box::Message(3) User Contributed Perl DocumentationMail::Box::Message(3)
2
6 Mail::Box::Message - manage one message within a mail-folder
7
9 Mail::Box::Message
10 is a Mail::Message
11 is a Mail::Reporter
12 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
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
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 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 Extends "DESCRIPTION" in Mail::Message.
37
39 Extends "METHODS" in Mail::Message.
40 Constructors
42 Extends "Constructors" in Mail::Message.
43 $obj->clone(%options)
45 Inherited, see "Constructors" in Mail::Message
46 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 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 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 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 trace => LEVEL
89 trusted => BOOLEAN
90 Constructing a message
92 Extends "Constructing a message" in Mail::Message.
93 $obj->bounce( [<$rg_object|%options>] )
95 Inherited, see "Constructing a message" in
96 Mail::Message::Construct::Bounce
97 Mail::Box::Message->build( [$message|$part|$body], $content )
99 Inherited, see "Constructing a message" in
100 Mail::Message::Construct::Build
101 Mail::Box::Message->buildFromBody($body, [$head], $headers)
103 Inherited, see "Constructing a message" in
104 Mail::Message::Construct::Build
105 $obj->forward(%options)
107 Inherited, see "Constructing a message" in
108 Mail::Message::Construct::Forward
109 $obj->forwardAttach(%options)
111 Inherited, see "Constructing a message" in
112 Mail::Message::Construct::Forward
113 $obj->forwardEncapsulate(%options)
115 Inherited, see "Constructing a message" in
116 Mail::Message::Construct::Forward
117 $obj->forwardInline(%options)
119 Inherited, see "Constructing a message" in
120 Mail::Message::Construct::Forward
121 $obj->forwardNo(%options)
123 Inherited, see "Constructing a message" in
124 Mail::Message::Construct::Forward
125 $obj->forwardPostlude()
127 Inherited, see "Constructing a message" in
128 Mail::Message::Construct::Forward
129 $obj->forwardPrelude()
131 Inherited, see "Constructing a message" in
132 Mail::Message::Construct::Forward
133 $obj->forwardSubject(STRING)
135 Inherited, see "Constructing a message" in
136 Mail::Message::Construct::Forward
137 Mail::Box::Message->read($fh|STRING|SCALAR|ARRAY, %options)
139 Inherited, see "Constructing a message" in
140 Mail::Message::Construct::Read
141 $obj->rebuild(%options)
143 Inherited, see "Constructing a message" in
144 Mail::Message::Construct::Rebuild
145 $obj->reply(%options)
147 Inherited, see "Constructing a message" in
148 Mail::Message::Construct::Reply
149 $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
151 Inherited, see "Constructing a message" in
152 Mail::Message::Construct::Reply
153 $obj->replySubject(STRING)
155 Mail::Box::Message->replySubject(STRING)
156 Inherited, see "Constructing a message" in
157 Mail::Message::Construct::Reply
158 The message
160 Extends "The message" in Mail::Message.
161 $obj->container()
163 Inherited, see "The message" in Mail::Message
164 $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 -Option --Default
171 shallow <false>
172 shallow_body <false>
173 shallow_head <false>
174 share <false>
175 shallow => BOOLEAN
177 Used for clone(shallow).
178 shallow_body => BOOLEAN
180 Used for clone(shallow_body).
181 shallow_head => BOOLEAN
183 Used for clone(shallow_head).
184 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 example:
191 my $draft = $mgr->open(folder => 'Draft');
193 $message->copyTo($draft, share => 1);
194 $obj->folder( [$folder] )
196 In with folder did we detect this message/dummy? This is a
197 reference to the folder-object.
198 $obj->isDummy()
200 Inherited, see "The message" in Mail::Message
201 $obj->isPart()
203 Inherited, see "The message" in Mail::Message
204 $obj->messageId()
206 Inherited, see "The message" in Mail::Message
207 $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 The newly created message clone (part of the destination folder) is
215 returned. All %options are passed to copyTo()
216 -Option --Default
218 shallow_body <undef>
219 share <true unless shallow_body exists>
220 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 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 example: of moving a message
233 my $trash = Mail::Box::Mbox->new(folder => 'trash');
235 my $t = $msg->moveTo($trash);
236 is equivalent to
238 my $t = $msg->copyTo($trash, share => 1);
240 $msg->delete;
241 $obj->partNumber()
243 Inherited, see "The message" in Mail::Message
244 $obj->print( [$fh] )
246 Inherited, see "The message" in Mail::Message
247 $obj->send( [$mailer], %options )
249 Inherited, see "The message" in Mail::Message
250 $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 $obj->size()
256 Inherited, see "The message" in Mail::Message
257 $obj->toplevel()
259 Inherited, see "The message" in Mail::Message
260 $obj->write( [$fh] )
262 Inherited, see "The message" in Mail::Message
263 The header
265 Extends "The header" in Mail::Message.
266 $obj->bcc()
268 Inherited, see "The header" in Mail::Message
269 $obj->cc()
271 Inherited, see "The header" in Mail::Message
272 $obj->date()
274 Inherited, see "The header" in Mail::Message
275 $obj->destinations()
277 Inherited, see "The header" in Mail::Message
278 $obj->from()
280 Inherited, see "The header" in Mail::Message
281 $obj->get($fieldname)
283 Inherited, see "The header" in Mail::Message
284 $obj->guessTimestamp()
286 Inherited, see "The header" in Mail::Message
287 $obj->head( [$head] )
289 Inherited, see "The header" in Mail::Message
290 $obj->nrLines()
292 Inherited, see "The header" in Mail::Message
293 $obj->sender()
295 Inherited, see "The header" in Mail::Message
296 $obj->study($fieldname)
298 Inherited, see "The header" in Mail::Message
299 $obj->subject()
301 Inherited, see "The header" in Mail::Message
302 $obj->timestamp()
304 Inherited, see "The header" in Mail::Message
305 $obj->to()
307 Inherited, see "The header" in Mail::Message
308 The body
310 Extends "The body" in Mail::Message.
311 $obj->body( [$body] )
313 Inherited, see "The body" in Mail::Message
314 $obj->contentType()
316 Inherited, see "The body" in Mail::Message
317 $obj->decoded(%options)
319 Inherited, see "The body" in Mail::Message
320 $obj->encode(%options)
322 Inherited, see "The body" in Mail::Message
323 $obj->isMultipart()
325 Inherited, see "The body" in Mail::Message
326 $obj->isNested()
328 Inherited, see "The body" in Mail::Message
329 $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
331 Inherited, see "The body" in Mail::Message
332 Flags
334 Extends "Flags" in Mail::Message.
335 $obj->delete()
337 Inherited, see "Flags" in Mail::Message
338 $obj->deleted( [BOOLEAN] )
340 Inherited, see "Flags" in Mail::Message
341 $obj->isDeleted()
343 Inherited, see "Flags" in Mail::Message
344 $obj->isModified()
346 Inherited, see "Flags" in Mail::Message
347 $obj->label($label|PAIRS)
349 Inherited, see "Flags" in Mail::Message
350 $obj->labels()
352 Inherited, see "Flags" in Mail::Message
353 $obj->labelsToStatus()
355 Inherited, see "Flags" in Mail::Message
356 $obj->modified( [BOOLEAN] )
358 Inherited, see "Flags" in Mail::Message
359 $obj->statusToLabels()
361 Inherited, see "Flags" in Mail::Message
362 The whole message as text
364 Extends "The whole message as text" in Mail::Message.
365 $obj->file()
367 Inherited, see "The whole message as text" in
368 Mail::Message::Construct::Text
369 $obj->lines()
371 Inherited, see "The whole message as text" in
372 Mail::Message::Construct::Text
373 $obj->printStructure( [$fh|undef],[$indent] )
375 Inherited, see "The whole message as text" in
376 Mail::Message::Construct::Text
377 $obj->string()
379 Inherited, see "The whole message as text" in
380 Mail::Message::Construct::Text
381 Internals
383 Extends "Internals" in Mail::Message.
384 $obj->clonedFrom()
386 Inherited, see "Internals" in Mail::Message
387 Mail::Box::Message->coerce($message, %options)
389 Inherited, see "Internals" in Mail::Message
390 $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 $obj->isDelayed()
397 Inherited, see "Internals" in Mail::Message
398 $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 By default, the $bodytype will call Mail::Box::determineBodyType()
407 where the message will be added to.
408 $obj->readFromParser( $parser, [$bodytype] )
410 Inherited, see "Internals" in Mail::Message
411 $obj->readHead( $parser, [$class] )
413 Inherited, see "Internals" in Mail::Message
414 $obj->recursiveRebuildPart($part, %options)
416 Inherited, see "Internals" in Mail::Message::Construct::Rebuild
417 $obj->storeBody($body)
419 Inherited, see "Internals" in Mail::Message
420 $obj->takeMessageId( [STRING] )
422 Inherited, see "Internals" in Mail::Message
423 Error handling
425 Extends "Error handling" in Mail::Message.
426 $obj->AUTOLOAD()
428 Inherited, see "METHODS" in Mail::Message::Construct
429 $obj->addReport($object)
431 Inherited, see "Error handling" in Mail::Reporter
432 $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 $obj->errors()
440 Inherited, see "Error handling" in Mail::Reporter
441 $obj->log( [$level, [$strings]] )
443 Mail::Box::Message->log( [$level, [$strings]] )
444 Inherited, see "Error handling" in Mail::Reporter
445 $obj->logPriority($level)
447 Mail::Box::Message->logPriority($level)
448 Inherited, see "Error handling" in Mail::Reporter
449 $obj->logSettings()
451 Inherited, see "Error handling" in Mail::Reporter
452 $obj->notImplemented()
454 Inherited, see "Error handling" in Mail::Reporter
455 $obj->report( [$level] )
457 Inherited, see "Error handling" in Mail::Reporter
458 $obj->reportAll( [$level] )
460 Inherited, see "Error handling" in Mail::Reporter
461 $obj->shortSize( [$value] )
463 Mail::Box::Message->shortSize( [$value] )
464 Inherited, see "Error handling" in Mail::Message
465 $obj->shortString()
467 Inherited, see "Error handling" in Mail::Message
468 $obj->trace( [$level] )
470 Inherited, see "Error handling" in Mail::Reporter
471 $obj->warnings()
473 Inherited, see "Error handling" in Mail::Reporter
474 Cleanup
476 Extends "Cleanup" in Mail::Message.
477 $obj->DESTROY()
479 Inherited, see "Cleanup" in Mail::Reporter
480 $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
489 Extends "DETAILS" in Mail::Message.
490
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 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 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 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 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 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 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 Error: coercion starts with some object
536
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
542 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
543 ChangeLog.
544 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/
547perl v5.34.0 2022-01-21 Mail::Box::Message(3)