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 sepa‐
64 rate 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
73 simplifies especially print statements and sorting a lot.
74 Example: use overloaded folder as string
76 # Three lines with overloading: resp. cmp, @{}, and ""
78 foreach my $folder (sort @folders)
79 { my $msgcount = @$folder;
80 print "$folder contains $msgcount messages\n";
81 }
82 overload: @{}
84 When the folder is used as if it is a reference to an array, it
86 will show the messages, like messages() and message() would do.
87 Example: use overloaded folder as array
89 my $msg = $folder->[3];
91 my $msg = $folder->message(3); # same
92 foreach my $msg (@$folder) ...
94 foreach my $msg ($folder->messages) ... # same
95 overload: cmp
97 (string comparison) folders are compared based on their name. The
99 sort rules are those of the build-in "cmp".
100
102 Constructors
103 Mail::Box->new(OPTIONS)
105 Open a new folder. A list of labeled OPTIONS for the mailbox can be
107 supplied. Some options pertain to Mail::Box, and others are added
108 by sub-classes. The list below describes all the options provided
109 by any Mail::Box.
110 To control delay-loading of messages, as well the headers as the
112 bodies, a set of *_type options are available. "extract" determines
113 whether we want delay-loading.
114 Option --Defined in --Default
116 access 'r'
117 body_delayed_type Mail::Message::Body::Delayed
118 body_type <folder specific>
119 coerce_options []
120 create <false>
121 extract 10240
122 field_type undef
123 fix_headers <false>
124 folder $ENV{MAIL}
125 folderdir undef
126 head_delayed_type Mail::Message::Head::Delayed
127 head_type Mail::Message::Head::Complete
128 keep_dups <false>
129 lock_file undef
130 lock_timeout 1 hour
131 lock_type Mail::Box::Locker::DotLock
132 lock_wait 10 seconds
133 locker undef
134 log Mail::Reporter 'WARNINGS'
135 manager undef
136 message_type Mail::Box::Message
137 multipart_type Mail::Message::Body::Multipart
138 remove_when_empty <true>
139 save_on_exit <true>
140 trace Mail::Reporter 'WARNINGS'
141 trusted <depends on folder location>
142 . access MODE
144 Access-rights to the folder. Folders are opened for read-only
146 (which means write-protected) by default! MODE can be
147 'r': read-only (default)
149 'a': append
150 'rw': read-write
151 'd': delete
152 These MODE has no relation to the modes actually used to open
154 the folder files within this module. For instance, if you
155 specify "rw", and open the folder, only read permission on the
156 folder-file is required.
157 Be warned: writing a MBOX folder may create a new file to
159 replace the old folder. The permissions and owner of the file
160 may get changed by this.
161 . body_delayed_type CLASS
163 The bodies which are delayed: which will be read from file when
165 it is needed, but not before.
166 . body_type CLASS⎪CODE
168 When messages are read from a folder-file, the headers will be
170 stored in a "head_type" object. For the body, however, there
171 is a range of choices about type, which are all described in
172 Mail::Message::Body.
173 Specify a CODE-reference which produces the body-type to be
175 created, or a CLASS of the body which is used when the body is
176 not a multipart or nested. In case of a code reference, the
177 header structure is passed as first argument to the routine.
178 Do not return a delayed body-type (like "::Delayed"), because
180 that is determined by the "extract" option while the folder is
181 opened. Even delayed message will require some real body type
182 when they get parsed eventually. Multiparts and nested mes‐
183 sages are also outside your control.
184 For instance:
186 $mgr->open('InBox', body_type => \&which_body);
188 sub which_body($) {
190 my $head = shift;
191 my $size = $head->guessBodySize ⎪⎪ 0;
192 my $type = $size > 100000 ? 'File' : 'Lines';
193 "Mail::Message::Body::$type";
194 }
195 The default depends on the mail-folder type, although the gen‐
197 eral default is Mail::Message::Body::Lines. Please check the
198 applicable manual pages.
199 . coerce_options ARRAY
201 Keep configuration information for messages which are coerced
203 into the specified folder type, starting with a different
204 folder type (or even no folder at all). Messages which are
205 coerced are always fully read, so this kind of information does
206 not need to be kept here.
207 . create BOOLEAN
209 Automatically create the folder when it does not exist yet.
211 This will only work when access is granted for writing or
212 appending to the folder.
213 Be careful: you may create a different folder type than you
215 expect unless you explicitly specify Mail::Box::Man‐
216 ager::open(type).
217 . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
219 Defines when to parse (process) the content of the message.
221 When the header of a message is read, you may want to postpone
222 the reading of the body: header information is more often
223 needed than the body data, so why parse it always together?
224 The cost of delaying is not too high, and with some luck you
225 may never need parsing the body.
226 If you supply an INTEGER to this option, bodies of those mes‐
228 sages with a total size less than that number will be extracted
229 from the folder only when necessary. Messages where the size
230 (in the "Content-Length" field) is not included in the header,
231 like often the case for multiparts and nested messages, will
232 not be extracted by default.
233 If you supply a CODE reference, that subroutine is called every
235 time that the extraction mechanism wants to determine whether
236 to parse the body or not. The subroutine is called with the
237 following arguments:
238 CODE->(FOLDER, HEAD)
240 where FOLDER is a reference to the folder we are reading. HEAD
242 refers to the Mail::Message::Head::Complete head of the message
243 at hand. The routine must return a "true" value (extract now)
244 or a "false" value (be lazy, do not parse yet). Think about
245 using the Mail::Message::Head::guessBodySize() and Mail::Mes‐
246 sage::guessTimestamp() on the header to determine your choice.
247 The third possibility is to specify the NAME of a method. In
249 that case, for each message is called:
250 FOLDER->NAME(HEAD)
252 Where each component has the same meaning as described above.
254 The fourth way to use this option involves constants: with
256 "LAZY" all messages will be delayed. With "ALWAYS" you enforce
257 unconditional parsing, no delaying will take place. The latter
258 is usuful when you are sure you always need all the messages in
259 the folder.
260 $folder->new(extract => 'LAZY'); # Very lazy
262 $folder->new(extract => 10000); # Less than 10kB
263 # same, but implemented yourself
265 $folder->new(extract => &large);
266 sub large($) {
267 my ($f, $head) = @_;
268 my $size = $head->guessBodySize;
269 defined $size ? $size < 10000 : 1
270 };
271 # method call by name, useful for Mail::Box
273 # extensions. The example selects all messages
274 # sent by you to be loaded without delay.
275 # Other messages will be delayed.
276 $folder->new(extract => 'sent_by_me');
277 sub Mail::Box::send_by_me($) {
278 my ($self, $header) = @_;
279 $header->get('from') =~ m/\bmy\@example.com\b/i;
280 }
281 . field_type CLASS
283 The type of the fields to be used in a header. Must extend
285 Mail::Message::Field.
286 . fix_headers BOOLEAN
288 Broken MIME headers usually stop the parser: all lines not
290 parsed are added to the body of the message. With this flag
291 set, the erroneous line is added to the previous header field
292 and parsing is continued. See
293 Mail::Box::Parser::Perl::new(fix_header_errors).
294 . folder FOLDERNAME
296 Which folder to open (for reading or writing). When used for
298 reading (the "access" option set to "r" or "a") the mailbox
299 should already exist and must be readable. The file or direc‐
300 tory of the mailbox need not exist if it is opened for reading
301 and writing ("rw"). Write-permission is checked when opening
302 an existing mailbox.
303 The folder name can be preceded by a "=", to indicate that it
305 is named relative to the directory specified in new(folderdir).
306 Otherwise, it is taken as relative or absolute path.
307 . folderdir DIRECTORY
309 Where are folders to be found by default? A folder-name may be
311 preceded by a equals-sign ("=", a "mutt" convension) to explic‐
312 itly state that the folder is located below the default direc‐
313 tory. For example: in case "folderdir => '/tmp'" and "folder
314 => '=abc'", the name of the folder-file is '/tmp/abc'. Each
315 folder type has already some default set.
316 . head_delayed_type CLASS
318 The headers which are delayed: which will be read from file
320 when it is needed, but not before.
321 . head_type CLASS
323 The type of header which contains all header information. Must
325 extend Mail::Message::Head::Complete.
326 . keep_dups BOOLEAN
328 Indicates whether or not duplicate messages within the folder
330 should be retained. A message is considered to be a duplicate
331 if its message-id is the same as a previously parsed message
332 within the same folder. If this option is false (the default)
333 such messages are automatically deleted, because it is consid‐
334 ered useless to store the same message twice.
335 . lock_file FILENAME
337 The name of the file which is used to lock. This must be spec‐
339 ified when locking is to be used.
340 . lock_timeout SECONDS
342 When the lock file is older than the specified number of SEC‐
344 ONDS, it is considered a mistake. The original lock is
345 released, and accepted for this folder.
346 . lock_type CLASS⎪STRING⎪ARRAY
348 The type of the locker object. This may be the full name of a
350 CLASS which extends Mail::Box::Locker, or one of the known
351 locker types "DotLock", "Flock", "Mutt", "NFS", "POSIX", or
352 "NONE". If an ARRAY is specified, then a Multi locker is built
353 which uses the specified list.
354 . lock_wait SECONDS
356 SECONDS to wait before failing on opening this folder.
358 . locker OBJECT
360 An OBJECT which extends Mail::Box::Locker, and will handle
362 folder locking replacing the default lock behavior.
363 . log LEVEL
365 . manager MANAGER
367 A reference to the object which manages this folder -- typi‐
369 cally an Mail::Box::Manager instance.
370 . message_type CLASS
372 What kind of message objects are stored in this type of folder.
374 The default is Mail::Box::Message (which is a sub-class of
375 Mail::Message). The class you offer must be an extension of
376 Mail::Box::Message.
377 . multipart_type CLASS
379 The default type of objects which are to be created for multi‐
381 part message bodies.
382 . remove_when_empty BOOLEAN
384 Determines whether to remove the folder file or directory auto‐
386 matically when the write would result in a folder without mes‐
387 sages nor sub-folders.
388 . save_on_exit BOOLEAN
390 Sets the policy for saving the folder when it is closed. A
392 folder can be closed manually (see close()) or in a number of
393 implicit ways, including on the moment the program is termi‐
394 nated.
395 . trace LEVEL
397 . trusted BOOLEAN
399 Flags whether to trust the data in the folder or not. Folders
401 which reside in your "folderdir" will be trusted by default
402 (even when the names if not specified staring with "="). Fold‐
403 ers which are outside the folderdir or read from STDIN
404 (Mail::Message::Construct::read()) are not trused by default,
405 and require some extra checking.
406 If you do not check encodings of received messages, you may
408 print binary data to the screen, which is a security risk.
409 The folder
411 $obj->addMessage(MESSAGE, OPTIONS)
413 Add a message to the folder. A message is usually a
415 Mail::Box::Message object or a sub-class thereof. The message
416 shall not be in an other folder, when you use this method. In case
417 it is, use Mail::Box::Manager::moveMessage() or Mail::Box::Man‐
418 ager::copyMessage() via the manager.
419 Messages with id's which already exist in this folder are not
421 added.
422 Option--Default
424 share <not used>
425 . share BOOLEAN
427 Try to share the physical resource of the current message with
429 the indicated message. It is sometimes possible to share mes‐
430 sages between different folder types. When the sharing is not
431 possible, than this option is simply ignored.
432 Sharing the resource is quite dangerous, and only available for
434 a limited number of folder types, at the moment only some
435 Mail::Box::Dir folders; these file-based messages can be
436 hardlinked (on platforms that support it). The link may get
437 broken when one message is modified in one of the folders....
438 but maybe not, depending on the folder types involved.
439 Example:
441 $folder->addMessage($msg);
443 $folder->addMessages($msg1, $msg2, ...);
444 $obj->addMessages(MESSAGE [, MESSAGE, ...])
446 Adds a set of MESSAGE objects to the open folder at once. For some
448 folder types this may be faster than adding them one at a time.
449 Example:
451 $folder->addMessages($msg1, $msg2, ...);
453 Mail::Box->appendMessages(OPTIONS)
455 Append one or more messages to an unopened folder. Usually, this
457 method is called by the Mail::Box::Manager::appendMessage(), in
458 which case the correctness of the folder type is checked.
459 For some folder types it is required to open the folder before it
461 can be used for appending. This can be fast, but this can also be
462 very slow (depends on the implementation). All OPTIONS passed will
463 also be used to open the folder, if needed.
464 Option --Default
466 folder <required>
467 message undef
468 messages undef
469 share <false>
470 . folder FOLDERNAME
472 The name of the folder to which the messages are to be
474 appended. The folder implementation will avoid opening the
475 folder when possible, because this is resource consuming.
476 . message MESSAGE
478 . messages ARRAY-OF-MESSAGES
480 One reference to a MESSAGE or a reference to an ARRAY of MES‐
482 SAGEs, which may be of any type. The messages will be first
483 coerced into the correct message type to fit in the folder, and
484 then will be added to it.
485 . share BOOLEAN
487 Try to share physical storage of the message. Only available
489 for a limited number of folder types, otherwise no-op.
490 Example:
492 my $message = Mail::Message->new(...);
494 Mail::Box::Mbox->appendMessages
495 ( folder => '=xyz'
496 , message => $message
497 , folderdir => $ENV{FOLDERS}
498 );
499 better:
501 my Mail::Box::Manager $mgr;
503 $mgr->appendMessages($message, folder => '=xyz');
504 $obj->close(OPTIONS)
506 Close the folder, which usually implies writing the changes. This
508 will return "false" when writing is required but fails. Please do
509 check this result.
510 WARNING: When moving messages from one folder to another, be sure
512 to write the destination folder before writing and closing the
513 source folder. Otherwise you may lose data if the system crashes
514 or if there are software problems.
515 Option --Default
517 force <false>
518 save_deleted false
519 write MODIFIED
520 . force BOOLEAN
522 Override the new(access) setting which was specified when the
524 folder was opened. This option only has an effect if its value
525 is TRUE. NOTE: Writing to the folder may not be permitted by
526 the operating system, in which case even "force" will not help.
527 . save_deleted BOOLEAN
529 Do also write messages which where flagged to be deleted to
531 their folder. The flag for deletion is conserved (when possi‐
532 ble), which means that a re-open of the folder may remove the
533 messages for real. See write(save_deleted).
534 . write 'ALWAYS'⎪'NEVER'⎪'MODIFIED'
536 Specifies whether the folder should be written. As could be
538 expected, "ALWAYS" means always (even if there are no changes),
539 "NEVER" means that changes to the folder will be lost, and
540 "MODIFIED" only saves the folder if there are any changes.
541 Example:
543 my $f = $mgr->open('spam', access => 'rw')
545 or die "Cannot open spam: $!\n";
546 $f->message(0)->delete
548 if $f->messages;
549 $f->close
551 or die "Couldn't write $f: $!\n";
552 $obj->copyTo(FOLDER, OPTIONS)
554 Copy the folder's messages to a new folder. The new folder may be
556 of a different type.
557 Option --Default
559 delete_copied <false>
560 select 'ACTIVE'
561 share <not used>
562 subfolders <folder type dependent>
563 . delete_copied BOOLEAN
565 Flag the messages from the source folder to be deleted, just
567 after it was copied. The deletion will only take effect when
568 the originating folder is closed.
569 . select 'ACTIVE'⎪'DELETED'⎪'ALL'⎪LABEL⎪!LABEL⎪FILTER
571 Which messages are to be copied. See the description of mes‐
573 sages() about how this works.
574 . share BOOLEAN
576 Try to share the message between the folders. Some
578 Mail::Box::Dir folder types do support it by creating a
579 hardlink (on UNIX/Linux).
580 . subfolders BOOLEAN⎪'FLATTEN'⎪'RECURSE'
582 How to handle sub-folders. When false (0 or "undef"), sub-
584 folders are simply ignored. With "FLATTEN", messages from sub-
585 folders are included in the main copy. "RECURSE" recursively
586 copies the sub-folders as well. By default, when the destina‐
587 tion folder supports sub-folders "RECURSE" is used, otherwise
588 "FLATTEN". A value of true will select the default.
589 Example:
591 my $mgr = Mail::Box::Manager->new;
593 my $imap = $mgr->open(type => 'imap', host => ...);
594 my $mh = $mgr->open(type => 'mh', folder => '/tmp/mh',
595 create => 1, access => 'w');
596 $imap->copyTo($mh, delete_copied => 1);
598 $mh->close; $imap->close;
599 $obj->delete(OPTIONS)
601 Remove the specified folder file or folder directory (depending on
603 the type of folder) from disk. Of course, THIS IS DANGEROUS: you
604 "may" lose data. Returns a "true" value on success.
605 WARNING: When moving messages from one folder to another, be sure
607 to write the destination folder before deleting the source folder.
608 Otherwise you may lose data if the system crashes or if there are
609 software problems.
610 Option --Default
612 recursive 1
613 . recursive BOOLEAN
615 Example: removing an open folder
617 my $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw');
619 ... some other code ...
620 $folder->delete;
621 Example: removing an closed folder
623 my $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd');
625 $folder->delete;
626 $obj->folderdir([DIRECTORY])
628 Get or set the DIRECTORY which is used to store mail-folders by
630 default.
631 Example:
633 print $folder->folderdir;
635 $folder->folderdir("$ENV{HOME}/nsmail");
636 $obj->name
638 Returns the name of the folder. What the name represents depends
640 on the actual type of mailbox used.
641 Example:
643 print $folder->name;
645 print "$folder"; # overloaded stringification
646 $obj->organization
648 Returns how the folder is organized: as one "FILE" with many mes‐
650 sages, a "DIRECTORY" with one message per file, or by a "REMOTE"
651 server.
652 $obj->size
654 Returns the size of the folder in bytes, not counting in the
656 deleted messages. The error in the presented result may be as
657 large as 10%, because the in-memory representation of messages is
658 not always the same as the size when they are written.
659 $obj->type
661 Returns a name for the type of mail box. This can be "mbox", "mh",
663 "maildir", or "pop3".
664 $obj->update(OPTIONS)
666 Read new messages from the folder, which where received after open‐
668 ing it. This is quite dangerous and shouldn't be possible: folders
669 which are open are locked. However, some applications do not use
670 locks or the wrong kind of locks. This method reads the changes
671 (not always failsafe) and incorporates them in the open folder
672 administration.
673 The OPTIONS are extra values which are passed to the updateMes‐
675 sages() method which is doing the actual work here.
676 $obj->url
678 Represent the folder as a URL (Universal Resource Locator) string.
680 You may pass such a URL as folder name to Mail::Box::Man‐
681 ager::open().
682 Example:
684 print $folder->url;
686 # may result in
687 # mbox:/var/mail/markov or
688 # pop3://user:password@pop.aol.com:101
689 Folder flags
691 $obj->access
693 Returns the access mode of the folder, as set by new(access)
695 $obj->isModified
697 Checks if the folder, as stored in memory, is modified. A true
699 value is returned when any of the messages is to be deleted, has
700 changed, or messages were added after the folder was read from
701 file.
702 WARNING: this flag is not related to an external change to the
704 folder structure on disk. Have a look at update() for that.
705 $obj->modified([BOOLEAN])
707 Sets whether the folder is modified or not.
709 $obj->writable
711 Checks whether the current folder is writable.
713 Example:
715 $folder->addMessage($msg) if $folder->writable;
717 The messages
719 $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
721 Some mail-readers keep the current message, which represents the
723 last used message. This method returns [after setting] the current
724 message. You may specify a NUMBER, to specify that that message
725 number is to be selected as current, or a MESSAGE/MESSAGE-ID (as
726 long as you are sure that the header is already loaded, otherwise
727 they are not recognized).
728 Example:
730 $folder->current(0);
732 $folder->current($message);
733 $obj->find(MESSAGE-ID)
735 Like messageId(), this method searches for a message with the MES‐
737 SAGE-ID, returning the corresponding message object. However,
738 "find" will cause unparsed message in the folder to be parsed until
739 the message-id is found. The folder will be scanned back to front.
740 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
742 Find the first message which has this LABEL with the correct set‐
744 ting. The BOOLEAN indicates whether any true value or any false
745 value is to be found. By default, a true value is searched for.
746 When a message does not have the requested label, it is taken as
747 false.
748 Example: looking for a labeled message
750 my $current = $folder->findFirstLabeled('current');
752 my $first = $folder->findFirstLabeled(seen => 0);
754 my $last = $folder->findFirstLabeled(seen => 0,
756 [ reverse $self->messages('ACTIVE') ] )
757 $obj->message(INDEX [,MESSAGE])
759 Get or set a message with on a certain index. Messages which are
761 flagged for deletion are counted. Negative indexes start at the
762 end of the folder.
763 Example:
765 my $msg = $folder->message(3);
767 $folder->message(3)->delete; # status changes to `deleted'
768 $folder->message(3, $msg);
769 print $folder->message(-1); # last message.
770 $obj->messageId(MESSAGE-ID [,MESSAGE])
772 With one argument, returns the message in the folder with the spec‐
774 ified MESSAGE-ID. If a reference to a message object is passed as
775 the optional second argument, the message is first stored in the
776 folder, replacing any existing message whose message ID is MES‐
777 SAGE-ID. (The message ID of MESSAGE need not match MESSAGE-ID.)
778 !!WARNING!!: when the message headers are delay-parsed, the message
780 might be in the folder but not yet parsed into memory. In this
781 case, use find() instead of "messageId()" if you really need a
782 thorough search. This is especially the case for directory orga‐
783 nized folders without special indexi, like Mail::Box::MH.
784 The MESSAGE-ID may still be in angles, which will be stripped. In
786 that case blanks (which origin from header line folding) are
787 removed too. Other info around the angles will be removed too.
788 Example:
790 my $msg = $folder->messageId('<complex-message.id>');
792 $folder->messageId("<complex-message\n.id>", $msg);
793 my $msg = $folder->messageId('complex-message.id');
794 my $msg = $folder->messageId('garbage <complex-message.id> trash');
795 $obj->messageIds
797 Returns a list of all message-ids in the folder, including those of
799 messages which are to be deleted.
800 For some folder-types (like MH), this method may cause all message-
802 files to be read. See their respective manual pages.
803 Example:
805 foreach my $id ($folder->messageIds) {
807 $folder->messageId($id)->print;
808 }
809 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
811 Returns multiple messages from the folder. The default is "ALL"
813 which will return (as expected maybe) all the messages in the
814 folder. The "ACTIVE" flag will return the messages not flagged for
815 deletion. This is the opposite of "DELETED", which returns all
816 messages from the folder which will be deleted when the folder is
817 closed.
818 You may also specify a RANGE: two numbers specifying begin and end
820 index in the array of messages. Negative indexes count from the
821 end of the folder. When an index is out-of-range, the returned
822 list will be shorter without complaints.
823 Everything else than the predefined names is seen as labels. The
825 messages which have that label set will be returned. When the
826 sequence starts with an exclamation mark (!), the search result is
827 reversed.
828 For more complex searches, you can specify a FILTER, which is sim‐
830 ply a code reference. The message is passed as only argument.
831 Example:
833 foreach my $message ($folder->messages) {...}
835 foreach my $message (@$folder) {...}
836 # twice the same
838 my @messages = $folder->messages;
839 my @messages = $folder->messages('ALL');
840 # Selection based on a range (begin, end)
842 my $subset = $folder->messages(10,-8);
843 # twice the same:
845 my @not_deleted= grep {not $_->isDeleted}
846 $folder->messages;
847 my @not_deleted= $folder->messages('ACTIVE');
848 # scalar context the number of messages
850 my $nr_of_msgs = $folder->messages;
851 # third message, via overloading
853 $folder->[2];
854 # Selection based on labels
856 $mgr->moveMessages($spam, $inbox->message('spam'));
857 $mgr->moveMessages($archive, $inbox->message('seen'));
858 $obj->nrMessages(OPTIONS)
860 Simply calls messages() in scalar context to return a count instead
862 of the messages itself. Some people seem to understand this bet‐
863 ter.
864 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
866 You start with a MESSAGE, and are looking for a set of messages
868 which are related to it. For instance, messages which appear in
869 the 'In-Reply-To' and 'Reference' header fields of that message.
870 These messages are known by their MESSAGE-IDS and you want to find
871 them in the folder.
872 When all message-ids are known, then looking-up messages is simple:
874 they are found in a plain hash using messageId(). But Mail::Box is
875 lazy where it can, so many messages may not have been read from
876 file yet, and that's the prefered situation, because that saves
877 time and memory.
878 It is not smart to search for the messages from front to back in
880 the folder: the chances are much higher that related message reside
881 closely to each other. Therefore, this method starts scanning the
882 folder from the specified MESSAGE, back to the front of the folder.
883 The TIMESPAN can be used to terminate the search based on the time
885 enclosed in the message. When the constant string "EVER" is used
886 as TIMESPAN, then the search is not limited by that. When an inte‐
887 ger is specified, it will be used as absolute time in time-ticks as
888 provided by your platform dependent "time" function. In other
889 cases, it is passed to timespan2seconds() to determine the thresh‐
890 old as time relative to the message's time.
891 The WINDOW is used to limit the search in number of messages to be
893 scanned as integer or constant string "ALL".
894 Returned are the message-ids which were not found during the scan.
896 Be warned that a message-id could already be known and therefore
897 not found: check that first.
898 Example: scanning through a folder for a message
900 my $refs = $msg->get('References') or return;
902 my @msgids = $ref =~ m/\<([^>]+\>/g;
903 my @failed = $folder->scanForMessages($msg, \@msgids, '3 days', 50);
904 Sub-folders
906 $obj->listSubFolders(OPTIONS)
908 Mail::Box->listSubFolders(OPTIONS)
910 List the names of all sub-folders to this folder, not recursively
912 decending. Use these names as argument to openSubFolder(), to get
913 access to that folder.
914 For MBOX folders, sub-folders are simulated.
916 Option --Default
918 check <false>
919 folder <from calling object>
920 folderdir <from folder>
921 skip_empty <false>
922 . check BOOLEAN
924 Should all returned foldernames be checked to be sure that they
926 are of the right type? Each sub-folder may need to be opened
927 to check this, with a folder type dependent penalty (in some
928 cases very expensive).
929 . folder FOLDERNAME
931 The folder whose sub-folders should be listed.
933 . folderdir DIRECTORY
935 . skip_empty BOOL
937 Shall empty folders (folders which currently do not contain any
939 messages) be included? Empty folders are not useful to open,
940 but may be useful to save to.
941 Example:
943 my $folder = $mgr->open('=in/new');
945 my @subs = $folder->listSubFolders;
946 my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');
948 my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.
949 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
951 Mail::Box->nameOfSubFolder(SUBNAME, [PARENTNAME])
953 Returns the constructed name of the folder with NAME, which is a
955 sub-folder of this current one. You have either to call this
956 method as instance method, or specify a PARENTNAME.
957 Example: how to get the name of a subfolder
959 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc');
961 print $sub; # abc/xyz
962 my $f = Mail::Box::Mbox->new(folder => 'abc');
964 print $f->nameOfSubfolder('xyz'); # abc/xyz
965 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef);
967 print $sub; # xyz
968 $obj->openRelatedFolder(OPTIONS)
970 Open a folder (usually a sub-folder) with the same options as this
972 one. If there is a folder manager in use, it will be informed
973 about this new folder. OPTIONS overrule the options which where
974 used for the folder this method is called upon.
975 $obj->openSubFolder(SUBNAME, OPTIONS)
977 Open (or create, if it does not exist yet) a new subfolder in an
979 existing folder.
980 Example:
982 my $folder = Mail::Box::Mbox->new(folder => '=Inbox');
984 my $sub = $folder->openSubFolder('read');
985 $obj->topFolderWithMessages
987 Mail::Box->topFolderWithMessages
989 Some folder types can have messages in the top-level folder, some
991 other can't.
992 Internals
994 $obj->coerce(MESSAGE, OPTIONS)
996 Coerce the MESSAGE to be of the correct type to be placed in the
998 folder. You can specify Mail::Internet and MIME::Entity objects
999 here: they will be translated into Mail::Message messages first.
1000 $obj->create(FOLDERNAME, OPTIONS)
1002 Mail::Box->create(FOLDERNAME, OPTIONS)
1004 Create a folder. If the folder already exists, it will be left
1006 unchanged. The folder is created, but not opened! If you want to
1007 open a file which may need to be created, then use Mail::Box::Man‐
1008 ager::open() with the create flag, or Mail::Box::new(create).
1009 Option --Default
1011 folderdir undef
1012 . folderdir DIRECTORY
1014 When the foldername is preceded by a "=", the "folderdir"
1016 directory will be searched for the named folder.
1017 $obj->determineBodyType(MESSAGE, HEAD)
1019 Determine which kind of body will be created for this message when
1021 reading the folder initially.
1022 Mail::Box->foundIn([FOLDERNAME], OPTIONS)
1024 Determine if the specified folder is of the type handled by the
1026 folder class. This method is extended by each folder sub-type.
1027 The FOLDERNAME specifies the name of the folder, as is specified by
1029 the application. You need to specified the "folder" option when
1030 you skip this first argument.
1031 OPTIONS is a list of extra information for the request. Read the
1033 documentation for each type of folder for type specific options,
1034 but each folder class will at least support the "folderdir" option:
1035 Option --Default
1037 folderdir undef
1038 . folderdir DIRECTORY
1040 The location where the folders of this class are stored by
1042 default. If the user specifies a name starting with a "=",
1043 that indicates that the folder is to be found in this default
1044 DIRECTORY.
1045 Example:
1047 Mail::Box::Mbox->foundIn('=markov',
1049 folderdir => "$ENV{HOME}/Mail");
1050 Mail::Box::MH->foundIn(folder => '=markov');
1051 $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
1053 Returns the character or characters used to separate lines in the
1055 folder file, optionally after setting it to STRING, or one of the
1056 constants. The first line of the folder sets the default.
1057 UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF.
1059 Each separator will be represented by a "\n" within your program.
1060 However, when processing platform foreign folders, complications
1061 appear. Think about the "Size" field in the header.
1062 When the separator is changed, the whole folder me be rewritten.
1064 Although, that may not be required.
1065 $obj->locker
1067 Returns the locking object.
1069 $obj->read(OPTIONS)
1071 Read messages from the folder into memory. The OPTIONS are folder
1073 specific. Do not call "read()" yourself: it will be called for you
1074 when you open the folder via the manager or instantiate a folder
1075 object directly.
1076 NOTE: if you are copying messages from one folder to another, use
1078 addMessages() instead of "read()".
1079 Example:
1081 my $mgr = Mail::Box::Manager->new;
1083 my $folder = $mgr->open('InBox'); # implies read
1084 my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same
1085 $obj->readMessages(OPTIONS)
1087 Called by read() to actually read the messages from one specific
1089 folder type. The read() organizes the general activities.
1090 The OPTIONS are "trusted", "head_type", "field_type", "mes‐
1092 sage_type", "body_delayed_type", and "head_delayed_type" as defined
1093 by the folder at hand. The defaults are the constructor defaults
1094 (see new()).
1095 $obj->storeMessage(MESSAGE)
1097 Store the message in the folder without the checks as performed by
1099 addMessage().
1100 $obj->toBeThreaded(MESSAGES)
1102 The specified message is ready to be removed from a thread. This
1104 will be passed on to the mail-manager, which keeps an overview on
1105 which thread-detection objects are floating around.
1106 $obj->toBeUnthreaded(MESSAGES)
1108 The specified message is ready to be included in a thread. This
1110 will be passed on to the mail-manager, which keeps an overview on
1111 which thread-detection objects are floating around.
1112 $obj->updateMessages(OPTIONS)
1114 Called by update() to read messages which arrived in the folder
1116 after it was opened. Sometimes, external applications dump mes‐
1117 sages in a folder without locking (or using a different lock than
1118 your application does).
1119 Although this is quite a dangerous, it only fails when a folder is
1121 updated (reordered or message removed) at exactly the same time as
1122 new messages arrive. These collisions are sparse.
1123 The options are the same as for readMessages().
1125 $obj->write(OPTIONS)
1127 Write the data to disk. The folder (a "true" value) is returned if
1129 successful. Deleted messages are transformed into destroyed mes‐
1130 sages: their memory is freed.
1131 WARNING: When moving messages from one folder to another, be sure
1133 to write (or close()) the destination folder before writing (or
1134 closing) the source folder: otherwise you may lose data if the sys‐
1135 tem crashes or if there are software problems.
1136 To write a folder to a different file, you must first create a new
1138 folder, then move all the messages, and then write or close() that
1139 new folder.
1140 Option --Default
1142 force <false>
1143 save_deleted <false>
1144 . force BOOLEAN
1146 Override write-protection with new(access) while opening the
1148 folder (whenever possible, it may still be blocked by the oper‐
1149 ating system).
1150 . save_deleted BOOLEAN
1152 Do also write messages which where flagged to be deleted to
1154 their folder. The flag for deletion is conserved (when possi‐
1155 ble), which means that a re-open of the folder may remove the
1156 messages for real. See close(save_deleted).
1157 $obj->writeMessages(OPTIONS)
1159 Called by write() to actually write the messages from one specific
1161 folder type. The "write" organizes the general activities. All
1162 options to write() are passed to "writeMessages" as well. Besides,
1163 a few extra are added by "write" itself.
1164 Option --Default
1166 messages <required>
1167 . messages ARRAY
1169 The messages to be written, which is a sub-set of all messages
1171 in the current folder.
1172 Other methods
1174 $obj->timespan2seconds(TIME)
1176 Mail::Box->timespan2seconds(TIME)
1178 TIME is a string, which starts with a float, and then one of the
1180 words 'hour', 'hours', 'day', 'days', 'week', or 'weeks'. For
1181 instance: '1 hour' or '4 weeks'.
1182 Error handling
1184 $obj->AUTOLOAD
1186 See "Error handling" in Mail::Reporter
1188 $obj->addReport(OBJECT)
1190 See "Error handling" in Mail::Reporter
1192 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
1194 Mail::Box->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALL‐
1196 BACK])
1197 See "Error handling" in Mail::Reporter
1199 $obj->errors
1201 See "Error handling" in Mail::Reporter
1203 $obj->log([LEVEL [,STRINGS]])
1205 Mail::Box->log([LEVEL [,STRINGS]])
1207 See "Error handling" in Mail::Reporter
1209 $obj->logPriority(LEVEL)
1211 Mail::Box->logPriority(LEVEL)
1213 See "Error handling" in Mail::Reporter
1215 $obj->logSettings
1217 See "Error handling" in Mail::Reporter
1219 $obj->notImplemented
1221 See "Error handling" in Mail::Reporter
1223 $obj->report([LEVEL])
1225 See "Error handling" in Mail::Reporter
1227 $obj->reportAll([LEVEL])
1229 See "Error handling" in Mail::Reporter
1231 $obj->trace([LEVEL])
1233 See "Error handling" in Mail::Reporter
1235 $obj->warnings
1237 See "Error handling" in Mail::Reporter
1239 Cleanup
1241 $obj->DESTROY
1243 This method is called by Perl when an folder-object is no longer
1245 accessible by the rest of the program.
1246 $obj->inGlobalDestruction
1248 See "Cleanup" in Mail::Reporter
1250
1252 Different kinds of folders
1253 In general, there are three classes of folders: those who group mes‐
1255 sages per file, those who group messages in a directory, and those do
1256 not provide direct access to the message data. These folder types are
1257 each based on a different base class.
1258 * File based folders Mail::Box::File
1260 File based folders maintain a folder (a set of messages) in one
1261 single file. The advantage is that your folder has only one single
1262 file to access, which speeds-up things when all messages must be
1263 accessed at once.
1264 One of the main disadvantages over directory based folders is that
1266 you have to construct some means to keep all message apart. For
1267 instance MBOX adds a message separator line between the messages in
1268 the file, and this line can cause confusion with the message's con‐
1269 tents.
1270 Where access to all messages at once is faster in file based fold‐
1272 ers, access to a single message is (much) slower, because the whole
1273 folder must be read. However, in directory based folders you have
1274 to figure-out which message you need, which may be a hassle as
1275 well.
1276 Examples of file based folders are MBOX, DBX, and NetScape.
1278 * Directory based folders Mail::Box::Dir
1280 In stead of collecting multiple messages in one file, you can also
1281 put each message in a separate file and collect those files in a
1282 directory to represent a folder.
1283 The main disadvantages of these folders are the enormous amount of
1285 tiny files you usually get in your file-system. It is extremely
1286 slow to search through your whole folder, because many files have
1287 to be opened to do so.
1288 The best feature of this organization is that each message is kept
1290 exactly as it was received, and can be processed with external
1291 scripts as well: you do not need any mail user agent (MUA).
1292 Examples of directoy organized folders are MH, Maildir, EMH, and
1294 XMH.
1295 * Network (external) folders Mail::Box::Net
1297 Where both types described before provide direct access to the mes‐
1298 sage data, maintain these folder types the message data for you:
1299 you have to request for messages or parts of them. These folders
1300 do not have a filename, file-system privileges and system locking
1301 to worry about, but typically require a hostname, folder and mes‐
1302 sage IDs, and authorization.
1303 Examples of these folder types are the popular POP and IMAP, and
1305 database oriented message storage.
1306 Available folder types
1308 * Mail::Box::Dbx (read only)
1310 Dbx files are created by Outlook Express. Using the external
1311 (optional) Mail::Transport::Dbx module, you can read these folders,
1312 even when you are running MailBox on a UNIX/Linux platform.
1313 Writing and deleting messages is not supported by the library, and
1315 therefore not by MailBox. Read access is enough to do folder con‐
1316 versions, for instance.
1317 * Mail::Box::IMAP4 (partially)
1319 The IMAP protocol is very complex. Some parts are implemented to
1320 create (sub-optimal but usable) IMAP clients. Besides, there are
1321 also some parts for IMAP servers present. The most important lack‐
1322 ing feature is support for encrypted connections.
1323 * Mail::Box::Maildir
1325 Maildir folders have a directory for each folder. A folder direc‐
1326 tory contains "tmp", "new", and "cur" sub-directories, each con‐
1327 tainting messages with a different purpose. Files with new mes‐
1328 sages are created in "tmp", then moved to "new" (ready to be
1329 accepted). Later, they are moved to the "cur" directory
1330 (accepted). Each message is one file with a name starting with
1331 timestamp. The name also contains flags about the status of the
1332 message.
1333 Maildir folders can not be used on Windows by reason of file-name
1335 limitations on that platform.
1336 * Mail::Box::Mbox
1338 A folder type in which all related messages are stored in one file.
1339 This is a very common folder type for UNIX.
1340 * Mail::Box::MH
1342 This folder creates a directory for each folder, and a message is
1343 one file inside that directory. The message files are numbered
1344 sequentially on order of arrival. A special ".mh_sequences" file
1345 maintains flags about the messages.
1346 * Mail::Box::POP3 (read/delete only)
1348 POP3 is a protocol which can be used to retreive messages from a
1349 remote system. After the connection to a POP server is made, the
1350 messages can be looked at and removed as if they are on the local
1351 system.
1352 * Mail::Box::Netzwert
1354 The Netzwert folder type is optimized for mailbox handling on a
1355 cluster of systems with a shared NFS storage. The code is not
1356 released under GPL (yet)
1357 Other folder types are on the (long) wishlist to get implemented.
1359 Please, help implementing more of them.
1360 Folder class implementation
1362 The class structure of folders is very close to that of messages. For
1364 instance, a Mail::Box::File::Message relates to a Mail::Box::File
1365 folder. The folder types are:
1366 Mail::Box::Netzwert
1368 Mail::Box::Mbox ⎪ Mail::Box::Maildir Mail::Box::POP3
1369 ⎪ Mail::Box::Dbx ⎪ ⎪ Mail::Box::MH ⎪ Mail::Box::IMAP4
1370 ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪
1371 ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪
1372 Mail::Box::File Mail::Box::Dir Mail::Box::Net
1373 ⎪ ⎪ ⎪
1374 `--------------. ⎪ .---------------'
1375 ⎪ ⎪ ⎪
1376 Mail::Box
1377 ⎪
1378 ⎪
1379 Mail::Reporter (general base class)
1380 By far most folder features are implemented in Mail::Box, so available
1382 to all folder types. Sometimes, features which appear in only some of
1383 the folder types are simulated for folders that miss them, like sub-
1384 folder support for MBOX.
1385
1387 Warning: Changes not written to read-only folder $self.
1388 You have opened the folder read-only --which is the default set by
1390 new(access)--, made modifications, and now want to close it. Set
1391 close(force) if you want to overrule the access mode, or close the
1392 folder with close(write) set to "NEVER".
1393 Error: Copying failed for one message.
1395 For some reason, for instance disc full, removed by external process,
1397 or read-protection, it is impossible to copy one of the messages.
1398 Copying will proceed for the other messages.
1399 Error: Destination folder $name is not writable.
1401 The folder where the messages are copied to is not opened with write
1403 access (see new(access)). This has no relation with write permission
1404 to the folder which is controled by your operating system.
1405 Warning: Different messages with id $msgid
1407 The message id is discovered more than once within the same folder, but
1409 the content of the message seems to be different. This should not be
1410 possible: each message must be unique.
1411 Error: Folder $name is opened read-only
1413 You can not write to this folder unless you have opened the folder to
1415 write or append with new(access), or the "force" option is set true.
1416 Error: Folder $name not deleted: not writable.
1418 The folder must be opened with write access via new(access), otherwise
1420 removing it will be refused. So, you may have write-access according
1421 to the operating system, but that will not automatically mean that this
1422 "delete" method permits you to. The reverse remark is valid as well.
1423 Error: Invalid timespan '$timespan' specified.
1425 The string does not follow the strict rules of the time span syntax
1427 which is permitted as parameter.
1428 Warning: Message-id '$msgid' does not contain a domain.
1430 According to the RFCs, message-ids need to contain a unique random
1432 part, then an "@", and then a domain name. This is made to avoid the
1433 creation of two messages with the same id. The warning emerges when
1434 the "@" is missing from the string.
1435 Error: No folder name specified.
1437 You did not specify the name of a folder to be opened. Use the
1439 new(folder) option or set the "MAIL" environment variable.
1440 Error: Package $package does not implement $method.
1442 Fatal error: the specific package (or one of its superclasses) does not
1444 implement this method where it should. This message means that some
1445 other related classes do implement this method however the class at
1446 hand does not. Probably you should investigate this and probably
1447 inform the author of the package.
1448 Error: Unable to create subfolder $name of $folder.
1450 The copy includes the subfolders, but for some reason it was not possi‐
1452 ble to copy one of these. Copying will proceed for all other sub-fold‐
1453 ers.
1454 Error: Writing folder $name failed
1456 For some reason (you probably got more error messages about this prob‐
1458 lem) it is impossible to write the folder, although you should because
1459 there were changes made.
1460
1462 This module is part of Mail-Box distribution version 2.070, built on
1463 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
1464
1466 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
1467 ChangeLog.
1468 This program is free software; you can redistribute it and/or modify it
1470 under the same terms as Perl itself. See
1471 http://www.perl.com/perl/misc/Artistic.html
1472perl v5.8.8 2007-03-25 Mail::Box(3)