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
37 Constructors
38 $obj->clone(OPTIONS)
39 See "Constructors" in Mail::Message
40 Mail::Box::Message->new(OPTIONS)
42 -Option --Defined in --Default
43 body Mail::Message undef
44 body_type <from folder>
45 deleted Mail::Message <false>
46 field_type Mail::Message undef
47 folder <required>
48 head Mail::Message undef
49 head_type Mail::Message Mail::Message::Head::Complete
50 labels Mail::Message {}
51 log Mail::Reporter 'WARNINGS'
52 messageId Mail::Message undef
53 modified Mail::Message <false>
54 size undef
55 trace Mail::Reporter 'WARNINGS'
56 trusted Mail::Message <false>
57 body => OBJECT
59 body_type => CODE|CLASS
60 If the body of a message is used delay-loaded, the message must
61 what type of message to become when it finally gets parsed. The
62 folder which is delaying the load must specify the algorithm to
63 determine that type.
64 deleted => BOOLEAN
66 field_type => CLASS
67 folder => FOLDER
68 The folder where this message appeared in. The argument is an
69 instance of (a sub-class of) a Mail::Box.
70 head => OBJECT
72 head_type => CLASS
73 labels => ARRAY|HASH
74 log => LEVEL
75 messageId => STRING
76 modified => BOOLEAN
77 size => INTEGER
78 The size of the message, which includes head and body, but
79 without the message separators which may be used by the folder
80 type.
81 trace => LEVEL
83 trusted => BOOLEAN
84 Constructing a message
86 $obj->bounce([RG-OBJECT|OPTIONS])
87 See "Constructing a message" in Mail::Message::Construct::Bounce
88 Mail::Box::Message->build([MESSAGE|PART|BODY], CONTENT)
90 See "Constructing a message" in Mail::Message::Construct::Build
91 Mail::Box::Message->buildFromBody(BODY, [HEAD], HEADERS)
93 See "Constructing a message" in Mail::Message::Construct::Build
94 $obj->forward(OPTIONS)
96 See "Constructing a message" in Mail::Message::Construct::Forward
97 $obj->forwardAttach(OPTIONS)
99 See "Constructing a message" in Mail::Message::Construct::Forward
100 $obj->forwardEncapsulate(OPTIONS)
102 See "Constructing a message" in Mail::Message::Construct::Forward
103 $obj->forwardInline(OPTIONS)
105 See "Constructing a message" in Mail::Message::Construct::Forward
106 $obj->forwardNo(OPTIONS)
108 See "Constructing a message" in Mail::Message::Construct::Forward
109 $obj->forwardPostlude
111 See "Constructing a message" in Mail::Message::Construct::Forward
112 $obj->forwardPrelude
114 See "Constructing a message" in Mail::Message::Construct::Forward
115 $obj->forwardSubject(STRING)
117 See "Constructing a message" in Mail::Message::Construct::Forward
118 Mail::Box::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
120 OPTIONS)
121 See "Constructing a message" in Mail::Message::Construct::Read
122 $obj->rebuild(OPTIONS)
124 See "Constructing a message" in Mail::Message::Construct::Rebuild
125 $obj->reply(OPTIONS)
127 See "Constructing a message" in Mail::Message::Construct::Reply
128 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
130 See "Constructing a message" in Mail::Message::Construct::Reply
131 $obj->replySubject(STRING)
133 Mail::Box::Message->replySubject(STRING)
134 See "Constructing a message" in Mail::Message::Construct::Reply
136 The message
138 $obj->container
139 See "The message" in Mail::Message
140 $obj->copyTo(FOLDER, OPTIONS)
142 Copy the message to the indicated opened FOLDER, without deleting
143 the original. The coerced message (the clone in the destination
144 folder) is returned.
145 -Option --Default
147 shallow <false>
148 shallow_body <false>
149 shallow_head <false>
150 share <false>
151 shallow => BOOLEAN
153 Used for clone(shallow).
154 shallow_body => BOOLEAN
156 Used for clone(shallow_body).
157 shallow_head => BOOLEAN
159 Used for clone(shallow_head).
160 share => BOOLEAN
162 Try to share the physical storage of the message between the two
163 folders. Sometimes, they even may be of different types. When
164 not possible, this options will be silently ignored.
165 example:
167 my $draft = $mgr->open(folder => 'Draft');
169 $message->copyTo($draft, share => 1);
170 $obj->folder([FOLDER])
172 In with folder did we detect this message/dummy? This is a
173 reference to the folder-object.
174 $obj->isDummy
176 See "The message" in Mail::Message
177 $obj->isPart
179 See "The message" in Mail::Message
180 $obj->messageId
182 See "The message" in Mail::Message
183 $obj->moveTo(FOLDER, OPTIONS)
185 Move the message from this folder to the FOLDER specified. This
186 will create a copy using clone() first. Then, this original
187 message is flagged to get deleted. So until the source folder is
188 closed, two copies of the message may stay in memory.
189 The newly created message clone (part of the destination folder) is
191 returned. All OPTIONS are passed to copyTo()
192 -Option --Default
194 shallow_body <undef>
195 share <true unless shallow_body exists>
196 shallow_body => BOOLEAN
198 Only create a shallow body, which means that the header can not
199 be reused. A message can therefore not be shared in storage
200 unless explicitly stated.
201 share => BOOLEAN
203 When there is a chance that the original message can be
204 undeleted, then this must be set to false. Otherwise a shallow
205 clone will be made, which will share the header which can be
206 modified in the undeleted message.
207 example: of moving a message
209 my $t = $msg->moveTo('trash');
211 is equivalent to
213 my $t = $msg->copyTo('trash', share => 1);
215 $msg->delete;
216 $obj->print([FILEHANDLE])
218 See "The message" in Mail::Message
219 $obj->send([MAILER], OPTIONS)
221 See "The message" in Mail::Message
222 $obj->seqnr([INTEGER])
224 Get the number of this message is the current folder. It starts
225 counting from zero. Do not change the number.
226 $obj->size
228 See "The message" in Mail::Message
229 $obj->toplevel
231 See "The message" in Mail::Message
232 $obj->write([FILEHANDLE])
234 See "The message" in Mail::Message
235 The header
237 $obj->bcc
238 See "The header" in Mail::Message
239 $obj->cc
241 See "The header" in Mail::Message
242 $obj->date
244 See "The header" in Mail::Message
245 $obj->destinations
247 See "The header" in Mail::Message
248 $obj->from
250 See "The header" in Mail::Message
251 $obj->get(FIELDNAME)
253 See "The header" in Mail::Message
254 $obj->guessTimestamp
256 See "The header" in Mail::Message
257 $obj->head([HEAD])
259 See "The header" in Mail::Message
260 $obj->nrLines
262 See "The header" in Mail::Message
263 $obj->sender
265 See "The header" in Mail::Message
266 $obj->study(FIELDNAME)
268 See "The header" in Mail::Message
269 $obj->subject
271 See "The header" in Mail::Message
272 $obj->timestamp
274 See "The header" in Mail::Message
275 $obj->to
277 See "The header" in Mail::Message
278 The body
280 $obj->body([BODY])
281 See "The body" in Mail::Message
282 $obj->contentType
284 See "The body" in Mail::Message
285 $obj->decoded(OPTIONS)
287 See "The body" in Mail::Message
288 $obj->encode(OPTIONS)
290 See "The body" in Mail::Message
291 $obj->isMultipart
293 See "The body" in Mail::Message
294 $obj->isNested
296 See "The body" in Mail::Message
297 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
299 See "The body" in Mail::Message
300 Flags
302 $obj->delete
303 See "Flags" in Mail::Message
304 $obj->deleted([BOOLEAN])
306 See "Flags" in Mail::Message
307 $obj->isDeleted
309 See "Flags" in Mail::Message
310 $obj->isModified
312 See "Flags" in Mail::Message
313 $obj->label(LABEL|PAIRS)
315 See "Flags" in Mail::Message
316 $obj->labels
318 See "Flags" in Mail::Message
319 $obj->labelsToStatus
321 See "Flags" in Mail::Message
322 $obj->modified([BOOLEAN])
324 See "Flags" in Mail::Message
325 $obj->statusToLabels
327 See "Flags" in Mail::Message
328 The whole message as text
330 $obj->file
331 See "The whole message as text" in Mail::Message::Construct::Text
332 $obj->lines
334 See "The whole message as text" in Mail::Message::Construct::Text
335 $obj->printStructure([FILEHANDLE|undef],[INDENT])
337 See "The whole message as text" in Mail::Message::Construct::Text
338 $obj->string
340 See "The whole message as text" in Mail::Message::Construct::Text
341 Internals
343 $obj->clonedFrom
344 See "Internals" in Mail::Message
345 Mail::Box::Message->coerce(MESSAGE, OPTIONS)
347 See "Internals" in Mail::Message
348 $obj->diskDelete
350 Remove a message from disk. This is not from the folder, but
351 everything else, like parts of the message which are stored outside
352 from the folder.
353 $obj->isDelayed
355 See "Internals" in Mail::Message
356 $obj->readBody(PARSER, HEAD [, BODYTYPE])
358 Read the body of one message. The PARSER gives access to the
359 folder file. The HEAD has been read with readHead(). The optional
360 BODYTYPE supplies the class name of the body to be created, or a
361 code reference to a routine which can produce a body type based on
362 the head (passed as first argument).
363 By default, the BODYTYPE will call Mail::Box::determineBodyType()
365 where the message will be added to.
366 $obj->readFromParser(PARSER, [BODYTYPE])
368 See "Internals" in Mail::Message
369 $obj->readHead(PARSER [,CLASS])
371 See "Internals" in Mail::Message
372 $obj->recursiveRebuildPart(PART, OPTIONS)
374 See "Internals" in Mail::Message::Construct::Rebuild
375 $obj->storeBody(BODY)
377 See "Internals" in Mail::Message
378 $obj->takeMessageId([STRING])
380 See "Internals" in Mail::Message
381 Error handling
383 $obj->AUTOLOAD
384 See "METHODS" in Mail::Message::Construct
385 $obj->addReport(OBJECT)
387 See "Error handling" in Mail::Reporter
388 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
390 Mail::Box::Message->defaultTrace([LEVEL]|[LOGLEVEL,
391 TRACELEVEL]|[LEVEL, CALLBACK])
392 See "Error handling" in Mail::Reporter
394 $obj->errors
396 See "Error handling" in Mail::Reporter
397 $obj->log([LEVEL [,STRINGS]])
399 Mail::Box::Message->log([LEVEL [,STRINGS]])
400 See "Error handling" in Mail::Reporter
402 $obj->logPriority(LEVEL)
404 Mail::Box::Message->logPriority(LEVEL)
405 See "Error handling" in Mail::Reporter
407 $obj->logSettings
409 See "Error handling" in Mail::Reporter
410 $obj->notImplemented
412 See "Error handling" in Mail::Reporter
413 $obj->report([LEVEL])
415 See "Error handling" in Mail::Reporter
416 $obj->reportAll([LEVEL])
418 See "Error handling" in Mail::Reporter
419 $obj->shortSize([VALUE])
421 Mail::Box::Message->shortSize([VALUE])
422 See "Error handling" in Mail::Message
424 $obj->shortString
426 See "Error handling" in Mail::Message
427 $obj->trace([LEVEL])
429 See "Error handling" in Mail::Reporter
430 $obj->warnings
432 See "Error handling" in Mail::Reporter
433 Cleanup
435 $obj->DESTROY
436 See "Cleanup" in Mail::Message
437 $obj->destruct
439 Removes most of the memory occupied by the message by detaching the
440 header and body. Then, the object changes into a
441 Mail::Box::Message::Destructed which will catch all attempts to
442 access the header and body. Be careful with the usage of this
443 method.
444 $obj->inGlobalDestruction
446 See "Cleanup" in Mail::Reporter
447
449 Error: Cannot coerce a $class object into a $class object
450 Error: Cannot include forward source as $include.
451 Unknown alternative for the forward(include). Valid choices are
452 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
453 Error: Cannot include reply source as $include.
455 Unknown alternative for the "include" option of reply(). Valid
456 choices are "NO", "INLINE", and "ATTACH".
457 Error: Method bounce requires To, Cc, or Bcc
459 The message bounce() method forwards a received message off to
460 someone else without modification; you must specified it's new
461 destination. If you have the urge not to specify any destination,
462 you probably are looking for reply(). When you wish to modify the
463 content, use forward().
464 Error: Method forwardAttach requires a preamble
466 Error: Method forwardEncapsulate requires a preamble
467 Error: No address to create forwarded to.
468 If a forward message is created, a destination address must be
469 specified.
470 Error: No default mailer found to send message.
472 The message send() mechanism had not enough information to
473 automatically find a mail transfer agent to sent this message.
474 Specify a mailer explicitly using the "via" options.
475 Error: No rebuild rule $name defined.
477 Error: Only build() Mail::Message's; they are not in a folder yet
478 You may wish to construct a message to be stored in a some kind of
479 folder, but you need to do that in two steps. First, create a
480 normal Mail::Message, and then add it to the folder. During this
481 Mail::Box::addMessage() process, the message will get coerce()-d
482 into the right message type, adding storage information and the
483 like.
484 Error: Package $package does not implement $method.
486 Fatal error: the specific package (or one of its superclasses) does
487 not implement this method where it should. This message means that
488 some other related classes do implement this method however the
489 class at hand does not. Probably you should investigate this and
490 probably inform the author of the package.
491 Error: coercion starts with some object
493
495 This module is part of Mail-Box distribution version 2.097, built on
496 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
497
499 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
500 ChangeLog.
501 This program is free software; you can redistribute it and/or modify it
503 under the same terms as Perl itself. See
504 http://www.perl.com/perl/misc/Artistic.html
505perl v5.12.3 2011-01-26 Mail::Box::Message(3)