| Mail::Box(3pm) | User Contributed Perl Documentation | Mail::Box(3pm) |
Mail::Box - manage a mailbox, a folder with messages
Mail::Box is a Mail::Reporter Mail::Box is extended by Mail::Box::Dir Mail::Box::File Mail::Box::Net
use Mail::Box::Manager;
my $mgr = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => $ENV{MAIL}, ...);
print $folder->name;
# Get the first message.
print $folder->message(0);
# Delete the third message
$folder->message(3)->delete;
# Get the number of messages in scalar context.
my $emails = $folder->messages;
# Iterate over the messages.
foreach ($folder->messages) {...} # all messages
foreach (@$folder) {...} # all messages
$folder->addMessage(Mail::Box::Message->new(...));
Tied-interface:
tie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox; # Four times the same: $inbox[3]->print; # tied $folder->[3]->print; # overloaded folder $folder->message(3)->print; # usual print $folder->[3]; # overloaded message tie my(%inbox), 'Mail::Box::Tie::HASH', $inbox; # Twice times the same $inbox{$msgid}->print; # tied $folder->messageId($msgid)->print;# usual
A Mail::Box::Manager creates "Mail::Box" objects. But you already knew, because you started with the Mail::Box-Overview manual page. That page is obligatory reading, sorry!
"Mail::Box" is the base class for accessing various types of mailboxes (folders) in a uniform manner. The various folder types vary on how they store their messages, but when some effort those differences could be hidden behind a general API. For example, some folders store many messages in one single file, where other store each message in a separate file within the same directory.
No object in your program will be of type "Mail::Box": it is only used as base class for the real folder types. "Mail::Box" is extended by
Extends "DESCRIPTION" in Mail::Reporter.
example: use overloaded folder as string
# Three lines with overloading: resp. cmp, @{}, and ""
foreach my $folder (sort @folders)
{ my $msgcount = @$folder;
print "$folder contains $msgcount messages\n";
}
example: use overloaded folder as array
my $msg = $folder->[3]; my $msg = $folder->message(3); # same foreach my $msg (@$folder) ... foreach my $msg ($folder->messages) ... # same
Extends "METHODS" in Mail::Reporter.
Extends "Constructors" in Mail::Reporter.
To control delay-loading of messages, as well the headers as the bodies, a set of *_type options are available. "extract" determines whether we want delay-loading.
-Option --Defined in --Default
access 'r'
body_delayed_type Mail::Message::Body::Delayed
body_type <folder specific>
coerce_options []
create <false>
extract 10240
field_type undef
fix_headers <false>
folder $ENV{MAIL}
folderdir undef
head_delayed_type Mail::Message::Head::Delayed
head_type Mail::Message::Head::Complete
keep_dups <false>
lock_file undef
lock_timeout 1 hour
lock_type Mail::Box::Locker::DotLock
lock_wait 10 seconds
locker undef
log Mail::Reporter 'WARNINGS'
manager undef
message_type <folder-class>::Message
multipart_type Mail::Message::Body::Multipart
remove_when_empty <true>
save_on_exit <true>
trace Mail::Reporter 'WARNINGS'
trusted <depends on folder location>
These MODE has no relation to the modes actually used to open the folder files within this module. For instance, if you specify "rw", and open the folder, only read permission on the folder-file is required.
Be warned: writing a MBOX folder may create a new file to replace the old folder. The permissions and owner of the file may get changed by this.
Specify a CODE-reference which produces the body-type to be created, or a CLASS of the body which is used when the body is not a multipart or nested. In case of a code reference, the header structure is passed as first argument to the routine.
Do not return a delayed body-type (like "::Delayed"), because that is determined by the "extract" option while the folder is opened. Even delayed message will require some real body type when they get parsed eventually. Multiparts and nested messages are also outside your control.
For instance:
$mgr->open('InBox', body_type => \&which_body);
sub which_body($) {
my $head = shift;
my $size = $head->guessBodySize || 0;
my $type = $size > 100000 ? 'File' : 'Lines';
"Mail::Message::Body::$type";
}
The default depends on the mail-folder type, although the general default is Mail::Message::Body::Lines. Please check the applicable manual pages.
Be careful: you may create a different folder type than you expect unless you explicitly specify Mail::Box::Manager::open(type).
If you supply an INTEGER to this option, bodies of those messages with a total size less than that number will be extracted from the folder only when necessary. Messages where the size (in the "Content-Length" field) is not included in the header, like often the case for multiparts and nested messages, will not be extracted by default.
If you supply a CODE reference, that subroutine is called every time that the extraction mechanism wants to determine whether to parse the body or not. The subroutine is called with the following arguments:
CODE->(FOLDER, HEAD)
where FOLDER is a reference to the folder we are reading. HEAD refers to the Mail::Message::Head::Complete head of the message at hand. The routine must return a "true" value (extract now) or a "false" value (be lazy, do not parse yet). Think about using the Mail::Message::Head::guessBodySize() and Mail::Message::guessTimestamp() on the header to determine your choice.
The third possibility is to specify the NAME of a method. In that case, for each message is called:
FOLDER->NAME(HEAD)
Where each component has the same meaning as described above.
The fourth way to use this option involves constants: with "LAZY" all messages will be delayed. With "ALWAYS" you enforce unconditional parsing, no delaying will take place. The latter is usuful when you are sure you always need all the messages in the folder.
$folder->new(extract => 'LAZY'); # Very lazy
$folder->new(extract => 10000); # Less than 10kB
# same, but implemented yourself
$folder->new(extract => &large);
sub large($) {
my ($f, $head) = @_;
my $size = $head->guessBodySize;
defined $size ? $size < 10000 : 1
};
# method call by name, useful for Mail::Box
# extensions. The example selects all messages
# sent by you to be loaded without delay.
# Other messages will be delayed.
$folder->new(extract => 'sent_by_me');
sub Mail::Box::send_by_me($) {
my ($self, $header) = @_;
$header->get('from') =~ m/\bmy\@example.com\b/i;
}
The folder name can be preceded by a "=", to indicate that it is named relative to the directory specified in new(folderdir). Otherwise, it is taken as relative or absolute path.
If you do not check encodings of received messages, you may print binary data to the screen, which is a security risk.
Messages with id's which already exist in this folder are not added.
BE WARNED that message labels may get lost when a message is moved from one folder type to an other. An attempt is made to translate labels, but there are many differences in interpretation by applications.
-Option--Default
share <not used>
Sharing the resource is quite dangerous, and only available for a limited number of folder types, at the moment only some Mail::Box::Dir folders; these file-based messages can be hardlinked (on platforms that support it). The link may get broken when one message is modified in one of the folders.... but maybe not, depending on the folder types involved.
example:
$folder->addMessage($msg); $folder->addMessages($msg1, $msg2, ...);
example:
$folder->addMessages($msg1, $msg2, ...);
For some folder types it is required to open the folder before it can be used for appending. This can be fast, but this can also be very slow (depends on the implementation). All %options passed will also be used to open the folder, if needed.
-Option --Default
folder <required>
message undef
messages undef
share <false>
example:
my $message = Mail::Message->new(...);
Mail::Box::Mbox->appendMessages
( folder => '=xyz'
, message => $message
, folderdir => $ENV{FOLDERS}
);
better:
my Mail::Box::Manager $mgr; $mgr->appendMessages($message, folder => '=xyz');
WARNING: When moving messages from one folder to another, be sure to write the destination folder before writing and closing the source folder. Otherwise you may lose data if the system crashes or if there are software problems.
-Option --Default
force <false>
save_deleted false
write MODIFIED
example:
my $f = $mgr->open('spam', access => 'rw')
or die "Cannot open spam: $!\n";
$f->message(0)->delete
if $f->messages;
$f->close
or die "Couldn't write $f: $!\n";
-Option --Default
delete_copied <false>
select 'ACTIVE'
share <not used>
subfolders <folder type dependent>
example:
my $mgr = Mail::Box::Manager->new;
my $imap = $mgr->open(type => 'imap', host => ...);
my $mh = $mgr->open(type => 'mh', folder => '/tmp/mh',
create => 1, access => 'w');
$imap->copyTo($mh, delete_copied => 1);
$mh->close; $imap->close;
WARNING: When moving messages from one folder to another, be sure to write the destination folder before deleting the source folder. Otherwise you may lose data if the system crashes or if there are software problems.
-Option --Default
recursive 1
example: removing an open folder
my $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw'); ... some other code ... $folder->delete;
example: removing an closed folder
my $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd'); $folder->delete;
example:
print $folder->folderdir;
$folder->folderdir("$ENV{HOME}/nsmail");
example:
print $folder->name;
print "$folder"; # overloaded stringification
The %options are extra values which are passed to the updateMessages() method which is doing the actual work here.
example:
print $folder->url;
# may result in
# mbox:/var/mail/markov or
# pop3://user:password@pop.aol.com:101
WARNING: this flag is not related to an external change to the folder structure on disk. Have a look at update() for that.
example:
$folder->addMessage($msg) if $folder->writable;
example:
$folder->current(0); $folder->current($message);
example: looking for a labeled message
my $current = $folder->findFirstLabeled('current');
my $first = $folder->findFirstLabeled(seen => 0);
my $last = $folder->findFirstLabeled(seen => 0,
[ reverse $self->messages('ACTIVE') ] )
example:
my $msg = $folder->message(3); $folder->message(3)->delete; # status changes to `deleted' $folder->message(3, $msg); print $folder->message(-1); # last message.
!!WARNING!!: when the message headers are delay-parsed, the message might be in the folder but not yet parsed into memory. In this case, use find() instead of "messageId()" if you really need a thorough search. This is especially the case for directory organized folders without special indexi, like Mail::Box::MH.
The $message_id may still be in angles, which will be stripped. In that case blanks (which origin from header line folding) are removed too. Other info around the angles will be removed too.
example:
my $msg = $folder->messageId('<complex-message.id>');
$folder->messageId("<complex-message\n.id>", $msg);
my $msg = $folder->messageId('complex-message.id');
my $msg = $folder->messageId('garbage <complex-message.id> trash');
For some folder-types (like MH), this method may cause all message-files to be read. See their respective manual pages.
example:
foreach my $id ($folder->messageIds) {
$folder->messageId($id)->print;
}
You may also specify a $range: two numbers specifying begin and end index in the array of messages. Negative indexes count from the end of the folder. When an index is out-of-range, the returned list will be shorter without complaints.
Everything else than the predefined names is seen as labels. The messages which have that label set will be returned. When the sequence starts with an exclamation mark (!), the search result is reversed.
For more complex searches, you can specify a $filter, which is simply a code reference. The message is passed as only argument.
example:
foreach my $message ($folder->messages) {...}
foreach my $message (@$folder) {...}
# twice the same
my @messages = $folder->messages;
my @messages = $folder->messages('ALL');
# Selection based on a range (begin, end)
my $subset = $folder->messages(10,-8);
# twice the same:
my @not_deleted= grep {not $_->isDeleted}
$folder->messages;
my @not_deleted= $folder->messages('ACTIVE');
# scalar context the number of messages
my $nr_of_msgs = $folder->messages;
# third message, via overloading
$folder->[2];
# Selection based on labels
$mgr->moveMessages($spam, $inbox->message('spam'));
$mgr->moveMessages($archive, $inbox->message('seen'));
The %options are passed to (and explained in) messages().
When all message-ids are known, then looking-up messages is simple: they are found in a plain hash using messageId(). But Mail::Box is lazy where it can, so many messages may not have been read from file yet, and that's the preferred situation, because that saves time and memory.
It is not smart to search for the messages from front to back in the folder: the chances are much higher that related message reside closely to each other. Therefore, this method starts scanning the folder from the specified $message, back to the front of the folder.
The $timespan can be used to terminate the search based on the time enclosed in the message. When the constant string "EVER" is used as $timespan, then the search is not limited by that. When an integer is specified, it will be used as absolute time in time-ticks as provided by your platform dependent "time" function. In other cases, it is passed to timespan2seconds() to determine the threshold as time relative to the message's time.
The $window is used to limit the search in number of messages to be scanned as integer or constant string "ALL".
Returned are the message-ids which were not found during the scan. Be warned that a message-id could already be known and therefore not found: check that first.
example: scanning through a folder for a message
my $refs = $msg->get('References') or return;
my @msgids = $ref =~ m/\<([^>]+\>/g;
my @failed = $folder->scanForMessages($msg, \@msgids, '3 days', 50);
For MBOX folders, sub-folders are simulated.
-Option --Default
check <false>
folder <from calling object>
folderdir <from folder>
skip_empty <false>
example:
my $folder = $mgr->open('=in/new');
my @subs = $folder->listSubFolders;
my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');
my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.
example: how to get the name of a subfolder
my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc');
print $sub; # abc/xyz
my $f = Mail::Box::Mbox->new(folder => 'abc');
print $f->nameOfSubfolder('xyz'); # abc/xyz
my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef);
print $sub; # xyz
example:
my $folder = Mail::Box::Mbox->new(folder => '=Inbox');
my $sub = $folder->openSubFolder('read');
-Option --Default
folderdir undef
The $foldername specifies the name of the folder, as is specified by the application. You need to specified the "folder" option when you skip this first argument.
%options is a list of extra information for the request. Read the documentation for each type of folder for type specific options, but each folder class will at least support the "folderdir" option:
-Option --Default
folderdir undef
example:
Mail::Box::Mbox->foundIn('=markov',
folderdir => "$ENV{HOME}/Mail");
Mail::Box::MH->foundIn(folder => '=markov');
UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF. Each separator will be represented by a "\n" within your program. However, when processing platform foreign folders, complications appear. Think about the "Size" field in the header.
When the separator is changed, the whole folder me be rewritten. Although, that may not be required.
NOTE: if you are copying messages from one folder to another, use addMessages() instead of "read()".
example:
my $mgr = Mail::Box::Manager->new;
my $folder = $mgr->open('InBox'); # implies read
my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same
The %options are "trusted", "head_type", "field_type", "message_type", "body_delayed_type", and "head_delayed_type" as defined by the folder at hand. The defaults are the constructor defaults (see new()).
Although this is quite a dangerous, it only fails when a folder is updated (reordered or message removed) at exactly the same time as new messages arrive. These collisions are sparse.
The options are the same as for readMessages().
WARNING: When moving messages from one folder to another, be sure to write (or close()) the destination folder before writing (or closing) the source folder: otherwise you may lose data if the system crashes or if there are software problems.
To write a folder to a different file, you must first create a new folder, then move all the messages, and then write or close() that new folder.
-Option --Default
force <false>
save_deleted <false>
-Option --Default
messages <required>
Extends "Error handling" in Mail::Reporter.
Extends "Cleanup" in Mail::Reporter.
In general, there are three classes of folders: those who group messages per file, those who group messages in a directory, and those do not provide direct access to the message data. These folder types are each based on a different base class.
File based folders maintain a folder (a set of messages) in one single file. The advantage is that your folder has only one single file to access, which speeds-up things when all messages must be accessed at once.
One of the main disadvantages over directory based folders is that you have to construct some means to keep all message apart. For instance MBOX adds a message separator line between the messages in the file, and this line can cause confusion with the message's contents.
Where access to all messages at once is faster in file based folders, access to a single message is (much) slower, because the whole folder must be read. However, in directory based folders you have to figure-out which message you need, which may be a hassle as well.
Examples of file based folders are MBOX, DBX, and NetScape.
In stead of collecting multiple messages in one file, you can also put each message in a separate file and collect those files in a directory to represent a folder.
The main disadvantages of these folders are the enormous amount of tiny files you usually get in your file-system. It is extremely slow to search through your whole folder, because many files have to be opened to do so.
The best feature of this organization is that each message is kept exactly as it was received, and can be processed with external scripts as well: you do not need any mail user agent (MUA).
Examples of directory organized folders are MH, Maildir, EMH and XMH.
Where both types described before provide direct access to the message data, maintain these folder types the message data for you: you have to request for messages or parts of them. These folders do not have a filename, file-system privileges and system locking to worry about, but typically require a hostname, folder and message IDs, and authorization.
Examples of these folder types are the popular POP and IMAP, and database oriented message storage.
Dbx files are created by Outlook Express. Using the external (optional) Mail::Transport::Dbx module, you can read these folders, even when you are running MailBox on a UNIX/Linux platform.
Writing and deleting messages is not supported by the library, and therefore not by MailBox. Read access is enough to do folder conversions, for instance.
The IMAP protocol is very complex. Some parts are implemented to create (sub-optimal but usable) IMAP clients. Besides, there are also some parts for IMAP servers present. The most important lacking feature is support for encrypted connections.
Maildir folders have a directory for each folder. A folder directory contains "tmp", "new", and "cur" sub-directories, each containing messages with a different purpose. Files with new messages are created in "tmp", then moved to "new" (ready to be accepted). Later, they are moved to the "cur" directory (accepted). Each message is one file with a name starting with timestamp. The name also contains flags about the status of the message.
Maildir folders can not be used on Windows by reason of file-name limitations on that platform.
A folder type in which all related messages are stored in one file. This is a very common folder type for UNIX.
This folder creates a directory for each folder, and a message is one file inside that directory. The message files are numbered sequentially on order of arrival. A special ".mh_sequences" file maintains flags about the messages.
POP3 is a protocol which can be used to retrieve messages from a remote system. After the connection to a POP server is made, the messages can be looked at and removed as if they are on the local system.
The Netzwert folder type is optimized for mailbox handling on a cluster of systems with a shared NFS storage. The code is not released under GPL (yet)
Other folder types are on the (long) wishlist to get implemented. Please, help implementing more of them.
The class structure of folders is very close to that of messages. For instance, a Mail::Box::File::Message relates to a Mail::Box::File folder. The folder types are:
Mail::Box::Netzwert
Mail::Box::Mbox | Mail::Box::Maildir Mail::Box::POP3
| Mail::Box::Dbx | | Mail::Box::MH | Mail::Box::IMAP4
| | | | | | |
| | | | | | |
Mail::Box::File Mail::Box::Dir Mail::Box::Net
| | |
`--------------. | .---------------'
| | |
Mail::Box
|
|
Mail::Reporter (general base class)
By far most folder features are implemented in Mail::Box, so available to all folder types. Sometimes, features which appear in only some of the folder types are simulated for folders that miss them, like sub-folder support for MBOX.
This module is part of Mail-Box distribution version 3.009, built on August 18, 2020. Website: http://perl.overmeer.net/CPAN/
Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/
| 2020-08-20 | perl v5.30.3 |