my $folder = new Mail::Box::IMAP4 ... my $message = $folder->message(10);
See SYNOPSIS in Mail::Box::Net::Message
A Mail::Box::IMAP4::Message
represents one message on a IMAP4 server,
maintained by a Mail::Box::IMAP4 folder. Each message is stored as
separate entity on the server, and maybe temporarily in your program
as well.
See DESCRIPTION in Mail::Box::Net::Message
See Structure of a Message in Mail::Message
See The header in Mail::Message
See The body in Mail::Message
See Message object implementation in Mail::Message
See Message class implementation in Mail::Message
See Labels in Mail::Message
See Predefined labels in Mail::Message
See Status and X-Status fields in Mail::Message
Labels (or flags) are known to all folder formats, but differ how they are stored. Some folder types use message header lines to keep the labels, other use a separate file. The IMAP protocol does not specify how the labels are kept on the server, but does specify how they are named.
The label names as defined by the IMAP protocol are standardized into the MailBox standard to hide folder differences. The following translations are always performed:
\Seen => seen \Answered => replied \Flagged => flagged \Deleted => deleted \Draft => draft \Recent => NOT old
$imap->message(3)->label(replied => 1, draft => 0);
will result in a IMAP protocol statements like
A003 STORE 4 +FLAGS (\Answered) A003 STORE 4 -FLAGS (\Draft)
Of course, your program may be in need for more labels than those provided by the protocol. You can still use these: they stay locally (and are lost when the folder is closed). Some IMAP4 extensions permit more labels than the basic RFC, but that is not yet supported by this implementation.
When you ask for one or more flags of a message more than once, you may
improve the overall performance by setting new(cache_labels) to YES
.
However, this may cause inconsistencies when multiple clients use the
same folder on the IMAP server.
You may also delay the label updates to the server until the folder is closed (or for ever when read-only is required). When Mail::Box::write() or Mail::Box::close() is called, it is decided whether to throw all changes away or write after all.