1Mail::Box::Maildir::MesUssaegre(C3o)ntributed Perl DocumMeanitla:t:iBoonx::Maildir::Message(3)
2
6 Mail::Box::Maildir::Message - one message in a Maildir folder
7
9 Mail::Box::Maildir::Message
10 is a Mail::Box::Dir::Message
11 is a Mail::Box::Message
12 is a Mail::Message
13 is a Mail::Reporter
14
16 my $folder = new Mail::Box::Maildir ...
17 my $message = $folder->message(10);
18
20 A "Mail::Box::Maildir::Message" represents one message in an
21 Mail::Box::Maildir folder. Each message is stored in a separate file.
22
24 Constructors
25 $obj->clone(OPTIONS)
26 See "Constructors" in Mail::Message
27 Mail::Box::Maildir::Message->new(OPTIONS)
29 See "METHODS" in Mail::Box::Dir::Message
30 Constructing a message
32 $obj->bounce([RG-OBJECT|OPTIONS])
33 See "Constructing a message" in Mail::Message::Construct::Bounce
34 Mail::Box::Maildir::Message->build([MESSAGE|PART|BODY], CONTENT)
36 See "Constructing a message" in Mail::Message::Construct::Build
37 Mail::Box::Maildir::Message->buildFromBody(BODY, [HEAD], HEADERS)
39 See "Constructing a message" in Mail::Message::Construct::Build
40 $obj->forward(OPTIONS)
42 See "Constructing a message" in Mail::Message::Construct::Forward
43 $obj->forwardAttach(OPTIONS)
45 See "Constructing a message" in Mail::Message::Construct::Forward
46 $obj->forwardEncapsulate(OPTIONS)
48 See "Constructing a message" in Mail::Message::Construct::Forward
49 $obj->forwardInline(OPTIONS)
51 See "Constructing a message" in Mail::Message::Construct::Forward
52 $obj->forwardNo(OPTIONS)
54 See "Constructing a message" in Mail::Message::Construct::Forward
55 $obj->forwardPostlude
57 See "Constructing a message" in Mail::Message::Construct::Forward
58 $obj->forwardPrelude
60 See "Constructing a message" in Mail::Message::Construct::Forward
61 $obj->forwardSubject(STRING)
63 See "Constructing a message" in Mail::Message::Construct::Forward
64 Mail::Box::Maildir::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
66 OPTIONS)
67 See "Constructing a message" in Mail::Message::Construct::Read
68 $obj->rebuild(OPTIONS)
70 See "Constructing a message" in Mail::Message::Construct::Rebuild
71 $obj->reply(OPTIONS)
73 See "Constructing a message" in Mail::Message::Construct::Reply
74 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
76 See "Constructing a message" in Mail::Message::Construct::Reply
77 $obj->replySubject(STRING)
79 Mail::Box::Maildir::Message->replySubject(STRING)
80 See "Constructing a message" in Mail::Message::Construct::Reply
82 The message
84 $obj->container
85 See "The message" in Mail::Message
86 $obj->copyTo(FOLDER, OPTIONS)
88 See "The message" in Mail::Box::Message
89 $obj->filename([FILENAME])
91 Returns the current filename for this message. If the FILENAME
92 argument is specified, a new filename will be set. For maildir
93 messages this means that modifications are immediately performed:
94 there will be a rename (move) from the old name to the new name.
95 Labels may change within in the message object as well.
96 $obj->folder([FOLDER])
98 See "The message" in Mail::Box::Message
99 $obj->isDummy
101 See "The message" in Mail::Message
102 $obj->isPart
104 See "The message" in Mail::Message
105 $obj->messageId
107 See "The message" in Mail::Message
108 $obj->moveTo(FOLDER, OPTIONS)
110 See "The message" in Mail::Box::Message
111 $obj->print([FILEHANDLE])
113 See "The message" in Mail::Message
114 $obj->send([MAILER], OPTIONS)
116 See "The message" in Mail::Message
117 $obj->seqnr([INTEGER])
119 See "The message" in Mail::Box::Message
120 $obj->size
122 See "The message" in Mail::Message
123 $obj->toplevel
125 See "The message" in Mail::Message
126 $obj->write([FILEHANDLE])
128 See "The message" in Mail::Message
129 The header
131 $obj->bcc
132 See "The header" in Mail::Message
133 $obj->cc
135 See "The header" in Mail::Message
136 $obj->date
138 See "The header" in Mail::Message
139 $obj->destinations
141 See "The header" in Mail::Message
142 $obj->from
144 See "The header" in Mail::Message
145 $obj->get(FIELDNAME)
147 See "The header" in Mail::Message
148 $obj->guessTimestamp
150 The filename of a "Mail::Box::Maildir::Message" contains a
151 timestamp. This is a wild guess about the actual time of sending
152 of the message: it is the time of receipt which may be seconds to
153 hours off. But is still a good guess... When the message header
154 is not parsed, then this date is used.
155 $obj->head([HEAD])
157 See "The header" in Mail::Message
158 $obj->nrLines
160 See "The header" in Mail::Message
161 $obj->sender
163 See "The header" in Mail::Message
164 $obj->study(FIELDNAME)
166 See "The header" in Mail::Message
167 $obj->subject
169 See "The header" in Mail::Message
170 $obj->timestamp
172 See "The header" in Mail::Message
173 $obj->to
175 See "The header" in Mail::Message
176 The body
178 $obj->body([BODY])
179 See "The body" in Mail::Message
180 $obj->contentType
182 See "The body" in Mail::Message
183 $obj->decoded(OPTIONS)
185 See "The body" in Mail::Message
186 $obj->encode(OPTIONS)
188 See "The body" in Mail::Message
189 $obj->isMultipart
191 See "The body" in Mail::Message
192 $obj->isNested
194 See "The body" in Mail::Message
195 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
197 See "The body" in Mail::Message
198 Flags
200 $obj->delete
201 See "Flags" in Mail::Message
202 $obj->deleted([BOOLEAN])
204 See "Flags" in Mail::Message
205 $obj->isDeleted
207 See "Flags" in Mail::Message
208 $obj->isModified
210 See "Flags" in Mail::Message
211 $obj->label(LABEL|PAIRS)
213 See "Flags" in Mail::Message
214 $obj->labels
216 See "Flags" in Mail::Message
217 $obj->labelsToStatus
219 See "Flags" in Mail::Message
220 $obj->modified([BOOLEAN])
222 See "Flags" in Mail::Message
223 $obj->statusToLabels
225 See "Flags" in Mail::Message
226 The whole message as text
228 $obj->file
229 See "The whole message as text" in Mail::Message::Construct::Text
230 $obj->lines
232 See "The whole message as text" in Mail::Message::Construct::Text
233 $obj->printStructure([FILEHANDLE|undef],[INDENT])
235 See "The whole message as text" in Mail::Message::Construct::Text
236 $obj->string
238 See "The whole message as text" in Mail::Message::Construct::Text
239 Labels
241 $obj->labelsToFilename
242 When the labels on a message change, this may implicate a change in
243 the message's filename. The change will take place immediately.
244 The new filename (which may be the same as the old filename) is
245 returned. "undef" is returned when the rename is required but
246 fails.
247 Internals
249 $obj->accept([BOOLEAN])
250 Accept a message for the folder. This will move it from the "new"
251 or "tmp" sub-directories into the "cur" sub-directory (or back when
252 the BOOLEAN is "false"). When you accept an already accepted
253 message, nothing will happen.
254 $obj->clonedFrom
256 See "Internals" in Mail::Message
257 Mail::Box::Maildir::Message->coerce(MESSAGE, OPTIONS)
259 See "Internals" in Mail::Message
260 $obj->create(FILENAME)
262 See "Internals" in Mail::Box::Dir::Message
263 $obj->diskDelete
265 See "Internals" in Mail::Box::Message
266 $obj->isDelayed
268 See "Internals" in Mail::Message
269 $obj->loadBody
271 See "Internals" in Mail::Box::Dir::Message
272 $obj->loadHead
274 See "Internals" in Mail::Box::Dir::Message
275 $obj->parser
277 See "Internals" in Mail::Box::Dir::Message
278 $obj->readBody(PARSER, HEAD [, BODYTYPE])
280 See "Internals" in Mail::Box::Message
281 $obj->readFromParser(PARSER, [BODYTYPE])
283 See "Internals" in Mail::Message
284 $obj->readHead(PARSER [,CLASS])
286 See "Internals" in Mail::Message
287 $obj->recursiveRebuildPart(PART, OPTIONS)
289 See "Internals" in Mail::Message::Construct::Rebuild
290 $obj->storeBody(BODY)
292 See "Internals" in Mail::Message
293 $obj->takeMessageId([STRING])
295 See "Internals" in Mail::Message
296 Error handling
298 $obj->AUTOLOAD
299 See "METHODS" in Mail::Message::Construct
300 $obj->addReport(OBJECT)
302 See "Error handling" in Mail::Reporter
303 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
305 Mail::Box::Maildir::Message->defaultTrace([LEVEL]|[LOGLEVEL,
306 TRACELEVEL]|[LEVEL, CALLBACK])
307 See "Error handling" in Mail::Reporter
309 $obj->errors
311 See "Error handling" in Mail::Reporter
312 $obj->log([LEVEL [,STRINGS]])
314 Mail::Box::Maildir::Message->log([LEVEL [,STRINGS]])
315 See "Error handling" in Mail::Reporter
317 $obj->logPriority(LEVEL)
319 Mail::Box::Maildir::Message->logPriority(LEVEL)
320 See "Error handling" in Mail::Reporter
322 $obj->logSettings
324 See "Error handling" in Mail::Reporter
325 $obj->notImplemented
327 See "Error handling" in Mail::Reporter
328 $obj->report([LEVEL])
330 See "Error handling" in Mail::Reporter
331 $obj->reportAll([LEVEL])
333 See "Error handling" in Mail::Reporter
334 $obj->shortSize([VALUE])
336 Mail::Box::Maildir::Message->shortSize([VALUE])
337 See "Error handling" in Mail::Message
339 $obj->shortString
341 See "Error handling" in Mail::Message
342 $obj->trace([LEVEL])
344 See "Error handling" in Mail::Reporter
345 $obj->warnings
347 See "Error handling" in Mail::Reporter
348 Cleanup
350 $obj->DESTROY
351 See "Cleanup" in Mail::Message
352 $obj->destruct
354 See "Cleanup" in Mail::Box::Message
355 $obj->inGlobalDestruction
357 See "Cleanup" in Mail::Reporter
358
360 Structure of a Message
361 The header
362 The body
364 Message object implementation
366 Message class implementation
367 Labels
368 Predefined labels
369 Status and X-Status fields
371 Flags in filename
373 When new messages arrive on system and have to be stored in a maildir
375 folder, they are put in the "new" sub-directory of the folder (first
376 created in the "tmp" sub-directory and then immediately moved to
377 "new"). The following information was found at
378 <http://cr.yp.to/proto/maildir.html>.
379 Each message is written in a separate file. The filename is
381 constructed from the time-of-arrival, a hostname, an unique component,
382 a syntax marker, and flags. For example "1014220791.meteor.42:2,DF".
383 The filename must match:
384 my ($time, $unique, $hostname, $info)
386 = $filename =~ m!^(\d+)\.(.*)\.(\w+)(\:.*)?$!;
387 my ($semantics, $flags)
388 = $info =~ m!([12])\,([DFPRST]*)$!;
389 my @flags = split //, $flags;
390 When an application opens the folder, there may be messages in "new"
392 which are new arival, and messages in "cur". The latter are labeled
393 "accepted". To move a message from "new" to "cur", you have two
394 options with the same effect:
395 $msg->accept;
397 $msg->label(accept => 1);
398 See accept(), label(), Mail::Box::Maildir::new(accept_new), and
400 Mail::Box::Maildir::acceptMessages()
401 The messages are moved, and their name is immediately extended with
403 flags. An example:
404 new/897979431.meteor.42 may become
406 cur/897979431.meteor.42:2,FS
407 The added characters ':2,' refer to the "second state of processing",
409 where the message has been inspected. And the characters (which should
410 be in alphabetic order) mean
411 D => draft
413 F => flagged
414 R => replied (answered)
415 S => seen
416 T => deleted (tagged for deletion)
417 Some maildir clients support
419 P => passed (resent/forwarded/bounced to someone else)
420 The flags will immediately change when label() or delete() is used,
422 which differs from other message implementations: maildir is stateless,
423 and should not break when applications crash.
424
426 Error: Cannot coerce a $class object into a $class object
427 Error: Cannot create parser for $filename.
428 For some reason (the previous message have told you already) it was
429 not possible to create a message parser for the specified filename.
430 Error: Cannot include forward source as $include.
432 Unknown alternative for the forward(include). Valid choices are
433 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
434 Error: Cannot include reply source as $include.
436 Unknown alternative for the "include" option of reply(). Valid
437 choices are "NO", "INLINE", and "ATTACH".
438 Error: Cannot write message to $filename: $!
440 When a modified or new message is written to disk, it is first
441 written to a temporary file in the folder directory. For some
442 reason, it is impossible to create this file.
443 Error: Failed to move $new to $filename: $!
445 When a modified or new message is written to disk, it is first
446 written to a temporary file in the folder directory. Then, the new
447 file is moved to replace the existing file. Apparently, the latter
448 fails.
449 Error: Method bounce requires To, Cc, or Bcc
451 The message bounce() method forwards a received message off to
452 someone else without modification; you must specified it's new
453 destination. If you have the urge not to specify any destination,
454 you probably are looking for reply(). When you wish to modify the
455 content, use forward().
456 Error: Method forwardAttach requires a preamble
458 Error: Method forwardEncapsulate requires a preamble
459 Error: No address to create forwarded to.
460 If a forward message is created, a destination address must be
461 specified.
462 Error: No default mailer found to send message.
464 The message send() mechanism had not enough information to
465 automatically find a mail transfer agent to sent this message.
466 Specify a mailer explicitly using the "via" options.
467 Error: No rebuild rule $name defined.
469 Error: Only build() Mail::Message's; they are not in a folder yet
470 You may wish to construct a message to be stored in a some kind of
471 folder, but you need to do that in two steps. First, create a
472 normal Mail::Message, and then add it to the folder. During this
473 Mail::Box::addMessage() process, the message will get coerce()-d
474 into the right message type, adding storage information and the
475 like.
476 Error: Package $package does not implement $method.
478 Fatal error: the specific package (or one of its superclasses) does
479 not implement this method where it should. This message means that
480 some other related classes do implement this method however the
481 class at hand does not. Probably you should investigate this and
482 probably inform the author of the package.
483 Error: Unable to read delayed body.
485 For some reason, the header of the message could be read, but the
486 body cannot. Probably the file has disappeared or the permissions
487 were changed during the progress of the program.
488 Error: Unable to read delayed head.
490 Mail::Box tries to be lazy with respect to parsing messages. When
491 a directory organized folder is opened, only the filenames of
492 messages are collected. At first use, the messages are read from
493 their file. Apperently, a message is used for the first time here,
494 but has disappeared or is unreadible for some other reason.
495 Error: coercion starts with some object
497
499 This module is part of Mail-Box distribution version 2.097, built on
500 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
501
503 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
504 ChangeLog.
505 This program is free software; you can redistribute it and/or modify it
507 under the same terms as Perl itself. See
508 http://www.perl.com/perl/misc/Artistic.html
509perl v5.12.3 2011-01-26 Mail::Box::Maildir::Message(3)