1Mail::Box(3) User Contributed Perl Documentation Mail::Box(3)
2
6 Mail::Box - manage a mailbox, a folder with messages
7
9 Mail::Box
10 is a Mail::Reporter
11 Mail::Box is extended by
13 Mail::Box::Dir
14 Mail::Box::File
15 Mail::Box::Net
16
18 use Mail::Box::Manager;
19 my $mgr = Mail::Box::Manager->new;
20 my $folder = $mgr->open(folder => $ENV{MAIL}, ...);
21 print $folder->name;
22 # Get the first message.
24 print $folder->message(0);
25 # Delete the third message
27 $folder->message(3)->delete;
28 # Get the number of messages in scalar context.
30 my $emails = $folder->messages;
31 # Iterate over the messages.
33 foreach ($folder->messages) {...} # all messages
34 foreach (@$folder) {...} # all messages
35 $folder->addMessage(Mail::Box::Message->new(...));
37 Tied-interface:
39 tie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox;
41 # Four times the same:
43 $inbox[3]->print; # tied
44 $folder->[3]->print; # overloaded folder
45 $folder->message(3)->print; # usual
46 print $folder->[3]; # overloaded message
47 tie my(%inbox), 'Mail::Box::Tie::HASH', $inbox;
49 # Twice times the same
51 $inbox{$msgid}->print; # tied
52 $folder->messageId($msgid)->print;# usual
53
55 A Mail::Box::Manager creates "Mail::Box" objects. But you already
56 knew, because you started with the Mail::Box-Overview manual page.
57 That page is obligatory reading, sorry!
58 "Mail::Box" is the base class for accessing various types of mailboxes
60 (folders) in a uniform manner. The various folder types vary on how
61 they store their messages, but when some effort those differences could
62 be hidden behind a general API. For example, some folders store many
63 messages in one single file, where other store each message in a
64 separate file withing the same directory.
65 No object in your program will be of type "Mail::Box": it is only used
67 as base class for the real folder types. "Mail::Box" is extended by
68
70 overload: ""
71 (stringification) The folder objects stringify to their name. This
72 simplifies especially print statements and sorting a lot.
73 example: use overloaded folder as string
75 # Three lines with overloading: resp. cmp, @{}, and ""
77 foreach my $folder (sort @folders)
78 { my $msgcount = @$folder;
79 print "$folder contains $msgcount messages\n";
80 }
81 overload: @{}
83 When the folder is used as if it is a reference to an array, it
84 will show the messages, like messages() and message() would do.
85 example: use overloaded folder as array
87 my $msg = $folder->[3];
89 my $msg = $folder->message(3); # same
90 foreach my $msg (@$folder) ...
92 foreach my $msg ($folder->messages) ... # same
93 overload: cmp
95 (string comparison) folders are compared based on their name. The
96 sort rules are those of the build-in "cmp".
97
99 Constructors
100 Mail::Box->new(OPTIONS)
101 Open a new folder. A list of labeled OPTIONS for the mailbox can be
102 supplied. Some options pertain to Mail::Box, and others are added
103 by sub-classes.
104 To control delay-loading of messages, as well the headers as the
106 bodies, a set of *_type options are available. "extract" determines
107 whether we want delay-loading.
108 -Option --Defined in --Default
110 access 'r'
111 body_delayed_type Mail::Message::Body::Delayed
112 body_type <folder specific>
113 coerce_options []
114 create <false>
115 extract 10240
116 field_type undef
117 fix_headers <false>
118 folder $ENV{MAIL}
119 folderdir undef
120 head_delayed_type Mail::Message::Head::Delayed
121 head_type Mail::Message::Head::Complete
122 keep_dups <false>
123 lock_file undef
124 lock_timeout 1 hour
125 lock_type Mail::Box::Locker::DotLock
126 lock_wait 10 seconds
127 locker undef
128 log Mail::Reporter 'WARNINGS'
129 manager undef
130 message_type Mail::Box::Message
131 multipart_type Mail::Message::Body::Multipart
132 remove_when_empty <true>
133 save_on_exit <true>
134 trace Mail::Reporter 'WARNINGS'
135 trusted <depends on folder location>
136 access => MODE
138 Access-rights to the folder. Folders are opened for read-only
139 (which means write-protected) by default! MODE can be
140 'r': read-only (default)
142 'a': append
143 'rw': read-write
144 'd': delete
145 These MODE has no relation to the modes actually used to open the
147 folder files within this module. For instance, if you specify
148 "rw", and open the folder, only read permission on the folder-
149 file is required.
150 Be warned: writing a MBOX folder may create a new file to replace
152 the old folder. The permissions and owner of the file may get
153 changed by this.
154 body_delayed_type => CLASS
156 The bodies which are delayed: which will be read from file when
157 it is needed, but not before.
158 body_type => CLASS|CODE
160 When messages are read from a folder-file, the headers will be
161 stored in a "head_type" object. For the body, however, there is
162 a range of choices about type, which are all described in
163 Mail::Message::Body.
164 Specify a CODE-reference which produces the body-type to be
166 created, or a CLASS of the body which is used when the body is
167 not a multipart or nested. In case of a code reference, the
168 header structure is passed as first argument to the routine.
169 Do not return a delayed body-type (like "::Delayed"), because
171 that is determined by the "extract" option while the folder is
172 opened. Even delayed message will require some real body type
173 when they get parsed eventually. Multiparts and nested messages
174 are also outside your control.
175 For instance:
177 $mgr->open('InBox', body_type => \&which_body);
179 sub which_body($) {
181 my $head = shift;
182 my $size = $head->guessBodySize || 0;
183 my $type = $size > 100000 ? 'File' : 'Lines';
184 "Mail::Message::Body::$type";
185 }
186 The default depends on the mail-folder type, although the general
188 default is Mail::Message::Body::Lines. Please check the
189 applicable manual pages.
190 coerce_options => ARRAY
192 Keep configuration information for messages which are coerced
193 into the specified folder type, starting with a different folder
194 type (or even no folder at all). Messages which are coerced are
195 always fully read, so this kind of information does not need to
196 be kept here.
197 create => BOOLEAN
199 Automatically create the folder when it does not exist yet. This
200 will only work when access is granted for writing or appending to
201 the folder.
202 Be careful: you may create a different folder type than you
204 expect unless you explicitly specify
205 Mail::Box::Manager::open(type).
206 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
208 Defines when to parse (process) the content of the message. When
209 the header of a message is read, you may want to postpone the
210 reading of the body: header information is more often needed than
211 the body data, so why parse it always together? The cost of
212 delaying is not too high, and with some luck you may never need
213 parsing the body.
214 If you supply an INTEGER to this option, bodies of those messages
216 with a total size less than that number will be extracted from
217 the folder only when necessary. Messages where the size (in the
218 "Content-Length" field) is not included in the header, like often
219 the case for multiparts and nested messages, will not be
220 extracted by default.
221 If you supply a CODE reference, that subroutine is called every
223 time that the extraction mechanism wants to determine whether to
224 parse the body or not. The subroutine is called with the
225 following arguments:
226 CODE->(FOLDER, HEAD)
228 where FOLDER is a reference to the folder we are reading. HEAD
230 refers to the Mail::Message::Head::Complete head of the message
231 at hand. The routine must return a "true" value (extract now) or
232 a "false" value (be lazy, do not parse yet). Think about using
233 the Mail::Message::Head::guessBodySize() and
234 Mail::Message::guessTimestamp() on the header to determine your
235 choice.
236 The third possibility is to specify the NAME of a method. In
238 that case, for each message is called:
239 FOLDER->NAME(HEAD)
241 Where each component has the same meaning as described above.
243 The fourth way to use this option involves constants: with "LAZY"
245 all messages will be delayed. With "ALWAYS" you enforce
246 unconditional parsing, no delaying will take place. The latter
247 is usuful when you are sure you always need all the messages in
248 the folder.
249 $folder->new(extract => 'LAZY'); # Very lazy
251 $folder->new(extract => 10000); # Less than 10kB
252 # same, but implemented yourself
254 $folder->new(extract => &large);
255 sub large($) {
256 my ($f, $head) = @_;
257 my $size = $head->guessBodySize;
258 defined $size ? $size < 10000 : 1
259 };
260 # method call by name, useful for Mail::Box
262 # extensions. The example selects all messages
263 # sent by you to be loaded without delay.
264 # Other messages will be delayed.
265 $folder->new(extract => 'sent_by_me');
266 sub Mail::Box::send_by_me($) {
267 my ($self, $header) = @_;
268 $header->get('from') =~ m/\bmy\@example.com\b/i;
269 }
270 field_type => CLASS
272 The type of the fields to be used in a header. Must extend
273 Mail::Message::Field.
274 fix_headers => BOOLEAN
276 Broken MIME headers usually stop the parser: all lines not parsed
277 are added to the body of the message. With this flag set, the
278 erroneous line is added to the previous header field and parsing
279 is continued. See
280 Mail::Box::Parser::Perl::new(fix_header_errors).
281 folder => FOLDERNAME
283 Which folder to open (for reading or writing). When used for
284 reading (the "access" option set to "r" or "a") the mailbox
285 should already exist and must be readable. The file or directory
286 of the mailbox need not exist if it is opened for reading and
287 writing ("rw"). Write-permission is checked when opening an
288 existing mailbox.
289 The folder name can be preceded by a "=", to indicate that it is
291 named relative to the directory specified in new(folderdir).
292 Otherwise, it is taken as relative or absolute path.
293 folderdir => DIRECTORY
295 Where are folders to be found by default? A folder-name may be
296 preceded by a equals-sign ("=", a "mutt" convension) to
297 explicitly state that the folder is located below the default
298 directory. For example: in case "folderdir => '/tmp'" and
299 "folder => '=abc'", the name of the folder-file is '/tmp/abc'.
300 Each folder type has already some default set.
301 head_delayed_type => CLASS
303 The headers which are delayed: which will be read from file when
304 it is needed, but not before.
305 head_type => CLASS
307 The type of header which contains all header information. Must
308 extend Mail::Message::Head::Complete.
309 keep_dups => BOOLEAN
311 Indicates whether or not duplicate messages within the folder
312 should be retained. A message is considered to be a duplicate if
313 its message-id is the same as a previously parsed message within
314 the same folder. If this option is false (the default) such
315 messages are automatically deleted, because it is considered
316 useless to store the same message twice.
317 lock_file => FILENAME
319 The name of the file which is used to lock. This must be
320 specified when locking is to be used.
321 lock_timeout => SECONDS
323 When the lock file is older than the specified number of SECONDS,
324 it is considered a mistake. The original lock is released, and
325 accepted for this folder.
326 lock_type => CLASS|STRING|ARRAY
328 The type of the locker object. This may be the full name of a
329 CLASS which extends Mail::Box::Locker, or one of the known locker
330 types "DotLock", "Flock", "Mutt", "NFS", "POSIX", or "NONE". If
331 an ARRAY is specified, then a Multi locker is built which uses
332 the specified list.
333 lock_wait => SECONDS
335 SECONDS to wait before failing on opening this folder.
336 locker => OBJECT
338 An OBJECT which extends Mail::Box::Locker, and will handle folder
339 locking replacing the default lock behavior.
340 log => LEVEL
342 manager => MANAGER
343 A reference to the object which manages this folder -- typically
344 an Mail::Box::Manager instance.
345 message_type => CLASS
347 What kind of message objects are stored in this type of folder.
348 The default is Mail::Box::Message (which is a sub-class of
349 Mail::Message). The class you offer must be an extension of
350 Mail::Box::Message.
351 multipart_type => CLASS
353 The default type of objects which are to be created for multipart
354 message bodies.
355 remove_when_empty => BOOLEAN
357 Determines whether to remove the folder file or directory
358 automatically when the write would result in a folder without
359 messages nor sub-folders.
360 save_on_exit => BOOLEAN
362 Sets the policy for saving the folder when it is closed. A
363 folder can be closed manually (see close()) or in a number of
364 implicit ways, including on the moment the program is terminated.
365 trace => LEVEL
367 trusted => BOOLEAN
368 Flags whether to trust the data in the folder or not. Folders
369 which reside in your "folderdir" will be trusted by default (even
370 when the names if not specified staring with "="). Folders which
371 are outside the folderdir or read from STDIN
372 (Mail::Message::Construct::read()) are not trused by default, and
373 require some extra checking.
374 If you do not check encodings of received messages, you may print
376 binary data to the screen, which is a security risk.
377 The folder
379 $obj->addMessage(MESSAGE, OPTIONS)
380 Add a message to the folder. A message is usually a
381 Mail::Box::Message object or a sub-class thereof. The message
382 shall not be in an other folder, when you use this method. In case
383 it is, use Mail::Box::Manager::moveMessage() or
384 Mail::Box::Manager::copyMessage() via the manager.
385 Messages with id's which already exist in this folder are not
387 added.
388 BE WARNED that message labels may get lost when a message is moved
390 from one folder type to an other. An attempt is made to translate
391 labels, but there are many differences in interpretation by
392 applications.
393 -Option--Default
395 share <not used>
396 share => BOOLEAN
398 Try to share the physical resource of the current message with
399 the indicated message. It is sometimes possible to share
400 messages between different folder types. When the sharing is not
401 possible, than this option is simply ignored.
402 Sharing the resource is quite dangerous, and only available for a
404 limited number of folder types, at the moment only some
405 Mail::Box::Dir folders; these file-based messages can be
406 hardlinked (on platforms that support it). The link may get
407 broken when one message is modified in one of the folders.... but
408 maybe not, depending on the folder types involved.
409 example:
411 $folder->addMessage($msg);
413 $folder->addMessages($msg1, $msg2, ...);
414 $obj->addMessages(MESSAGE [, MESSAGE, ...])
416 Adds a set of MESSAGE objects to the open folder at once. For some
417 folder types this may be faster than adding them one at a time.
418 example:
420 $folder->addMessages($msg1, $msg2, ...);
422 Mail::Box->appendMessages(OPTIONS)
424 Append one or more messages to an unopened folder. Usually, this
425 method is called by the Mail::Box::Manager::appendMessage(), in
426 which case the correctness of the folder type is checked.
427 For some folder types it is required to open the folder before it
429 can be used for appending. This can be fast, but this can also be
430 very slow (depends on the implementation). All OPTIONS passed will
431 also be used to open the folder, if needed.
432 -Option --Default
434 folder <required>
435 message undef
436 messages undef
437 share <false>
438 folder => FOLDERNAME
440 The name of the folder to which the messages are to be appended.
441 The folder implementation will avoid opening the folder when
442 possible, because this is resource consuming.
443 message => MESSAGE
445 messages => ARRAY-OF-MESSAGES
446 One reference to a MESSAGE or a reference to an ARRAY of
447 MESSAGEs, which may be of any type. The messages will be first
448 coerced into the correct message type to fit in the folder, and
449 then will be added to it.
450 share => BOOLEAN
452 Try to share physical storage of the message. Only available for
453 a limited number of folder types, otherwise no-op.
454 example:
456 my $message = Mail::Message->new(...);
458 Mail::Box::Mbox->appendMessages
459 ( folder => '=xyz'
460 , message => $message
461 , folderdir => $ENV{FOLDERS}
462 );
463 better:
465 my Mail::Box::Manager $mgr;
467 $mgr->appendMessages($message, folder => '=xyz');
468 $obj->close(OPTIONS)
470 Close the folder, which usually implies writing the changes. This
471 will return "false" when writing is required but fails. Please do
472 check this result.
473 WARNING: When moving messages from one folder to another, be sure
475 to write the destination folder before writing and closing the
476 source folder. Otherwise you may lose data if the system crashes
477 or if there are software problems.
478 -Option --Default
480 force <false>
481 save_deleted false
482 write MODIFIED
483 force => BOOLEAN
485 Override the new(access) setting which was specified when the
486 folder was opened. This option only has an effect if its value is
487 TRUE. NOTE: Writing to the folder may not be permitted by the
488 operating system, in which case even "force" will not help.
489 save_deleted => BOOLEAN
491 Do also write messages which where flagged to be deleted to their
492 folder. The flag for deletion is conserved (when possible),
493 which means that a re-open of the folder may remove the messages
494 for real. See write(save_deleted).
495 write => 'ALWAYS'|'NEVER'|'MODIFIED'
497 Specifies whether the folder should be written. As could be
498 expected, "ALWAYS" means always (even if there are no changes),
499 "NEVER" means that changes to the folder will be lost, and
500 "MODIFIED" only saves the folder if there are any changes.
501 example:
503 my $f = $mgr->open('spam', access => 'rw')
505 or die "Cannot open spam: $!\n";
506 $f->message(0)->delete
508 if $f->messages;
509 $f->close
511 or die "Couldn't write $f: $!\n";
512 $obj->copyTo(FOLDER, OPTIONS)
514 Copy the folder's messages to a new folder. The new folder may be
515 of a different type.
516 -Option --Default
518 delete_copied <false>
519 select 'ACTIVE'
520 share <not used>
521 subfolders <folder type dependent>
522 delete_copied => BOOLEAN
524 Flag the messages from the source folder to be deleted, just
525 after it was copied. The deletion will only take effect when the
526 originating folder is closed.
527 select => 'ACTIVE'|'DELETED'|'ALL'|LABEL|!LABEL|FILTER
529 Which messages are to be copied. See the description of
530 messages() about how this works.
531 share => BOOLEAN
533 Try to share the message between the folders. Some
534 Mail::Box::Dir folder types do support it by creating a hardlink
535 (on UNIX/Linux).
536 subfolders => BOOLEAN|'FLATTEN'|'RECURSE'
538 How to handle sub-folders. When false (0 or "undef"), sub-
539 folders are simply ignored. With "FLATTEN", messages from sub-
540 folders are included in the main copy. "RECURSE" recursively
541 copies the sub-folders as well. By default, when the destination
542 folder supports sub-folders "RECURSE" is used, otherwise
543 "FLATTEN". A value of true will select the default.
544 example:
546 my $mgr = Mail::Box::Manager->new;
548 my $imap = $mgr->open(type => 'imap', host => ...);
549 my $mh = $mgr->open(type => 'mh', folder => '/tmp/mh',
550 create => 1, access => 'w');
551 $imap->copyTo($mh, delete_copied => 1);
553 $mh->close; $imap->close;
554 $obj->delete(OPTIONS)
556 Remove the specified folder file or folder directory (depending on
557 the type of folder) from disk. Of course, THIS IS DANGEROUS: you
558 "may" lose data. Returns a "true" value on success.
559 WARNING: When moving messages from one folder to another, be sure
561 to write the destination folder before deleting the source folder.
562 Otherwise you may lose data if the system crashes or if there are
563 software problems.
564 -Option --Default
566 recursive 1
567 recursive => BOOLEAN
569 example: removing an open folder
571 my $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw');
573 ... some other code ...
574 $folder->delete;
575 example: removing an closed folder
577 my $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd');
579 $folder->delete;
580 $obj->folderdir([DIRECTORY])
582 Get or set the DIRECTORY which is used to store mail-folders by
583 default.
584 example:
586 print $folder->folderdir;
588 $folder->folderdir("$ENV{HOME}/nsmail");
589 $obj->name
591 Returns the name of the folder. What the name represents depends
592 on the actual type of mailbox used.
593 example:
595 print $folder->name;
597 print "$folder"; # overloaded stringification
598 $obj->organization
600 Returns how the folder is organized: as one "FILE" with many
601 messages, a "DIRECTORY" with one message per file, or by a "REMOTE"
602 server.
603 $obj->size
605 Returns the size of the folder in bytes, not counting in the
606 deleted messages. The error in the presented result may be as
607 large as 10%, because the in-memory representation of messages is
608 not always the same as the size when they are written.
609 $obj->type
611 Returns a name for the type of mail box. This can be "mbox", "mh",
612 "maildir", or "pop3".
613 $obj->update(OPTIONS)
615 Read new messages from the folder, which where received after
616 opening it. This is quite dangerous and shouldn't be possible:
617 folders which are open are locked. However, some applications do
618 not use locks or the wrong kind of locks. This method reads the
619 changes (not always failsafe) and incorporates them in the open
620 folder administration.
621 The OPTIONS are extra values which are passed to the
623 updateMessages() method which is doing the actual work here.
624 $obj->url
626 Represent the folder as a URL (Universal Resource Locator) string.
627 You may pass such a URL as folder name to
628 Mail::Box::Manager::open().
629 example:
631 print $folder->url;
633 # may result in
634 # mbox:/var/mail/markov or
635 # pop3://user:password@pop.aol.com:101
636 Folder flags
638 $obj->access
639 Returns the access mode of the folder, as set by new(access)
640 $obj->isModified
642 Checks if the folder, as stored in memory, is modified. A true
643 value is returned when any of the messages is to be deleted, has
644 changed, or messages were added after the folder was read from
645 file.
646 WARNING: this flag is not related to an external change to the
648 folder structure on disk. Have a look at update() for that.
649 $obj->modified([BOOLEAN])
651 Sets whether the folder is modified or not.
652 $obj->writable
654 Checks whether the current folder is writable.
655 example:
657 $folder->addMessage($msg) if $folder->writable;
659 The messages
661 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
662 Some mail-readers keep the current message, which represents the
663 last used message. This method returns [after setting] the current
664 message. You may specify a NUMBER, to specify that that message
665 number is to be selected as current, or a MESSAGE/MESSAGE-ID (as
666 long as you are sure that the header is already loaded, otherwise
667 they are not recognized).
668 example:
670 $folder->current(0);
672 $folder->current($message);
673 $obj->find(MESSAGE-ID)
675 Like messageId(), this method searches for a message with the
676 MESSAGE-ID, returning the corresponding message object. However,
677 "find" will cause unparsed message in the folder to be parsed until
678 the message-id is found. The folder will be scanned back to front.
679 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
681 Find the first message which has this LABEL with the correct
682 setting. The BOOLEAN indicates whether any true value or any false
683 value is to be found. By default, a true value is searched for.
684 When a message does not have the requested label, it is taken as
685 false.
686 example: looking for a labeled message
688 my $current = $folder->findFirstLabeled('current');
690 my $first = $folder->findFirstLabeled(seen => 0);
692 my $last = $folder->findFirstLabeled(seen => 0,
694 [ reverse $self->messages('ACTIVE') ] )
695 $obj->message(INDEX [,MESSAGE])
697 Get or set a message with on a certain index. Messages which are
698 flagged for deletion are counted. Negative indexes start at the
699 end of the folder.
700 example:
702 my $msg = $folder->message(3);
704 $folder->message(3)->delete; # status changes to `deleted'
705 $folder->message(3, $msg);
706 print $folder->message(-1); # last message.
707 $obj->messageId(MESSAGE-ID [,MESSAGE])
709 With one argument, returns the message in the folder with the
710 specified MESSAGE-ID. If a reference to a message object is passed
711 as the optional second argument, the message is first stored in the
712 folder, replacing any existing message whose message ID is MESSAGE-
713 ID. (The message ID of MESSAGE need not match MESSAGE-ID.)
714 !!WARNING!!: when the message headers are delay-parsed, the message
716 might be in the folder but not yet parsed into memory. In this
717 case, use find() instead of "messageId()" if you really need a
718 thorough search. This is especially the case for directory
719 organized folders without special indexi, like Mail::Box::MH.
720 The MESSAGE-ID may still be in angles, which will be stripped. In
722 that case blanks (which origin from header line folding) are
723 removed too. Other info around the angles will be removed too.
724 example:
726 my $msg = $folder->messageId('<complex-message.id>');
728 $folder->messageId("<complex-message\n.id>", $msg);
729 my $msg = $folder->messageId('complex-message.id');
730 my $msg = $folder->messageId('garbage <complex-message.id> trash');
731 $obj->messageIds
733 Returns a list of all message-ids in the folder, including those of
734 messages which are to be deleted.
735 For some folder-types (like MH), this method may cause all message-
737 files to be read. See their respective manual pages.
738 example:
740 foreach my $id ($folder->messageIds) {
742 $folder->messageId($id)->print;
743 }
744 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
746 Returns multiple messages from the folder. The default is "ALL"
747 which will return (as expected maybe) all the messages in the
748 folder. The "ACTIVE" flag will return the messages not flagged for
749 deletion. This is the opposite of "DELETED", which returns all
750 messages from the folder which will be deleted when the folder is
751 closed.
752 You may also specify a RANGE: two numbers specifying begin and end
754 index in the array of messages. Negative indexes count from the
755 end of the folder. When an index is out-of-range, the returned
756 list will be shorter without complaints.
757 Everything else than the predefined names is seen as labels. The
759 messages which have that label set will be returned. When the
760 sequence starts with an exclamation mark (!), the search result is
761 reversed.
762 For more complex searches, you can specify a FILTER, which is
764 simply a code reference. The message is passed as only argument.
765 example:
767 foreach my $message ($folder->messages) {...}
769 foreach my $message (@$folder) {...}
770 # twice the same
772 my @messages = $folder->messages;
773 my @messages = $folder->messages('ALL');
774 # Selection based on a range (begin, end)
776 my $subset = $folder->messages(10,-8);
777 # twice the same:
779 my @not_deleted= grep {not $_->isDeleted}
780 $folder->messages;
781 my @not_deleted= $folder->messages('ACTIVE');
782 # scalar context the number of messages
784 my $nr_of_msgs = $folder->messages;
785 # third message, via overloading
787 $folder->[2];
788 # Selection based on labels
790 $mgr->moveMessages($spam, $inbox->message('spam'));
791 $mgr->moveMessages($archive, $inbox->message('seen'));
792 $obj->nrMessages(OPTIONS)
794 Simply calls messages() in scalar context to return a count instead
795 of the messages itself. Some people seem to understand this
796 better. Note that nrMessages() will default to returning a count
797 of "ALL" messages in the folder, including both "ACTIVE" and
798 "DELETED".
799 The OPTIONS are passed to (and explained in) messages().
801 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
803 You start with a MESSAGE, and are looking for a set of messages
804 which are related to it. For instance, messages which appear in
805 the 'In-Reply-To' and 'Reference' header fields of that message.
806 These messages are known by their MESSAGE-IDS and you want to find
807 them in the folder.
808 When all message-ids are known, then looking-up messages is simple:
810 they are found in a plain hash using messageId(). But Mail::Box is
811 lazy where it can, so many messages may not have been read from
812 file yet, and that's the preferred situation, because that saves
813 time and memory.
814 It is not smart to search for the messages from front to back in
816 the folder: the chances are much higher that related message reside
817 closely to each other. Therefore, this method starts scanning the
818 folder from the specified MESSAGE, back to the front of the folder.
819 The TIMESPAN can be used to terminate the search based on the time
821 enclosed in the message. When the constant string "EVER" is used
822 as TIMESPAN, then the search is not limited by that. When an
823 integer is specified, it will be used as absolute time in time-
824 ticks as provided by your platform dependent "time" function. In
825 other cases, it is passed to timespan2seconds() to determine the
826 threshold as time relative to the message's time.
827 The WINDOW is used to limit the search in number of messages to be
829 scanned as integer or constant string "ALL".
830 Returned are the message-ids which were not found during the scan.
832 Be warned that a message-id could already be known and therefore
833 not found: check that first.
834 example: scanning through a folder for a message
836 my $refs = $msg->get('References') or return;
838 my @msgids = $ref =~ m/\<([^>]+\>/g;
839 my @failed = $folder->scanForMessages($msg, \@msgids, '3 days', 50);
840 Sub-folders
842 $obj->listSubFolders(OPTIONS)
843 Mail::Box->listSubFolders(OPTIONS)
844 List the names of all sub-folders to this folder, not recursively
846 decending. Use these names as argument to openSubFolder(), to get
847 access to that folder.
848 For MBOX folders, sub-folders are simulated.
850 -Option --Default
852 check <false>
853 folder <from calling object>
854 folderdir <from folder>
855 skip_empty <false>
856 check => BOOLEAN
858 Should all returned foldernames be checked to be sure that they
859 are of the right type? Each sub-folder may need to be opened to
860 check this, with a folder type dependent penalty (in some cases
861 very expensive).
862 folder => FOLDERNAME
864 The folder whose sub-folders should be listed.
865 folderdir => DIRECTORY
867 skip_empty => BOOL
868 Shall empty folders (folders which currently do not contain any
869 messages) be included? Empty folders are not useful to open, but
870 may be useful to save to.
871 example:
873 my $folder = $mgr->open('=in/new');
875 my @subs = $folder->listSubFolders;
876 my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');
878 my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.
879 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
881 Mail::Box->nameOfSubFolder(SUBNAME, [PARENTNAME])
882 Returns the constructed name of the folder with NAME, which is a
884 sub-folder of this current one. You have either to call this
885 method as instance method, or specify a PARENTNAME.
886 example: how to get the name of a subfolder
888 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc');
890 print $sub; # abc/xyz
891 my $f = Mail::Box::Mbox->new(folder => 'abc');
893 print $f->nameOfSubfolder('xyz'); # abc/xyz
894 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef);
896 print $sub; # xyz
897 $obj->openRelatedFolder(OPTIONS)
899 Open a folder (usually a sub-folder) with the same options as this
900 one. If there is a folder manager in use, it will be informed
901 about this new folder. OPTIONS overrule the options which where
902 used for the folder this method is called upon.
903 $obj->openSubFolder(SUBNAME, OPTIONS)
905 Open (or create, if it does not exist yet) a new subfolder in an
906 existing folder.
907 example:
909 my $folder = Mail::Box::Mbox->new(folder => '=Inbox');
911 my $sub = $folder->openSubFolder('read');
912 $obj->topFolderWithMessages
914 Mail::Box->topFolderWithMessages
915 Some folder types can have messages in the top-level folder, some
917 other can't.
918 Internals
920 $obj->coerce(MESSAGE, OPTIONS)
921 Coerce the MESSAGE to be of the correct type to be placed in the
922 folder. You can specify Mail::Internet and MIME::Entity objects
923 here: they will be translated into Mail::Message messages first.
924 $obj->create(FOLDERNAME, OPTIONS)
926 Mail::Box->create(FOLDERNAME, OPTIONS)
927 Create a folder. If the folder already exists, it will be left
929 unchanged. The folder is created, but not opened! If you want to
930 open a file which may need to be created, then use
931 Mail::Box::Manager::open() with the create flag, or
932 Mail::Box::new(create).
933 -Option --Default
935 folderdir undef
936 folderdir => DIRECTORY
938 When the foldername is preceded by a "=", the "folderdir"
939 directory will be searched for the named folder.
940 $obj->determineBodyType(MESSAGE, HEAD)
942 Determine which kind of body will be created for this message when
943 reading the folder initially.
944 Mail::Box->foundIn([FOLDERNAME], OPTIONS)
946 Determine if the specified folder is of the type handled by the
947 folder class. This method is extended by each folder sub-type.
948 The FOLDERNAME specifies the name of the folder, as is specified by
950 the application. You need to specified the "folder" option when
951 you skip this first argument.
952 OPTIONS is a list of extra information for the request. Read the
954 documentation for each type of folder for type specific options,
955 but each folder class will at least support the "folderdir" option:
956 -Option --Default
958 folderdir undef
959 folderdir => DIRECTORY
961 The location where the folders of this class are stored by
962 default. If the user specifies a name starting with a "=", that
963 indicates that the folder is to be found in this default
964 DIRECTORY.
965 example:
967 Mail::Box::Mbox->foundIn('=markov',
969 folderdir => "$ENV{HOME}/Mail");
970 Mail::Box::MH->foundIn(folder => '=markov');
971 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
973 Returns the character or characters used to separate lines in the
974 folder file, optionally after setting it to STRING, or one of the
975 constants. The first line of the folder sets the default.
976 UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF.
978 Each separator will be represented by a "\n" within your program.
979 However, when processing platform foreign folders, complications
980 appear. Think about the "Size" field in the header.
981 When the separator is changed, the whole folder me be rewritten.
983 Although, that may not be required.
984 $obj->locker
986 Returns the locking object.
987 $obj->read(OPTIONS)
989 Read messages from the folder into memory. The OPTIONS are folder
990 specific. Do not call "read()" yourself: it will be called for you
991 when you open the folder via the manager or instantiate a folder
992 object directly.
993 NOTE: if you are copying messages from one folder to another, use
995 addMessages() instead of "read()".
996 example:
998 my $mgr = Mail::Box::Manager->new;
1000 my $folder = $mgr->open('InBox'); # implies read
1001 my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same
1002 $obj->readMessages(OPTIONS)
1004 Called by read() to actually read the messages from one specific
1005 folder type. The read() organizes the general activities.
1006 The OPTIONS are "trusted", "head_type", "field_type",
1008 "message_type", "body_delayed_type", and "head_delayed_type" as
1009 defined by the folder at hand. The defaults are the constructor
1010 defaults (see new()).
1011 $obj->storeMessage(MESSAGE)
1013 Store the message in the folder without the checks as performed by
1014 addMessage().
1015 $obj->toBeThreaded(MESSAGES)
1017 The specified message is ready to be removed from a thread. This
1018 will be passed on to the mail-manager, which keeps an overview on
1019 which thread-detection objects are floating around.
1020 $obj->toBeUnthreaded(MESSAGES)
1022 The specified message is ready to be included in a thread. This
1023 will be passed on to the mail-manager, which keeps an overview on
1024 which thread-detection objects are floating around.
1025 $obj->updateMessages(OPTIONS)
1027 Called by update() to read messages which arrived in the folder
1028 after it was opened. Sometimes, external applications dump
1029 messages in a folder without locking (or using a different lock
1030 than your application does).
1031 Although this is quite a dangerous, it only fails when a folder is
1033 updated (reordered or message removed) at exactly the same time as
1034 new messages arrive. These collisions are sparse.
1035 The options are the same as for readMessages().
1037 $obj->write(OPTIONS)
1039 Write the data to disk. The folder (a "true" value) is returned if
1040 successful. Deleted messages are transformed into destroyed
1041 messages: their memory is freed.
1042 WARNING: When moving messages from one folder to another, be sure
1044 to write (or close()) the destination folder before writing (or
1045 closing) the source folder: otherwise you may lose data if the
1046 system crashes or if there are software problems.
1047 To write a folder to a different file, you must first create a new
1049 folder, then move all the messages, and then write or close() that
1050 new folder.
1051 -Option --Default
1053 force <false>
1054 save_deleted <false>
1055 force => BOOLEAN
1057 Override write-protection with new(access) while opening the
1058 folder (whenever possible, it may still be blocked by the
1059 operating system).
1060 save_deleted => BOOLEAN
1062 Do also write messages which where flagged to be deleted to their
1063 folder. The flag for deletion is conserved (when possible),
1064 which means that a re-open of the folder may remove the messages
1065 for real. See close(save_deleted).
1066 $obj->writeMessages(OPTIONS)
1068 Called by write() to actually write the messages from one specific
1069 folder type. The "write" organizes the general activities. All
1070 options to write() are passed to "writeMessages" as well. Besides,
1071 a few extra are added by "write" itself.
1072 -Option --Default
1074 messages <required>
1075 messages => ARRAY
1077 The messages to be written, which is a sub-set of all messages in
1078 the current folder.
1079 Other methods
1081 $obj->timespan2seconds(TIME)
1082 Mail::Box->timespan2seconds(TIME)
1083 TIME is a string, which starts with a float, and then one of the
1085 words 'hour', 'hours', 'day', 'days', 'week', or 'weeks'. For
1086 instance: '1 hour' or '4 weeks'.
1087 Error handling
1089 $obj->AUTOLOAD
1090 See "Error handling" in Mail::Reporter
1091 $obj->addReport(OBJECT)
1093 See "Error handling" in Mail::Reporter
1094 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
1096 Mail::Box->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
1097 CALLBACK])
1098 See "Error handling" in Mail::Reporter
1100 $obj->errors
1102 See "Error handling" in Mail::Reporter
1103 $obj->log([LEVEL [,STRINGS]])
1105 Mail::Box->log([LEVEL [,STRINGS]])
1106 See "Error handling" in Mail::Reporter
1108 $obj->logPriority(LEVEL)
1110 Mail::Box->logPriority(LEVEL)
1111 See "Error handling" in Mail::Reporter
1113 $obj->logSettings
1115 See "Error handling" in Mail::Reporter
1116 $obj->notImplemented
1118 See "Error handling" in Mail::Reporter
1119 $obj->report([LEVEL])
1121 See "Error handling" in Mail::Reporter
1122 $obj->reportAll([LEVEL])
1124 See "Error handling" in Mail::Reporter
1125 $obj->trace([LEVEL])
1127 See "Error handling" in Mail::Reporter
1128 $obj->warnings
1130 See "Error handling" in Mail::Reporter
1131 Cleanup
1133 $obj->DESTROY
1134 This method is called by Perl when an folder-object is no longer
1135 accessible by the rest of the program.
1136 $obj->inGlobalDestruction
1138 See "Cleanup" in Mail::Reporter
1139
1141 Different kinds of folders
1142 In general, there are three classes of folders: those who group
1143 messages per file, those who group messages in a directory, and those
1144 do not provide direct access to the message data. These folder types
1145 are each based on a different base class.
1146 · File based folders Mail::Box::File
1148 File based folders maintain a folder (a set of messages) in one
1150 single file. The advantage is that your folder has only one single
1151 file to access, which speeds-up things when all messages must be
1152 accessed at once.
1153 One of the main disadvantages over directory based folders is that
1155 you have to construct some means to keep all message apart. For
1156 instance MBOX adds a message separator line between the messages in
1157 the file, and this line can cause confusion with the message's
1158 contents.
1159 Where access to all messages at once is faster in file based
1161 folders, access to a single message is (much) slower, because the
1162 whole folder must be read. However, in directory based folders you
1163 have to figure-out which message you need, which may be a hassle as
1164 well.
1165 Examples of file based folders are MBOX, DBX, and NetScape.
1167 · Directory based folders Mail::Box::Dir
1169 In stead of collecting multiple messages in one file, you can also
1171 put each message in a separate file and collect those files in a
1172 directory to represent a folder.
1173 The main disadvantages of these folders are the enormous amount of
1175 tiny files you usually get in your file-system. It is extremely
1176 slow to search through your whole folder, because many files have
1177 to be opened to do so.
1178 The best feature of this organization is that each message is kept
1180 exactly as it was received, and can be processed with external
1181 scripts as well: you do not need any mail user agent (MUA).
1182 Examples of directoy organized folders are MH, Maildir, EMH, and
1184 XMH.
1185 · Network (external) folders Mail::Box::Net
1187 Where both types described before provide direct access to the
1189 message data, maintain these folder types the message data for you:
1190 you have to request for messages or parts of them. These folders
1191 do not have a filename, file-system privileges and system locking
1192 to worry about, but typically require a hostname, folder and
1193 message IDs, and authorization.
1194 Examples of these folder types are the popular POP and IMAP, and
1196 database oriented message storage.
1197 Available folder types
1199 · Mail::Box::Dbx (read only)
1200 Dbx files are created by Outlook Express. Using the external
1202 (optional) Mail::Transport::Dbx module, you can read these folders,
1203 even when you are running MailBox on a UNIX/Linux platform.
1204 Writing and deleting messages is not supported by the library, and
1206 therefore not by MailBox. Read access is enough to do folder
1207 conversions, for instance.
1208 · Mail::Box::IMAP4 (partially)
1210 The IMAP protocol is very complex. Some parts are implemented to
1212 create (sub-optimal but usable) IMAP clients. Besides, there are
1213 also some parts for IMAP servers present. The most important
1214 lacking feature is support for encrypted connections.
1215 · Mail::Box::Maildir
1217 Maildir folders have a directory for each folder. A folder
1219 directory contains "tmp", "new", and "cur" sub-directories, each
1220 containting messages with a different purpose. Files with new
1221 messages are created in "tmp", then moved to "new" (ready to be
1222 accepted). Later, they are moved to the "cur" directory
1223 (accepted). Each message is one file with a name starting with
1224 timestamp. The name also contains flags about the status of the
1225 message.
1226 Maildir folders can not be used on Windows by reason of file-name
1228 limitations on that platform.
1229 · Mail::Box::Mbox
1231 A folder type in which all related messages are stored in one file.
1233 This is a very common folder type for UNIX.
1234 · Mail::Box::MH
1236 This folder creates a directory for each folder, and a message is
1238 one file inside that directory. The message files are numbered
1239 sequentially on order of arrival. A special ".mh_sequences" file
1240 maintains flags about the messages.
1241 · Mail::Box::POP3 (read/delete only)
1243 POP3 is a protocol which can be used to retreive messages from a
1245 remote system. After the connection to a POP server is made, the
1246 messages can be looked at and removed as if they are on the local
1247 system.
1248 · Mail::Box::Netzwert
1250 The Netzwert folder type is optimized for mailbox handling on a
1252 cluster of systems with a shared NFS storage. The code is not
1253 released under GPL (yet)
1254 Other folder types are on the (long) wishlist to get implemented.
1256 Please, help implementing more of them.
1257 Folder class implementation
1259 The class structure of folders is very close to that of messages. For
1260 instance, a Mail::Box::File::Message relates to a Mail::Box::File
1261 folder. The folder types are:
1262 Mail::Box::Netzwert
1264 Mail::Box::Mbox | Mail::Box::Maildir Mail::Box::POP3
1265 | Mail::Box::Dbx | | Mail::Box::MH | Mail::Box::IMAP4
1266 | | | | | | |
1267 | | | | | | |
1268 Mail::Box::File Mail::Box::Dir Mail::Box::Net
1269 | | |
1270 `--------------. | .---------------'
1271 | | |
1272 Mail::Box
1273 |
1274 |
1275 Mail::Reporter (general base class)
1276 By far most folder features are implemented in Mail::Box, so available
1278 to all folder types. Sometimes, features which appear in only some of
1279 the folder types are simulated for folders that miss them, like sub-
1280 folder support for MBOX.
1281
1283 Warning: Changes not written to read-only folder $self.
1284 You have opened the folder read-only --which is the default set by
1285 new(access)--, made modifications, and now want to close it. Set
1286 close(force) if you want to overrule the access mode, or close the
1287 folder with close(write) set to "NEVER".
1288 Error: Copying failed for one message.
1290 For some reason, for instance disc full, removed by external
1291 process, or read-protection, it is impossible to copy one of the
1292 messages. Copying will proceed for the other messages.
1293 Error: Destination folder $name is not writable.
1295 The folder where the messages are copied to is not opened with
1296 write access (see new(access)). This has no relation with write
1297 permission to the folder which is controled by your operating
1298 system.
1299 Warning: Different messages with id $msgid
1301 The message id is discovered more than once within the same folder,
1302 but the content of the message seems to be different. This should
1303 not be possible: each message must be unique.
1304 Error: Folder $name is opened read-only
1306 You can not write to this folder unless you have opened the folder
1307 to write or append with new(access), or the "force" option is set
1308 true.
1309 Error: Folder $name not deleted: not writable.
1311 The folder must be opened with write access via new(access),
1312 otherwise removing it will be refused. So, you may have write-
1313 access according to the operating system, but that will not
1314 automatically mean that this "delete" method permits you to. The
1315 reverse remark is valid as well.
1316 Error: Invalid timespan '$timespan' specified.
1318 The string does not follow the strict rules of the time span syntax
1319 which is permitted as parameter.
1320 Warning: Message-id '$msgid' does not contain a domain.
1322 According to the RFCs, message-ids need to contain a unique random
1323 part, then an "@", and then a domain name. This is made to avoid
1324 the creation of two messages with the same id. The warning emerges
1325 when the "@" is missing from the string.
1326 Error: No folder name specified.
1328 You did not specify the name of a folder to be opened. Use the
1329 new(folder) option or set the "MAIL" environment variable.
1330 Error: Package $package does not implement $method.
1332 Fatal error: the specific package (or one of its superclasses) does
1333 not implement this method where it should. This message means that
1334 some other related classes do implement this method however the
1335 class at hand does not. Probably you should investigate this and
1336 probably inform the author of the package.
1337 Error: Unable to create subfolder $name of $folder.
1339 The copy includes the subfolders, but for some reason it was not
1340 possible to copy one of these. Copying will proceed for all other
1341 sub-folders.
1342 Error: Writing folder $name failed
1344 For some reason (you probably got more error messages about this
1345 problem) it is impossible to write the folder, although you should
1346 because there were changes made.
1347
1349 This module is part of Mail-Box distribution version 2.097, built on
1350 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
1351
1353 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
1354 ChangeLog.
1355 This program is free software; you can redistribute it and/or modify it
1357 under the same terms as Perl itself. See
1358 http://www.perl.com/perl/misc/Artistic.html
1359perl v5.12.3 2011-01-26 Mail::Box(3)