1Mail::Box::Message(3) User Contributed Perl DocumentationMail::Box::Message(3)
2
3
4
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
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
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
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
37 Constructors
38 $obj->clone(OPTIONS)
39 See "Constructors" in Mail::Message
40
41 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
58 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
65 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
71 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
82 trace => LEVEL
83 trusted => BOOLEAN
84
85 Constructing a message
86 $obj->bounce([RG-OBJECT|OPTIONS])
87 See "Constructing a message" in Mail::Message::Construct::Bounce
88
89 Mail::Box::Message->build([MESSAGE|PART|BODY], CONTENT)
90 See "Constructing a message" in Mail::Message::Construct::Build
91
92 Mail::Box::Message->buildFromBody(BODY, [HEAD], HEADERS)
93 See "Constructing a message" in Mail::Message::Construct::Build
94
95 $obj->forward(OPTIONS)
96 See "Constructing a message" in Mail::Message::Construct::Forward
97
98 $obj->forwardAttach(OPTIONS)
99 See "Constructing a message" in Mail::Message::Construct::Forward
100
101 $obj->forwardEncapsulate(OPTIONS)
102 See "Constructing a message" in Mail::Message::Construct::Forward
103
104 $obj->forwardInline(OPTIONS)
105 See "Constructing a message" in Mail::Message::Construct::Forward
106
107 $obj->forwardNo(OPTIONS)
108 See "Constructing a message" in Mail::Message::Construct::Forward
109
110 $obj->forwardPostlude
111 See "Constructing a message" in Mail::Message::Construct::Forward
112
113 $obj->forwardPrelude
114 See "Constructing a message" in Mail::Message::Construct::Forward
115
116 $obj->forwardSubject(STRING)
117 See "Constructing a message" in Mail::Message::Construct::Forward
118
119 Mail::Box::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
120 OPTIONS)
121 See "Constructing a message" in Mail::Message::Construct::Read
122
123 $obj->rebuild(OPTIONS)
124 See "Constructing a message" in Mail::Message::Construct::Rebuild
125
126 $obj->reply(OPTIONS)
127 See "Constructing a message" in Mail::Message::Construct::Reply
128
129 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
130 See "Constructing a message" in Mail::Message::Construct::Reply
131
132 $obj->replySubject(STRING)
133 Mail::Box::Message->replySubject(STRING)
134
135 See "Constructing a message" in Mail::Message::Construct::Reply
136
137 The message
138 $obj->container
139 See "The message" in Mail::Message
140
141 $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
146 -Option --Default
147 shallow <false>
148 shallow_body <false>
149 shallow_head <false>
150 share <false>
151
152 shallow => BOOLEAN
153 Used for clone(shallow).
154
155 shallow_body => BOOLEAN
156 Used for clone(shallow_body).
157
158 shallow_head => BOOLEAN
159 Used for clone(shallow_head).
160
161 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
166 example:
167
168 my $draft = $mgr->open(folder => 'Draft');
169 $message->copyTo($draft, share => 1);
170
171 $obj->folder([FOLDER])
172 In with folder did we detect this message/dummy? This is a
173 reference to the folder-object.
174
175 $obj->isDummy
176 See "The message" in Mail::Message
177
178 $obj->isPart
179 See "The message" in Mail::Message
180
181 $obj->messageId
182 See "The message" in Mail::Message
183
184 $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
190 The newly created message clone (part of the destination folder) is
191 returned. All OPTIONS are passed to copyTo()
192
193 -Option --Default
194 shallow_body <undef>
195 share <true unless shallow_body exists>
196
197 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
202 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
208 example: of moving a message
209
210 my $t = $msg->moveTo('trash');
211
212 is equivalent to
213
214 my $t = $msg->copyTo('trash', share => 1);
215 $msg->delete;
216
217 $obj->print([FILEHANDLE])
218 See "The message" in Mail::Message
219
220 $obj->send([MAILER], OPTIONS)
221 See "The message" in Mail::Message
222
223 $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
227 $obj->size
228 See "The message" in Mail::Message
229
230 $obj->toplevel
231 See "The message" in Mail::Message
232
233 $obj->write([FILEHANDLE])
234 See "The message" in Mail::Message
235
236 The header
237 $obj->bcc
238 See "The header" in Mail::Message
239
240 $obj->cc
241 See "The header" in Mail::Message
242
243 $obj->date
244 See "The header" in Mail::Message
245
246 $obj->destinations
247 See "The header" in Mail::Message
248
249 $obj->from
250 See "The header" in Mail::Message
251
252 $obj->get(FIELDNAME)
253 See "The header" in Mail::Message
254
255 $obj->guessTimestamp
256 See "The header" in Mail::Message
257
258 $obj->head([HEAD])
259 See "The header" in Mail::Message
260
261 $obj->nrLines
262 See "The header" in Mail::Message
263
264 $obj->sender
265 See "The header" in Mail::Message
266
267 $obj->study(FIELDNAME)
268 See "The header" in Mail::Message
269
270 $obj->subject
271 See "The header" in Mail::Message
272
273 $obj->timestamp
274 See "The header" in Mail::Message
275
276 $obj->to
277 See "The header" in Mail::Message
278
279 The body
280 $obj->body([BODY])
281 See "The body" in Mail::Message
282
283 $obj->contentType
284 See "The body" in Mail::Message
285
286 $obj->decoded(OPTIONS)
287 See "The body" in Mail::Message
288
289 $obj->encode(OPTIONS)
290 See "The body" in Mail::Message
291
292 $obj->isMultipart
293 See "The body" in Mail::Message
294
295 $obj->isNested
296 See "The body" in Mail::Message
297
298 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
299 See "The body" in Mail::Message
300
301 Flags
302 $obj->delete
303 See "Flags" in Mail::Message
304
305 $obj->deleted([BOOLEAN])
306 See "Flags" in Mail::Message
307
308 $obj->isDeleted
309 See "Flags" in Mail::Message
310
311 $obj->isModified
312 See "Flags" in Mail::Message
313
314 $obj->label(LABEL|PAIRS)
315 See "Flags" in Mail::Message
316
317 $obj->labels
318 See "Flags" in Mail::Message
319
320 $obj->labelsToStatus
321 See "Flags" in Mail::Message
322
323 $obj->modified([BOOLEAN])
324 See "Flags" in Mail::Message
325
326 $obj->statusToLabels
327 See "Flags" in Mail::Message
328
329 The whole message as text
330 $obj->file
331 See "The whole message as text" in Mail::Message::Construct::Text
332
333 $obj->lines
334 See "The whole message as text" in Mail::Message::Construct::Text
335
336 $obj->printStructure([FILEHANDLE|undef],[INDENT])
337 See "The whole message as text" in Mail::Message::Construct::Text
338
339 $obj->string
340 See "The whole message as text" in Mail::Message::Construct::Text
341
342 Internals
343 $obj->clonedFrom
344 See "Internals" in Mail::Message
345
346 Mail::Box::Message->coerce(MESSAGE, OPTIONS)
347 See "Internals" in Mail::Message
348
349 $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
354 $obj->isDelayed
355 See "Internals" in Mail::Message
356
357 $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
364 By default, the BODYTYPE will call Mail::Box::determineBodyType()
365 where the message will be added to.
366
367 $obj->readFromParser(PARSER, [BODYTYPE])
368 See "Internals" in Mail::Message
369
370 $obj->readHead(PARSER [,CLASS])
371 See "Internals" in Mail::Message
372
373 $obj->recursiveRebuildPart(PART, OPTIONS)
374 See "Internals" in Mail::Message::Construct::Rebuild
375
376 $obj->storeBody(BODY)
377 See "Internals" in Mail::Message
378
379 $obj->takeMessageId([STRING])
380 See "Internals" in Mail::Message
381
382 Error handling
383 $obj->AUTOLOAD
384 See "METHODS" in Mail::Message::Construct
385
386 $obj->addReport(OBJECT)
387 See "Error handling" in Mail::Reporter
388
389 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
390 Mail::Box::Message->defaultTrace([LEVEL]|[LOGLEVEL,
391 TRACELEVEL]|[LEVEL, CALLBACK])
392
393 See "Error handling" in Mail::Reporter
394
395 $obj->errors
396 See "Error handling" in Mail::Reporter
397
398 $obj->log([LEVEL [,STRINGS]])
399 Mail::Box::Message->log([LEVEL [,STRINGS]])
400
401 See "Error handling" in Mail::Reporter
402
403 $obj->logPriority(LEVEL)
404 Mail::Box::Message->logPriority(LEVEL)
405
406 See "Error handling" in Mail::Reporter
407
408 $obj->logSettings
409 See "Error handling" in Mail::Reporter
410
411 $obj->notImplemented
412 See "Error handling" in Mail::Reporter
413
414 $obj->report([LEVEL])
415 See "Error handling" in Mail::Reporter
416
417 $obj->reportAll([LEVEL])
418 See "Error handling" in Mail::Reporter
419
420 $obj->shortSize([VALUE])
421 Mail::Box::Message->shortSize([VALUE])
422
423 See "Error handling" in Mail::Message
424
425 $obj->shortString
426 See "Error handling" in Mail::Message
427
428 $obj->trace([LEVEL])
429 See "Error handling" in Mail::Reporter
430
431 $obj->warnings
432 See "Error handling" in Mail::Reporter
433
434 Cleanup
435 $obj->DESTROY
436 See "Cleanup" in Mail::Message
437
438 $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
445 $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
454 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
458 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
465 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
471 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
476 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
485 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
492 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
502 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
505
506
507
508perl v5.12.3 2011-01-26 Mail::Box::Message(3)