1Mail::Box::Maildir(3) User Contributed Perl DocumentationMail::Box::Maildir(3)
2
6 Mail::Box::Maildir - handle Maildir folders
7
9 Mail::Box::Maildir
10 is a Mail::Box::Dir
11 is a Mail::Box
12 is a Mail::Reporter
13
15 use Mail::Box::Maildir;
16 my $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;
17
19 This documentation describes how Maildir mailboxes work, and what you
20 can do with the Maildir folder object "Mail::Box::Maildir".
21 Maildir is not supported for Windows, because it create filenames which
23 are not accepted by the Windows system.
24 Extends "DESCRIPTION" in Mail::Box::Dir.
26
28 Extends "OVERLOADED" in Mail::Box::Dir.
29 overload: ""
31 Inherited, see "OVERLOADED" in Mail::Box
32 overload: @{}
34 Inherited, see "OVERLOADED" in Mail::Box
35 overload: cmp
37 Inherited, see "OVERLOADED" in Mail::Box
38
40 Extends "METHODS" in Mail::Box::Dir.
41 Constructors
43 Extends "Constructors" in Mail::Box::Dir.
44 Mail::Box::Maildir->new(%options)
46 -Option --Defined in --Default
47 accept_new <false>
48 access Mail::Box 'r'
49 body_delayed_type Mail::Box Mail::Message::Body::Delayed
50 body_type Mail::Box Mail::Message::Body::Lines
51 coerce_options Mail::Box []
52 create Mail::Box <false>
53 directory Mail::Box::Dir <derived from folder name>
54 extract Mail::Box 10240
55 field_type Mail::Box undef
56 fix_headers Mail::Box <false>
57 folder Mail::Box $ENV{MAIL}
58 folderdir Mail::Box $ENV{HOME}/.maildir
59 head_delayed_type Mail::Box Mail::Message::Head::Delayed
60 head_type Mail::Box Mail::Message::Head::Complete
61 keep_dups Mail::Box <false>
62 lock_file Mail::Box <not used>
63 lock_timeout Mail::Box <not used>
64 lock_type Mail::Box 'NONE' (constant)
65 lock_wait Mail::Box <not used>
66 locker Mail::Box undef
67 log Mail::Reporter 'WARNINGS'
68 manager Mail::Box undef
69 message_type Mail::Box <folder-class>::Message
70 multipart_type Mail::Box Mail::Message::Body::Multipart
71 remove_when_empty Mail::Box <true>
72 save_on_exit Mail::Box <true>
73 trace Mail::Reporter 'WARNINGS'
74 trusted Mail::Box <depends on folder location>
75 accept_new => BOOLEAN
77 When the folder is open, some messages may be stored in the "new"
78 sub-directory. By default, these messages are immediately moved
79 to the "cur" directory when the folder is opened. Otherwise, you
80 have to call acceptMessages() or
81 Mail::Box::Maildir::Message::accept().
82 access => MODE
84 body_delayed_type => CLASS
85 body_type => CLASS|CODE
86 coerce_options => ARRAY
87 create => BOOLEAN
88 directory => DIRECTORY
89 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
90 field_type => CLASS
91 fix_headers => BOOLEAN
92 folder => FOLDERNAME
93 folderdir => DIRECTORY
94 head_delayed_type => CLASS
95 head_type => CLASS
96 keep_dups => BOOLEAN
97 lock_file => FILENAME
98 lock_timeout => SECONDS
99 lock_type => CLASS|STRING|ARRAY
100 lock_wait => SECONDS
101 locker => OBJECT
102 log => LEVEL
103 manager => MANAGER
104 message_type => CLASS
105 multipart_type => CLASS
106 remove_when_empty => BOOLEAN
107 save_on_exit => BOOLEAN
108 trace => LEVEL
109 trusted => BOOLEAN
110 The folder
112 Extends "The folder" in Mail::Box::Dir.
113 $obj->addMessage($message, %options)
115 Inherited, see "The folder" in Mail::Box
116 $obj->addMessages(@messages)
118 Inherited, see "The folder" in Mail::Box
119 Mail::Box::Maildir->appendMessages(%options)
121 Inherited, see "The folder" in Mail::Box
122 $obj->close(%options)
124 Inherited, see "The folder" in Mail::Box
125 $obj->copyTo($folder, %options)
127 Inherited, see "The folder" in Mail::Box
128 $obj->delete(%options)
130 Inherited, see "The folder" in Mail::Box
131 $obj->directory()
133 Inherited, see "The folder" in Mail::Box::Dir
134 $obj->folderdir( [$directory] )
136 Inherited, see "The folder" in Mail::Box
137 $obj->name()
139 Inherited, see "The folder" in Mail::Box
140 $obj->organization()
142 Inherited, see "The folder" in Mail::Box
143 $obj->size()
145 Inherited, see "The folder" in Mail::Box
146 $obj->type()
148 Inherited, see "The folder" in Mail::Box
149 $obj->update(%options)
151 Inherited, see "The folder" in Mail::Box
152 $obj->url()
154 Inherited, see "The folder" in Mail::Box
155 Folder flags
157 Extends "Folder flags" in Mail::Box::Dir.
158 $obj->access()
160 Inherited, see "Folder flags" in Mail::Box
161 $obj->isModified()
163 Inherited, see "Folder flags" in Mail::Box
164 $obj->modified( [BOOLEAN] )
166 Inherited, see "Folder flags" in Mail::Box
167 $obj->writable()
169 Inherited, see "Folder flags" in Mail::Box
170 The messages
172 Extends "The messages" in Mail::Box::Dir.
173 $obj->current( [$number|$message|$message_id] )
175 Inherited, see "The messages" in Mail::Box
176 $obj->find($message_id)
178 Inherited, see "The messages" in Mail::Box
179 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
181 Inherited, see "The messages" in Mail::Box
182 $obj->message( $index, [$message] )
184 Inherited, see "The messages" in Mail::Box
185 $obj->messageId( $message_id, [$message] )
187 Inherited, see "The messages" in Mail::Box
188 $obj->messageIds()
190 Inherited, see "The messages" in Mail::Box
191 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
193 !$label|$filter> )
194 Inherited, see "The messages" in Mail::Box
195 $obj->nrMessages(%options)
197 Inherited, see "The messages" in Mail::Box
198 $obj->scanForMessages($message, $message_ids, $timespan, $window)
200 Inherited, see "The messages" in Mail::Box
201 Sub-folders
203 Extends "Sub-folders" in Mail::Box::Dir.
204 $obj->listSubFolders(%options)
206 Mail::Box::Maildir->listSubFolders(%options)
207 Inherited, see "Sub-folders" in Mail::Box
208 $obj->nameOfSubFolder( $subname, [$parentname] )
210 Mail::Box::Maildir->nameOfSubFolder( $subname, [$parentname] )
211 Inherited, see "Sub-folders" in Mail::Box
212 $obj->openRelatedFolder(%options)
214 Inherited, see "Sub-folders" in Mail::Box
215 $obj->openSubFolder($subname, %options)
217 Inherited, see "Sub-folders" in Mail::Box
218 $obj->topFolderWithMessages()
220 Mail::Box::Maildir->topFolderWithMessages()
221 Inherited, see "Sub-folders" in Mail::Box
222 Internals
224 Extends "Internals" in Mail::Box::Dir.
225 $obj->acceptMessages()
227 Accept all messages which are waiting in the "new" directory to be
228 moved to the "cur" directory. This will not rescan the directory
229 for newly arrived messages, because that's a task for update().
230 Mail::Box::Maildir->appendMessage(%options)
232 $obj->coerce($message, %options)
233 $obj->create($foldername, %options)
234 Mail::Box::Maildir->create($foldername, %options)
235 -Option --Defined in--Default
236 folderdir Mail::Box undef
237 folderdir => DIRECTORY
239 $obj->createDirs($folderdir)
240 Mail::Box::Maildir->createDirs($folderdir)
241 The $folderdir contains the absolute path of the location where the
242 messages are kept. Maildir folders contain a "tmp", "new", and
243 "cur" sub-directory within that folder directory as well. This
244 method will ensure that all directories exist. Returns false on
245 failure.
246 $obj->determineBodyType($message, $head)
248 Inherited, see "Internals" in Mail::Box
249 $obj->folderIsEmpty($folderdir)
251 Mail::Box::Maildir->folderIsEmpty($folderdir)
252 Checks whether the folder whose directory is specified as absolute
253 $folderdir is empty or not. A folder is empty when the "tmp",
254 "new", and "cur" subdirectories are empty and some files which are
255 left there by application programs. The maildir spec explicitly
256 states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
257 If any other files are found, the directory is considered not-
258 empty.
259 $obj->folderToDirectory($foldername, $folderdir)
261 Inherited, see "Internals" in Mail::Box::Dir
262 Mail::Box::Maildir->foundIn( [$foldername], %options )
264 Inherited, see "Internals" in Mail::Box
265 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
267 Inherited, see "Internals" in Mail::Box
268 $obj->locker()
270 Inherited, see "Internals" in Mail::Box
271 $obj->messageInFile($filename)
273 Inherited, see "Internals" in Mail::Box::Dir
274 $obj->read(%options)
276 Inherited, see "Internals" in Mail::Box
277 $obj->readMessageFilenames($directory)
279 Inherited, see "Internals" in Mail::Box::Dir
280 $obj->readMessages(%options)
282 Inherited, see "Internals" in Mail::Box
283 $obj->storeMessage($message)
285 Inherited, see "Internals" in Mail::Box
286 $obj->toBeThreaded($messages)
288 Inherited, see "Internals" in Mail::Box
289 $obj->toBeUnthreaded($messages)
291 Inherited, see "Internals" in Mail::Box
292 $obj->updateMessages(%options)
294 Inherited, see "Internals" in Mail::Box
295 $obj->write(%options)
297 Inherited, see "Internals" in Mail::Box
298 $obj->writeMessages(%options)
300 Inherited, see "Internals" in Mail::Box
301 Other methods
303 Extends "Other methods" in Mail::Box::Dir.
304 $obj->timespan2seconds($time)
306 Mail::Box::Maildir->timespan2seconds($time)
307 Inherited, see "Other methods" in Mail::Box
308 Error handling
310 Extends "Error handling" in Mail::Box::Dir.
311 $obj->AUTOLOAD()
313 Inherited, see "Error handling" in Mail::Reporter
314 $obj->addReport($object)
316 Inherited, see "Error handling" in Mail::Reporter
317 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
319 $callback] )
320 Mail::Box::Maildir->defaultTrace( [$level]|[$loglevel,
321 $tracelevel]|[$level, $callback] )
322 Inherited, see "Error handling" in Mail::Reporter
323 $obj->errors()
325 Inherited, see "Error handling" in Mail::Reporter
326 $obj->log( [$level, [$strings]] )
328 Mail::Box::Maildir->log( [$level, [$strings]] )
329 Inherited, see "Error handling" in Mail::Reporter
330 $obj->logPriority($level)
332 Mail::Box::Maildir->logPriority($level)
333 Inherited, see "Error handling" in Mail::Reporter
334 $obj->logSettings()
336 Inherited, see "Error handling" in Mail::Reporter
337 $obj->notImplemented()
339 Inherited, see "Error handling" in Mail::Reporter
340 $obj->report( [$level] )
342 Inherited, see "Error handling" in Mail::Reporter
343 $obj->reportAll( [$level] )
345 Inherited, see "Error handling" in Mail::Reporter
346 $obj->trace( [$level] )
348 Inherited, see "Error handling" in Mail::Reporter
349 $obj->warnings()
351 Inherited, see "Error handling" in Mail::Reporter
352 Cleanup
354 Extends "Cleanup" in Mail::Box::Dir.
355 $obj->DESTROY()
357 Inherited, see "Cleanup" in Mail::Box
358
360 The explanation is complicated, but for normal use you should bother
361 yourself with all details.
362 Extends "DETAILS" in Mail::Box::Dir.
364 Different kinds of folders
366 Extends "Different kinds of folders" in Mail::Box::Dir.
367 Available folder types
369 Extends "Available folder types" in Mail::Box::Dir.
370 Folder class implementation
372 Extends "Folder class implementation" in Mail::Box::Dir.
373 How MAILDIR folders work
375 Maildir-type folders use a directory to store the messages of one
376 folder. Each message is stored in a separate file. This seems useful,
377 because changes in a folder change only a few of these small files, in
378 contrast with file-based folders where changes in a folder cause
379 rewrites of huge folder-files.
380 However, Maildir based folders perform very bad if you need header
382 information of all messages. For instance, if you want to have full
383 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
384 the folder, it requires to read all header lines in all message files.
385 And usually, reading your messages as threads is desired. Maildir
386 maintains a tiny amount of info visible in the filename, which may make
387 it perform just a little bit faster than MH.
388
390 Error: Cannot append Maildir message in $new to folder $self.
391 The message (or messages) could not be stored in the right
392 directories for the Maildir folder.
393 Error: Cannot create Maildir directory $dir: $!
395 A Maildir folder is represented by a directory, with some sub-
396 directories. The top folder directory could not be created for the
397 reason indicated.
398 Error: Cannot create Maildir folder $name.
400 One or more of the directories required to administer a Maildir
401 folder could not be created.
402 Error: Cannot create Maildir message file $new.
404 A message is converted from some other message format into a
405 Maildir format by writing it to a file with a name which contains
406 the status flags of the message. Apparently, creating this file
407 failed.
408 Error: Cannot create Maildir subdir $dir: $!
410 Each Maildir folder has three sub-directories for administration:
411 "new", "tmp", and "cur". The mentioned directory could not be
412 created for the indicated reason.
413 Warning: Changes not written to read-only folder $self.
415 You have opened the folder read-only --which is the default set by
416 new(access)--, made modifications, and now want to close it. Set
417 close(force) if you want to overrule the access mode, or close the
418 folder with close(write) set to "NEVER".
419 Error: Copying failed for one message.
421 For some reason, for instance disc full, removed by external
422 process, or read-protection, it is impossible to copy one of the
423 messages. Copying will proceed for the other messages.
424 Error: Destination folder $name is not writable.
426 The folder where the messages are copied to is not opened with
427 write access (see new(access)). This has no relation with write
428 permission to the folder which is controlled by your operating
429 system.
430 Warning: Different messages with id $msgid
432 The message id is discovered more than once within the same folder,
433 but the content of the message seems to be different. This should
434 not be possible: each message must be unique.
435 Error: Folder $name is opened read-only
437 You can not write to this folder unless you have opened the folder
438 to write or append with new(access), or the "force" option is set
439 true.
440 Error: Folder $name not deleted: not writable.
442 The folder must be opened with write access via new(access),
443 otherwise removing it will be refused. So, you may have write-
444 access according to the operating system, but that will not
445 automatically mean that this "delete" method permits you to. The
446 reverse remark is valid as well.
447 Error: Invalid timespan '$timespan' specified.
449 The string does not follow the strict rules of the time span syntax
450 which is permitted as parameter.
451 Warning: Message-id '$msgid' does not contain a domain.
453 According to the RFCs, message-ids need to contain a unique random
454 part, then an "@", and then a domain name. This is made to avoid
455 the creation of two messages with the same id. The warning emerges
456 when the "@" is missing from the string.
457 Error: Package $package does not implement $method.
459 Fatal error: the specific package (or one of its superclasses) does
460 not implement this method where it should. This message means that
461 some other related classes do implement this method however the
462 class at hand does not. Probably you should investigate this and
463 probably inform the author of the package.
464 Error: Unable to create subfolder $name of $folder.
466 The copy includes the subfolders, but for some reason it was not
467 possible to copy one of these. Copying will proceed for all other
468 sub-folders.
469 Error: Writing folder $name failed
471 For some reason (you probably got more error messages about this
472 problem) it is impossible to write the folder, although you should
473 because there were changes made.
474
476 This module is part of Mail-Box distribution version 3.009, built on
477 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
478
480 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
481 ChangeLog.
482 This program is free software; you can redistribute it and/or modify it
484 under the same terms as Perl itself. See http://dev.perl.org/licenses/
485perl v5.36.0 2023-01-20 Mail::Box::Maildir(3)