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 within 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 Extends "DESCRIPTION" in Mail::Reporter.
70
72 overload: ""
73 (stringification) The folder objects stringify to their name. This
74 simplifies especially print statements and sorting a lot.
75 example: use overloaded folder as string
77 # Three lines with overloading: resp. cmp, @{}, and ""
79 foreach my $folder (sort @folders)
80 { my $msgcount = @$folder;
81 print "$folder contains $msgcount messages\n";
82 }
83 overload: @{}
85 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
98 sort rules are those of the build-in "cmp".
99
101 Extends "METHODS" in Mail::Reporter.
102 Constructors
104 Extends "Constructors" in Mail::Reporter.
105 Mail::Box->new(%options)
107 Open a new folder. A list of labeled %options for the mailbox can
108 be supplied. Some options pertain to Mail::Box, and others are
109 added by sub-classes.
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 <folder-class>::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
145 (which means write-protected) by default! MODE can be
146 'r': read-only (default)
148 'a': append
149 'rw': read-write
150 'd': delete
151 These MODE has no relation to the modes actually used to open the
153 folder files within this module. For instance, if you specify
154 "rw", and open the folder, only read permission on the folder-
155 file is required.
156 Be warned: writing a MBOX folder may create a new file to replace
158 the old folder. The permissions and owner of the file may get
159 changed by this.
160 body_delayed_type => CLASS
162 The bodies which are delayed: which will be read from file when
163 it is needed, but not before.
164 body_type => CLASS|CODE
166 When messages are read from a folder-file, the headers will be
167 stored in a "head_type" object. For the body, however, there is
168 a range of choices about type, which are all described in
169 Mail::Message::Body.
170 Specify a CODE-reference which produces the body-type to be
172 created, or a CLASS of the body which is used when the body is
173 not a multipart or nested. In case of a code reference, the
174 header structure is passed as first argument to the routine.
175 Do not return a delayed body-type (like "::Delayed"), because
177 that is determined by the "extract" option while the folder is
178 opened. Even delayed message will require some real body type
179 when they get parsed eventually. Multiparts and nested messages
180 are also outside your control.
181 For instance:
183 $mgr->open('InBox', body_type => \&which_body);
185 sub which_body($) {
187 my $head = shift;
188 my $size = $head->guessBodySize || 0;
189 my $type = $size > 100000 ? 'File' : 'Lines';
190 "Mail::Message::Body::$type";
191 }
192 The default depends on the mail-folder type, although the general
194 default is Mail::Message::Body::Lines. Please check the
195 applicable manual pages.
196 coerce_options => ARRAY
198 Keep configuration information for messages which are coerced
199 into the specified folder type, starting with a different folder
200 type (or even no folder at all). Messages which are coerced are
201 always fully read, so this kind of information does not need to
202 be kept here.
203 create => BOOLEAN
205 Automatically create the folder when it does not exist yet. This
206 will only work when access is granted for writing or appending to
207 the folder.
208 Be careful: you may create a different folder type than you
210 expect unless you explicitly specify
211 Mail::Box::Manager::open(type).
212 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
214 Defines when to parse (process) the content of the message. When
215 the header of a message is read, you may want to postpone the
216 reading of the body: header information is more often needed than
217 the body data, so why parse it always together? The cost of
218 delaying is not too high, and with some luck you may never need
219 parsing the body.
220 If you supply an INTEGER to this option, bodies of those messages
222 with a total size less than that number will be extracted from
223 the folder only when necessary. Messages where the size (in the
224 "Content-Length" field) is not included in the header, like often
225 the case for multiparts and nested messages, will not be
226 extracted by default.
227 If you supply a CODE reference, that subroutine is called every
229 time that the extraction mechanism wants to determine whether to
230 parse the body or not. The subroutine is called with the
231 following arguments:
232 CODE->(FOLDER, HEAD)
234 where FOLDER is a reference to the folder we are reading. HEAD
236 refers to the Mail::Message::Head::Complete head of the message
237 at hand. The routine must return a "true" value (extract now) or
238 a "false" value (be lazy, do not parse yet). Think about using
239 the Mail::Message::Head::guessBodySize() and
240 Mail::Message::guessTimestamp() on the header to determine your
241 choice.
242 The third possibility is to specify the NAME of a method. In
244 that case, for each message is called:
245 FOLDER->NAME(HEAD)
247 Where each component has the same meaning as described above.
249 The fourth way to use this option involves constants: with "LAZY"
251 all messages will be delayed. With "ALWAYS" you enforce
252 unconditional parsing, no delaying will take place. The latter
253 is usuful when you are sure you always need all the messages in
254 the folder.
255 $folder->new(extract => 'LAZY'); # Very lazy
257 $folder->new(extract => 10000); # Less than 10kB
258 # same, but implemented yourself
260 $folder->new(extract => &large);
261 sub large($) {
262 my ($f, $head) = @_;
263 my $size = $head->guessBodySize;
264 defined $size ? $size < 10000 : 1
265 };
266 # method call by name, useful for Mail::Box
268 # extensions. The example selects all messages
269 # sent by you to be loaded without delay.
270 # Other messages will be delayed.
271 $folder->new(extract => 'sent_by_me');
272 sub Mail::Box::send_by_me($) {
273 my ($self, $header) = @_;
274 $header->get('from') =~ m/\bmy\@example.com\b/i;
275 }
276 field_type => CLASS
278 The type of the fields to be used in a header. Must extend
279 Mail::Message::Field.
280 fix_headers => BOOLEAN
282 Broken MIME headers usually stop the parser: all lines not parsed
283 are added to the body of the message. With this flag set, the
284 erroneous line is added to the previous header field and parsing
285 is continued. See
286 Mail::Box::Parser::Perl::new(fix_header_errors).
287 folder => FOLDERNAME
289 Which folder to open (for reading or writing). When used for
290 reading (the "access" option set to "r" or "a") the mailbox
291 should already exist and must be readable. The file or directory
292 of the mailbox need not exist if it is opened for reading and
293 writing ("rw"). Write-permission is checked when opening an
294 existing mailbox.
295 The folder name can be preceded by a "=", to indicate that it is
297 named relative to the directory specified in new(folderdir).
298 Otherwise, it is taken as relative or absolute path.
299 folderdir => DIRECTORY
301 Where are folders to be found by default? A folder-name may be
302 preceded by a equals-sign ("=", a "mutt" convension) to
303 explicitly state that the folder is located below the default
304 directory. For example: in case "folderdir => '/tmp'" and
305 "folder => '=abc'", the name of the folder-file is '/tmp/abc'.
306 Each folder type has already some default set.
307 head_delayed_type => CLASS
309 The headers which are delayed: which will be read from file when
310 it is needed, but not before.
311 head_type => CLASS
313 The type of header which contains all header information. Must
314 extend Mail::Message::Head::Complete.
315 keep_dups => BOOLEAN
317 Indicates whether or not duplicate messages within the folder
318 should be retained. A message is considered to be a duplicate if
319 its message-id is the same as a previously parsed message within
320 the same folder. If this option is false (the default) such
321 messages are automatically deleted, because it is considered
322 useless to store the same message twice.
323 lock_file => FILENAME
325 The name of the file which is used to lock. This must be
326 specified when locking is to be used.
327 lock_timeout => SECONDS
329 When the lock file is older than the specified number of SECONDS,
330 it is considered a mistake. The original lock is released, and
331 accepted for this folder.
332 lock_type => CLASS|STRING|ARRAY
334 The type of the locker object. This may be the full name of a
335 CLASS which extends Mail::Box::Locker, or one of the known locker
336 types "DotLock", "Flock", "FcntlLock", "Mutt", "NFS", "POSIX", or
337 "NONE". If an ARRAY is specified, then a Multi locker is built
338 which uses the specified list.
339 lock_wait => SECONDS
341 SECONDS to wait before failing on opening this folder.
342 locker => OBJECT
344 An OBJECT which extends Mail::Box::Locker, and will handle folder
345 locking replacing the default lock behavior.
346 log => LEVEL
348 manager => MANAGER
349 A reference to the object which manages this folder -- typically
350 an Mail::Box::Manager instance.
351 message_type => CLASS
353 What kind of message objects are stored in this type of folder.
354 The default is constructed from the folder class followed by
355 "::Message". For instance, the message type for
356 "Mail::Box::POP3" is "Mail::Box::POP3::Message"
357 multipart_type => CLASS
359 The default type of objects which are to be created for multipart
360 message bodies.
361 remove_when_empty => BOOLEAN
363 Determines whether to remove the folder file or directory
364 automatically when the write would result in a folder without
365 messages nor sub-folders.
366 save_on_exit => BOOLEAN
368 Sets the policy for saving the folder when it is closed. A
369 folder can be closed manually (see close()) or in a number of
370 implicit ways, including on the moment the program is terminated.
371 trace => LEVEL
373 trusted => BOOLEAN
374 Flags whether to trust the data in the folder or not. Folders
375 which reside in your "folderdir" will be trusted by default (even
376 when the names if not specified staring with "="). Folders which
377 are outside the folderdir or read from STDIN
378 (Mail::Message::Construct::read()) are not trused by default, and
379 require some extra checking.
380 If you do not check encodings of received messages, you may print
382 binary data to the screen, which is a security risk.
383 The folder
385 $obj->addMessage($message, %options)
386 Add a message to the folder. A message is usually a
387 Mail::Box::Message object or a sub-class thereof. The message
388 shall not be in an other folder, when you use this method. In case
389 it is, use Mail::Box::Manager::moveMessage() or
390 Mail::Box::Manager::copyMessage() via the manager.
391 Messages with id's which already exist in this folder are not
393 added.
394 BE WARNED that message labels may get lost when a message is moved
396 from one folder type to an other. An attempt is made to translate
397 labels, but there are many differences in interpretation by
398 applications.
399 -Option--Default
401 share <not used>
402 share => BOOLEAN
404 Try to share the physical resource of the current message with
405 the indicated message. It is sometimes possible to share
406 messages between different folder types. When the sharing is not
407 possible, than this option is simply ignored.
408 Sharing the resource is quite dangerous, and only available for a
410 limited number of folder types, at the moment only some
411 Mail::Box::Dir folders; these file-based messages can be
412 hardlinked (on platforms that support it). The link may get
413 broken when one message is modified in one of the folders.... but
414 maybe not, depending on the folder types involved.
415 example:
417 $folder->addMessage($msg);
419 $folder->addMessages($msg1, $msg2, ...);
420 $obj->addMessages(@messages)
422 Adds a set of message objects to the open folder at once. For some
423 folder types this may be faster than adding them one at a time.
424 example:
426 $folder->addMessages($msg1, $msg2, ...);
428 Mail::Box->appendMessages(%options)
430 Append one or more messages to an unopened folder. Usually, this
431 method is called by the Mail::Box::Manager::appendMessage(), in
432 which case the correctness of the folder type is checked.
433 For some folder types it is required to open the folder before it
435 can be used for appending. This can be fast, but this can also be
436 very slow (depends on the implementation). All %options passed
437 will also be used to open the folder, if needed.
438 -Option --Default
440 folder <required>
441 message undef
442 messages undef
443 share <false>
444 folder => FOLDERNAME
446 The name of the folder to which the messages are to be appended.
447 The folder implementation will avoid opening the folder when
448 possible, because this is resource consuming.
449 message => MESSAGE
451 messages => ARRAY-OF-MESSAGES
452 One reference to a MESSAGE or a reference to an ARRAY of
453 MESSAGEs, which may be of any type. The messages will be first
454 coerced into the correct message type to fit in the folder, and
455 then will be added to it.
456 share => BOOLEAN
458 Try to share physical storage of the message. Only available for
459 a limited number of folder types, otherwise no-op.
460 example:
462 my $message = Mail::Message->new(...);
464 Mail::Box::Mbox->appendMessages
465 ( folder => '=xyz'
466 , message => $message
467 , folderdir => $ENV{FOLDERS}
468 );
469 better:
471 my Mail::Box::Manager $mgr;
473 $mgr->appendMessages($message, folder => '=xyz');
474 $obj->close(%options)
476 Close the folder, which usually implies writing the changes. This
477 will return "false" when writing is required but fails. Please do
478 check this result.
479 WARNING: When moving messages from one folder to another, be sure
481 to write the destination folder before writing and closing the
482 source folder. Otherwise you may lose data if the system crashes
483 or if there are software problems.
484 -Option --Default
486 force <false>
487 save_deleted false
488 write MODIFIED
489 force => BOOLEAN
491 Override the new(access) setting which was specified when the
492 folder was opened. This option only has an effect if its value is
493 TRUE. NOTE: Writing to the folder may not be permitted by the
494 operating system, in which case even "force" will not help.
495 save_deleted => BOOLEAN
497 Do also write messages which where flagged to be deleted to their
498 folder. The flag for deletion is conserved (when possible),
499 which means that a re-open of the folder may remove the messages
500 for real. See write(save_deleted).
501 write => 'ALWAYS'|'NEVER'|'MODIFIED'
503 Specifies whether the folder should be written. As could be
504 expected, "ALWAYS" means always (even if there are no changes),
505 "NEVER" means that changes to the folder will be lost, and
506 "MODIFIED" only saves the folder if there are any changes.
507 example:
509 my $f = $mgr->open('spam', access => 'rw')
511 or die "Cannot open spam: $!\n";
512 $f->message(0)->delete
514 if $f->messages;
515 $f->close
517 or die "Couldn't write $f: $!\n";
518 $obj->copyTo($folder, %options)
520 Copy the folder's messages to a new folder. The new folder may be
521 of a different type.
522 -Option --Default
524 delete_copied <false>
525 select 'ACTIVE'
526 share <not used>
527 subfolders <folder type dependent>
528 delete_copied => BOOLEAN
530 Flag the messages from the source folder to be deleted, just
531 after it was copied. The deletion will only take effect when the
532 originating folder is closed.
533 select => 'ACTIVE'|'DELETED'|'ALL'|LABEL|!LABEL|FILTER
535 Which messages are to be copied. See the description of
536 messages() about how this works.
537 share => BOOLEAN
539 Try to share the message between the folders. Some
540 Mail::Box::Dir folder types do support it by creating a hardlink
541 (on UNIX/Linux).
542 subfolders => BOOLEAN|'FLATTEN'|'RECURSE'
544 How to handle sub-folders. When false (0 or "undef"), sub-
545 folders are simply ignored. With "FLATTEN", messages from sub-
546 folders are included in the main copy. "RECURSE" recursively
547 copies the sub-folders as well. By default, when the destination
548 folder supports sub-folders "RECURSE" is used, otherwise
549 "FLATTEN". A value of true will select the default.
550 example:
552 my $mgr = Mail::Box::Manager->new;
554 my $imap = $mgr->open(type => 'imap', host => ...);
555 my $mh = $mgr->open(type => 'mh', folder => '/tmp/mh',
556 create => 1, access => 'w');
557 $imap->copyTo($mh, delete_copied => 1);
559 $mh->close; $imap->close;
560 $obj->delete(%options)
562 Remove the specified folder file or folder directory (depending on
563 the type of folder) from disk. Of course, THIS IS DANGEROUS: you
564 "may" lose data. Returns a "true" value on success.
565 WARNING: When moving messages from one folder to another, be sure
567 to write the destination folder before deleting the source folder.
568 Otherwise you may lose data if the system crashes or if there are
569 software problems.
570 -Option --Default
572 recursive 1
573 recursive => BOOLEAN
575 example: removing an open folder
577 my $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw');
579 ... some other code ...
580 $folder->delete;
581 example: removing an closed folder
583 my $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd');
585 $folder->delete;
586 $obj->folderdir( [$directory] )
588 Get or set the $directory which is used to store mail-folders by
589 default.
590 example:
592 print $folder->folderdir;
594 $folder->folderdir("$ENV{HOME}/nsmail");
595 $obj->name()
597 Returns the name of the folder. What the name represents depends
598 on the actual type of mailbox used.
599 example:
601 print $folder->name;
603 print "$folder"; # overloaded stringification
604 $obj->organization()
606 Returns how the folder is organized: as one "FILE" with many
607 messages, a "DIRECTORY" with one message per file, or by a "REMOTE"
608 server.
609 $obj->size()
611 Returns the size of the folder in bytes, not counting in the
612 deleted messages. The error in the presented result may be as
613 large as 10%, because the in-memory representation of messages is
614 not always the same as the size when they are written.
615 $obj->type()
617 Returns a name for the type of mail box. This can be "mbox", "mh",
618 "maildir", or "pop3".
619 $obj->update(%options)
621 Read new messages from the folder, which where received after
622 opening it. This is quite dangerous and shouldn't be possible:
623 folders which are open are locked. However, some applications do
624 not use locks or the wrong kind of locks. This method reads the
625 changes (not always failsafe) and incorporates them in the open
626 folder administration.
627 The %options are extra values which are passed to the
629 updateMessages() method which is doing the actual work here.
630 $obj->url()
632 Represent the folder as a URL (Universal Resource Locator) string.
633 You may pass such a URL as folder name to
634 Mail::Box::Manager::open().
635 example:
637 print $folder->url;
639 # may result in
640 # mbox:/var/mail/markov or
641 # pop3://user:password@pop.aol.com:101
642 Folder flags
644 $obj->access()
645 Returns the access mode of the folder, as set by new(access)
646 $obj->isModified()
648 Checks if the folder, as stored in memory, is modified. A true
649 value is returned when any of the messages is to be deleted, has
650 changed, or messages were added after the folder was read from
651 file.
652 WARNING: this flag is not related to an external change to the
654 folder structure on disk. Have a look at update() for that.
655 $obj->modified( [BOOLEAN] )
657 Sets whether the folder is modified or not.
658 $obj->writable()
660 Checks whether the current folder is writable.
661 example:
663 $folder->addMessage($msg) if $folder->writable;
665 The messages
667 $obj->current( [$number|$message|$message_id] )
668 Some mail-readers keep the current message, which represents the
669 last used message. This method returns [after setting] the current
670 message. You may specify a $number, to specify that that message
671 number is to be selected as current, or a $message/$message_id (as
672 long as you are sure that the header is already loaded, otherwise
673 they are not recognized).
674 example:
676 $folder->current(0);
678 $folder->current($message);
679 $obj->find($message_id)
681 Like messageId(), this method searches for a message with the
682 $message_id, returning the corresponding message object. However,
683 "find" will cause unparsed message in the folder to be parsed until
684 the message-id is found. The folder will be scanned back to front.
685 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
687 Find the first message which has this $label with the correct
688 setting. The BOOLEAN indicates whether any true value or any false
689 value is to be found in the ARRAY of $msgs. By default, a true
690 value is searched for. When a message does not have the requested
691 label, it is taken as false.
692 example: looking for a labeled message
694 my $current = $folder->findFirstLabeled('current');
696 my $first = $folder->findFirstLabeled(seen => 0);
698 my $last = $folder->findFirstLabeled(seen => 0,
700 [ reverse $self->messages('ACTIVE') ] )
701 $obj->message( $index, [$message] )
703 Get or set a message with on a certain index. Messages which are
704 flagged for deletion are counted. Negative indexes start at the
705 end of the folder.
706 example:
708 my $msg = $folder->message(3);
710 $folder->message(3)->delete; # status changes to `deleted'
711 $folder->message(3, $msg);
712 print $folder->message(-1); # last message.
713 $obj->messageId( $message_id, [$message] )
715 With one argument, returns the message in the folder with the
716 specified $message_id. If a reference to a message object is passed
717 as the optional second argument, the message is first stored in the
718 folder, replacing any existing message whose message ID is
719 $message_id. (The message ID of $message need not match
720 $message_id.)
721 !!WARNING!!: when the message headers are delay-parsed, the message
723 might be in the folder but not yet parsed into memory. In this
724 case, use find() instead of messageId() if you really need a
725 thorough search. This is especially the case for directory
726 organized folders without special indexi, like Mail::Box::MH.
727 The $message_id may still be in angles, which will be stripped. In
729 that case blanks (which origin from header line folding) are
730 removed too. Other info around the angles will be removed too.
731 example:
733 my $msg = $folder->messageId('<complex-message.id>');
735 $folder->messageId("<complex-message\n.id>", $msg);
736 my $msg = $folder->messageId('complex-message.id');
737 my $msg = $folder->messageId('garbage <complex-message.id> trash');
738 $obj->messageIds()
740 Returns a list of all message-ids in the folder, including those of
741 messages which are to be deleted.
742 For some folder-types (like MH), this method may cause all message-
744 files to be read. See their respective manual pages.
745 example:
747 foreach my $id ($folder->messageIds) {
749 $folder->messageId($id)->print;
750 }
751 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
753 !$label|$filter> )
754 Returns multiple messages from the folder. The default is "ALL"
755 which will return (as expected maybe) all the messages in the
756 folder. The "ACTIVE" flag will return the messages not flagged for
757 deletion. This is the opposite of "DELETED", which returns all
758 messages from the folder which will be deleted when the folder is
759 closed.
760 You may also specify a $range: two numbers specifying begin and end
762 index in the array of messages. Negative indexes count from the
763 end of the folder. When an index is out-of-range, the returned
764 list will be shorter without complaints.
765 Everything else than the predefined names is seen as labels. The
767 messages which have that label set will be returned. When the
768 sequence starts with an exclamation mark (!), the search result is
769 reversed.
770 For more complex searches, you can specify a $filter, which is
772 simply a code reference. The message is passed as only argument.
773 example:
775 foreach my $message ($folder->messages) {...}
777 foreach my $message (@$folder) {...}
778 # twice the same
780 my @messages = $folder->messages;
781 my @messages = $folder->messages('ALL');
782 # Selection based on a range (begin, end)
784 my $subset = $folder->messages(10,-8);
785 # twice the same:
787 my @not_deleted= grep {not $_->isDeleted}
788 $folder->messages;
789 my @not_deleted= $folder->messages('ACTIVE');
790 # scalar context the number of messages
792 my $nr_of_msgs = $folder->messages;
793 # third message, via overloading
795 $folder->[2];
796 # Selection based on labels
798 $mgr->moveMessages($spam, $inbox->message('spam'));
799 $mgr->moveMessages($archive, $inbox->message('seen'));
800 $obj->nrMessages(%options)
802 Simply calls messages() in scalar context to return a count instead
803 of the messages itself. Some people seem to understand this
804 better. Note that nrMessages() will default to returning a count
805 of "ALL" messages in the folder, including both "ACTIVE" and
806 "DELETED".
807 The %options are passed to (and explained in) messages().
809 $obj->scanForMessages($message, $message_ids, $timespan, $window)
811 You start with a $message, and are looking for a set of messages
812 which are related to it. For instance, messages which appear in
813 the 'In-Reply-To' and 'Reference' header fields of that message.
814 These messages are known by their $message_ids and you want to find
815 them in the folder.
816 When all message-ids are known, then looking-up messages is simple:
818 they are found in a plain hash using messageId(). But Mail::Box is
819 lazy where it can, so many messages may not have been read from
820 file yet, and that's the preferred situation, because that saves
821 time and memory.
822 It is not smart to search for the messages from front to back in
824 the folder: the chances are much higher that related message reside
825 closely to each other. Therefore, this method starts scanning the
826 folder from the specified $message, back to the front of the
827 folder.
828 The $timespan can be used to terminate the search based on the time
830 enclosed in the message. When the constant string "EVER" is used
831 as $timespan, then the search is not limited by that. When an
832 integer is specified, it will be used as absolute time in time-
833 ticks as provided by your platform dependent "time" function. In
834 other cases, it is passed to timespan2seconds() to determine the
835 threshold as time relative to the message's time.
836 The $window is used to limit the search in number of messages to be
838 scanned as integer or constant string "ALL".
839 Returned are the message-ids which were not found during the scan.
841 Be warned that a message-id could already be known and therefore
842 not found: check that first.
843 example: scanning through a folder for a message
845 my $refs = $msg->get('References') or return;
847 my @msgids = $ref =~ m/\<([^>]+\>/g;
848 my @failed = $folder->scanForMessages($msg, \@msgids, '3 days', 50);
849 Sub-folders
851 $obj->listSubFolders(%options)
852 Mail::Box->listSubFolders(%options)
853 List the names of all sub-folders to this folder, not recursively
854 decending. Use these names as argument to openSubFolder(), to get
855 access to that folder.
856 For MBOX folders, sub-folders are simulated.
858 -Option --Default
860 check <false>
861 folder <from calling object>
862 folderdir <from folder>
863 skip_empty <false>
864 check => BOOLEAN
866 Should all returned foldernames be checked to be sure that they
867 are of the right type? Each sub-folder may need to be opened to
868 check this, with a folder type dependent penalty (in some cases
869 very expensive).
870 folder => FOLDERNAME
872 The folder whose sub-folders should be listed.
873 folderdir => DIRECTORY
875 skip_empty => BOOL
876 Shall empty folders (folders which currently do not contain any
877 messages) be included? Empty folders are not useful to open, but
878 may be useful to save to.
879 example:
881 my $folder = $mgr->open('=in/new');
883 my @subs = $folder->listSubFolders;
884 my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');
886 my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.
887 $obj->nameOfSubFolder( $subname, [$parentname] )
889 Mail::Box->nameOfSubFolder( $subname, [$parentname] )
890 Returns the constructed name of the folder with NAME, which is a
891 sub-folder of this current one. You have either to call this
892 method as instance method, or specify a $parentname.
893 example: how to get the name of a subfolder
895 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc');
897 print $sub; # abc/xyz
898 my $f = Mail::Box::Mbox->new(folder => 'abc');
900 print $f->nameOfSubfolder('xyz'); # abc/xyz
901 my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef);
903 print $sub; # xyz
904 $obj->openRelatedFolder(%options)
906 Open a folder (usually a sub-folder) with the same options as this
907 one. If there is a folder manager in use, it will be informed
908 about this new folder. %options overrule the options which where
909 used for the folder this method is called upon.
910 $obj->openSubFolder($subname, %options)
912 Open (or create, if it does not exist yet) a new subfolder in an
913 existing folder.
914 example:
916 my $folder = Mail::Box::Mbox->new(folder => '=Inbox');
918 my $sub = $folder->openSubFolder('read');
919 $obj->topFolderWithMessages()
921 Mail::Box->topFolderWithMessages()
922 Some folder types can have messages in the top-level folder, some
923 other can't.
924 Internals
926 $obj->coerce($message, %options)
927 Coerce the $message to be of the correct type to be placed in the
928 folder. You can specify Mail::Internet and MIME::Entity objects
929 here: they will be translated into Mail::Message messages first.
930 $obj->create($foldername, %options)
932 Mail::Box->create($foldername, %options)
933 Create a folder. If the folder already exists, it will be left
934 unchanged. The folder is created, but not opened! If you want to
935 open a file which may need to be created, then use
936 Mail::Box::Manager::open() with the create flag, or
937 Mail::Box::new(create).
938 -Option --Default
940 folderdir undef
941 folderdir => DIRECTORY
943 When the foldername is preceded by a "=", the "folderdir"
944 directory will be searched for the named folder.
945 $obj->determineBodyType($message, $head)
947 Determine which kind of body will be created for this message when
948 reading the folder initially.
949 Mail::Box->foundIn( [$foldername], %options )
951 Determine if the specified folder is of the type handled by the
952 folder class. This method is extended by each folder sub-type.
953 The $foldername specifies the name of the folder, as is specified
955 by the application. You need to specified the "folder" option when
956 you skip this first argument.
957 %options is a list of extra information for the request. Read the
959 documentation for each type of folder for type specific options,
960 but each folder class will at least support the "folderdir" option:
961 -Option --Default
963 folderdir undef
964 folderdir => DIRECTORY
966 The location where the folders of this class are stored by
967 default. If the user specifies a name starting with a "=", that
968 indicates that the folder is to be found in this default
969 DIRECTORY.
970 example:
972 Mail::Box::Mbox->foundIn('=markov',
974 folderdir => "$ENV{HOME}/Mail");
975 Mail::Box::MH->foundIn(folder => '=markov');
976 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
978 Returns the character or characters used to separate lines in the
979 folder file, optionally after setting it to STRING, or one of the
980 constants. The first line of the folder sets the default.
981 UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF.
983 Each separator will be represented by a "\n" within your program.
984 However, when processing platform foreign folders, complications
985 appear. Think about the "Size" field in the header.
986 When the separator is changed, the whole folder me be rewritten.
988 Although, that may not be required.
989 $obj->locker()
991 Returns the locking object.
992 $obj->read(%options)
994 Read messages from the folder into memory. The %options are folder
995 specific. Do not call read() yourself: it will be called for you
996 when you open the folder via the manager or instantiate a folder
997 object directly.
998 NOTE: if you are copying messages from one folder to another, use
1000 addMessages() instead of read().
1001 example:
1003 my $mgr = Mail::Box::Manager->new;
1005 my $folder = $mgr->open('InBox'); # implies read
1006 my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same
1007 $obj->readMessages(%options)
1009 Called by read() to actually read the messages from one specific
1010 folder type. The read() organizes the general activities.
1011 The %options are "trusted", "head_type", "field_type",
1013 "message_type", "body_delayed_type", and "head_delayed_type" as
1014 defined by the folder at hand. The defaults are the constructor
1015 defaults (see new()).
1016 $obj->storeMessage($message)
1018 Store the message in the folder without the checks as performed by
1019 addMessage().
1020 $obj->toBeThreaded($messages)
1022 The specified message is ready to be removed from 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->toBeUnthreaded($messages)
1027 The specified message is ready to be included in a thread. This
1028 will be passed on to the mail-manager, which keeps an overview on
1029 which thread-detection objects are floating around.
1030 $obj->updateMessages(%options)
1032 Called by update() to read messages which arrived in the folder
1033 after it was opened. Sometimes, external applications dump
1034 messages in a folder without locking (or using a different lock
1035 than your application does).
1036 Although this is quite a dangerous, it only fails when a folder is
1038 updated (reordered or message removed) at exactly the same time as
1039 new messages arrive. These collisions are sparse.
1040 The options are the same as for readMessages().
1042 $obj->write(%options)
1044 Write the data to disk. The folder (a "true" value) is returned if
1045 successful. Deleted messages are transformed into destroyed
1046 messages: their memory is freed.
1047 WARNING: When moving messages from one folder to another, be sure
1049 to write (or close()) the destination folder before writing (or
1050 closing) the source folder: otherwise you may lose data if the
1051 system crashes or if there are software problems.
1052 To write a folder to a different file, you must first create a new
1054 folder, then move all the messages, and then write or close() that
1055 new folder.
1056 -Option --Default
1058 force <false>
1059 save_deleted <false>
1060 force => BOOLEAN
1062 Override write-protection with new(access) while opening the
1063 folder (whenever possible, it may still be blocked by the
1064 operating system).
1065 save_deleted => BOOLEAN
1067 Do also write messages which where flagged to be deleted to their
1068 folder. The flag for deletion is conserved (when possible),
1069 which means that a re-open of the folder may remove the messages
1070 for real. See close(save_deleted).
1071 $obj->writeMessages(%options)
1073 Called by write() to actually write the messages from one specific
1074 folder type. The "write" organizes the general activities. All
1075 options to write() are passed to "writeMessages" as well. Besides,
1076 a few extra are added by "write" itself.
1077 -Option --Default
1079 messages <required>
1080 messages => ARRAY
1082 The messages to be written, which is a sub-set of all messages in
1083 the current folder.
1084 Other methods
1086 $obj->timespan2seconds($time)
1087 Mail::Box->timespan2seconds($time)
1088 $time is a string, which starts with a float, and then one of the
1089 words 'hour', 'hours', 'day', 'days', 'week', or 'weeks'. For
1090 instance: '1 hour' or '4 weeks'.
1091 Error handling
1093 Extends "Error handling" in Mail::Reporter.
1094 $obj->AUTOLOAD()
1096 Inherited, see "Error handling" in Mail::Reporter
1097 $obj->addReport($object)
1099 Inherited, see "Error handling" in Mail::Reporter
1100 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
1102 $callback] )
1103 Mail::Box->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
1104 $callback] )
1105 Inherited, see "Error handling" in Mail::Reporter
1106 $obj->errors()
1108 Inherited, see "Error handling" in Mail::Reporter
1109 $obj->log( [$level, [$strings]] )
1111 Mail::Box->log( [$level, [$strings]] )
1112 Inherited, see "Error handling" in Mail::Reporter
1113 $obj->logPriority($level)
1115 Mail::Box->logPriority($level)
1116 Inherited, see "Error handling" in Mail::Reporter
1117 $obj->logSettings()
1119 Inherited, see "Error handling" in Mail::Reporter
1120 $obj->notImplemented()
1122 Inherited, see "Error handling" in Mail::Reporter
1123 $obj->report( [$level] )
1125 Inherited, see "Error handling" in Mail::Reporter
1126 $obj->reportAll( [$level] )
1128 Inherited, see "Error handling" in Mail::Reporter
1129 $obj->trace( [$level] )
1131 Inherited, see "Error handling" in Mail::Reporter
1132 $obj->warnings()
1134 Inherited, see "Error handling" in Mail::Reporter
1135 Cleanup
1137 Extends "Cleanup" in Mail::Reporter.
1138 $obj->DESTROY()
1140 This method is called by Perl when an folder-object is no longer
1141 accessible by the rest of the program.
1142
1144 Different kinds of folders
1145 In general, there are three classes of folders: those who group
1146 messages per file, those who group messages in a directory, and those
1147 do not provide direct access to the message data. These folder types
1148 are each based on a different base class.
1149 • File based folders Mail::Box::File
1151 File based folders maintain a folder (a set of messages) in one
1153 single file. The advantage is that your folder has only one single
1154 file to access, which speeds-up things when all messages must be
1155 accessed at once.
1156 One of the main disadvantages over directory based folders is that
1158 you have to construct some means to keep all message apart. For
1159 instance MBOX adds a message separator line between the messages in
1160 the file, and this line can cause confusion with the message's
1161 contents.
1162 Where access to all messages at once is faster in file based
1164 folders, access to a single message is (much) slower, because the
1165 whole folder must be read. However, in directory based folders you
1166 have to figure-out which message you need, which may be a hassle as
1167 well.
1168 Examples of file based folders are MBOX, DBX, and NetScape.
1170 • Directory based folders Mail::Box::Dir
1172 In stead of collecting multiple messages in one file, you can also
1174 put each message in a separate file and collect those files in a
1175 directory to represent a folder.
1176 The main disadvantages of these folders are the enormous amount of
1178 tiny files you usually get in your file-system. It is extremely
1179 slow to search through your whole folder, because many files have
1180 to be opened to do so.
1181 The best feature of this organization is that each message is kept
1183 exactly as it was received, and can be processed with external
1184 scripts as well: you do not need any mail user agent (MUA).
1185 Examples of directory organized folders are MH, Maildir, EMH and
1187 XMH.
1188 • Network (external) folders Mail::Box::Net
1190 Where both types described before provide direct access to the
1192 message data, maintain these folder types the message data for you:
1193 you have to request for messages or parts of them. These folders
1194 do not have a filename, file-system privileges and system locking
1195 to worry about, but typically require a hostname, folder and
1196 message IDs, and authorization.
1197 Examples of these folder types are the popular POP and IMAP, and
1199 database oriented message storage.
1200 Available folder types
1202 • Mail::Box::Dbx (read only)
1203 Dbx files are created by Outlook Express. Using the external
1205 (optional) Mail::Transport::Dbx module, you can read these folders,
1206 even when you are running MailBox on a UNIX/Linux platform.
1207 Writing and deleting messages is not supported by the library, and
1209 therefore not by MailBox. Read access is enough to do folder
1210 conversions, for instance.
1211 • Mail::Box::IMAP4 (partially)
1213 The IMAP protocol is very complex. Some parts are implemented to
1215 create (sub-optimal but usable) IMAP clients. Besides, there are
1216 also some parts for IMAP servers present. The most important
1217 lacking feature is support for encrypted connections.
1218 • Mail::Box::Maildir
1220 Maildir folders have a directory for each folder. A folder
1222 directory contains "tmp", "new", and "cur" sub-directories, each
1223 containing messages with a different purpose. Files with new
1224 messages are created in "tmp", then moved to "new" (ready to be
1225 accepted). Later, they are moved to the "cur" directory
1226 (accepted). Each message is one file with a name starting with
1227 timestamp. The name also contains flags about the status of the
1228 message.
1229 Maildir folders can not be used on Windows by reason of file-name
1231 limitations on that platform.
1232 • Mail::Box::Mbox
1234 A folder type in which all related messages are stored in one file.
1236 This is a very common folder type for UNIX.
1237 • Mail::Box::MH
1239 This folder creates a directory for each folder, and a message is
1241 one file inside that directory. The message files are numbered
1242 sequentially on order of arrival. A special ".mh_sequences" file
1243 maintains flags about the messages.
1244 • Mail::Box::POP3 (read/delete only)
1246 POP3 is a protocol which can be used to retrieve messages from a
1248 remote system. After the connection to a POP server is made, the
1249 messages can be looked at and removed as if they are on the local
1250 system.
1251 • Mail::Box::Netzwert
1253 The Netzwert folder type is optimized for mailbox handling on a
1255 cluster of systems with a shared NFS storage. The code is not
1256 released under GPL (yet)
1257 Other folder types are on the (long) wishlist to get implemented.
1259 Please, help implementing more of them.
1260 Folder class implementation
1262 The class structure of folders is very close to that of messages. For
1263 instance, a Mail::Box::File::Message relates to a Mail::Box::File
1264 folder. The folder types are:
1265 Mail::Box::Netzwert
1267 Mail::Box::Mbox | Mail::Box::Maildir Mail::Box::POP3
1268 | Mail::Box::Dbx | | Mail::Box::MH | Mail::Box::IMAP4
1269 | | | | | | |
1270 | | | | | | |
1271 Mail::Box::File Mail::Box::Dir Mail::Box::Net
1272 | | |
1273 `--------------. | .---------------'
1274 | | |
1275 Mail::Box
1276 |
1277 |
1278 Mail::Reporter (general base class)
1279 By far most folder features are implemented in Mail::Box, so available
1281 to all folder types. Sometimes, features which appear in only some of
1282 the folder types are simulated for folders that miss them, like sub-
1283 folder support for MBOX.
1284
1286 Warning: Changes not written to read-only folder $self.
1287 You have opened the folder read-only --which is the default set by
1288 new(access)--, made modifications, and now want to close it. Set
1289 close(force) if you want to overrule the access mode, or close the
1290 folder with close(write) set to "NEVER".
1291 Error: Copying failed for one message.
1293 For some reason, for instance disc full, removed by external
1294 process, or read-protection, it is impossible to copy one of the
1295 messages. Copying will proceed for the other messages.
1296 Error: Destination folder $name is not writable.
1298 The folder where the messages are copied to is not opened with
1299 write access (see new(access)). This has no relation with write
1300 permission to the folder which is controlled by your operating
1301 system.
1302 Warning: Different messages with id $msgid
1304 The message id is discovered more than once within the same folder,
1305 but the content of the message seems to be different. This should
1306 not be possible: each message must be unique.
1307 Error: Folder $name is opened read-only
1309 You can not write to this folder unless you have opened the folder
1310 to write or append with new(access), or the "force" option is set
1311 true.
1312 Error: Folder $name not deleted: not writable.
1314 The folder must be opened with write access via new(access),
1315 otherwise removing it will be refused. So, you may have write-
1316 access according to the operating system, but that will not
1317 automatically mean that this "delete" method permits you to. The
1318 reverse remark is valid as well.
1319 Error: Invalid timespan '$timespan' specified.
1321 The string does not follow the strict rules of the time span syntax
1322 which is permitted as parameter.
1323 Warning: Message-id '$msgid' does not contain a domain.
1325 According to the RFCs, message-ids need to contain a unique random
1326 part, then an "@", and then a domain name. This is made to avoid
1327 the creation of two messages with the same id. The warning emerges
1328 when the "@" is missing from the string.
1329 Error: No folder name specified.
1331 You did not specify the name of a folder to be opened. Use the
1332 new(folder) option or set the "MAIL" environment variable.
1333 Error: Package $package does not implement $method.
1335 Fatal error: the specific package (or one of its superclasses) does
1336 not implement this method where it should. This message means that
1337 some other related classes do implement this method however the
1338 class at hand does not. Probably you should investigate this and
1339 probably inform the author of the package.
1340 Error: Unable to create subfolder $name of $folder.
1342 The copy includes the subfolders, but for some reason it was not
1343 possible to copy one of these. Copying will proceed for all other
1344 sub-folders.
1345 Error: Writing folder $name failed
1347 For some reason (you probably got more error messages about this
1348 problem) it is impossible to write the folder, although you should
1349 because there were changes made.
1350
1352 This module is part of Mail-Box distribution version 3.009, built on
1353 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
1354
1356 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
1357 ChangeLog.
1358 This program is free software; you can redistribute it and/or modify it
1360 under the same terms as Perl itself. See http://dev.perl.org/licenses/
1361perl v5.36.0 2023-01-20 Mail::Box(3)