use Mail::Box::Manager; my $mgr = Mail::Box::Manager->new; my $folder = $mgr->open(folder => 'InBox'); my $msg = $folder->message(2); # $msg is a Mail::Message now my $subject = $msg->subject; # The message's subject my @cc = $msg->cc; # List of Mail::Address'es my $msg = Mail::Message->build(...); my $reply_msg = Mail::Message->reply(...); my $frwd_msg = Mail::Message->forward(...); my Mail::Message::Head $head = $msg->head; my Mail::Message::Body $body = $msg->decoded; $msg->decoded->print($outfile);
See SYNOPSIS in Mail::Reporter
A Mail::Message
object is a container for MIME-encoded message information,
as defined by RFC2822. Everything what is not specificly related to storing
the messages in mailboxes (folders) is implemented in this class. Methods
which are related to folders is implemented in the Mail::Box::Message
extension.
The main methods are get(), to get information from a message header field, and decoded() to get the intended content of a message. But there are many more which can assist your program.
Complex message handling, like construction of replies and forwards, are implemented in separate packages which are autoloaded into this class. This means you can simply use these methods as if they are part of this class. Those package add functionality to all kinds of message objects.
See DESCRIPTION in Mail::Reporter
A MIME-compliant message is build upon two parts: the header and the body.
The header is a list of fields, some spanning more than one line (folded) each telling something about the message. Information stored in here are for instance the sender of the message, the receivers of the message, when it was transported, how it was transported, etc. Headers can grow quite large.
In MailBox, each message object manages exactly one header object (a Mail::Message::Head) and one body object (a Mail::Message::Body). The header contains a list of header fields, which are represented by Mail::Message::Field objects.
The body contains the "payload": the data to be transfered. The data can be encoded, only accessible with a specific application, and may use some weird character-set, like Vietnamese; the MailBox distribution tries to assist you with handling these e-mails without the need to know all the details. This additional information ("meta-information") about the body data is stored in the header. The header contains more information, for instance about the message transport and relations to other messages.
The general idea about the structure of a message is
Mail::Message | | | `-has-one--Mail::Message::Body | `----has-one--Mail::Message::Head | `-has-many--Mail::Message::Field
However: there are about 7 kinds of body objects, 3 kinds of headers and 3 kinds of fields. You will usually not see too much of these kinds, because they are merely created for performance reasons and can be used all the same, with the exception of the multipart bodies.
A multipart body is either a Mail::Message::Body::Multipart
(mime type multipart/*
) or a Mail::Message::Body::Nested
(mime type message/rfc822
). These bodies are more complex:
Mail::Message::Body::Multipart | `-has-many--Mail::Message::Part | | | `-has-one--Mail::Message::Body | `----has-one--Mail::Message::Head
Before you try to reconstruct multiparts or nested messages yourself, you can better take a look at Mail::Message::Construct::Rebuild.
The class structure of messages is very close to that of folders. For instance, a Mail::Box::File::Message relates to a Mail::Box::File folder.
As extra level of inheritance, it has a Mail::Message, which is a message without location. And there is a special case of message: Mail::Message::Part is a message encapsulated in a multipart body.
The message types are:
Mail::Box::Mbox::Message Mail::Box::POP3::Message | Mail::Box::Dbx::Message Mail::Box::IMAP4::Message | | | | | Mail::Box::File::Message Mail::Box::Net::Message | | | Mail::Box::Maildir::Message | | | Mail::Box::MH::Message | | | | | | Mail::Box::Dir::Message | | | | `------------. | .-----------------' | | | Mail::Box::Message Mail::Message::Part | | | .-------------' | | Mail::Message | | 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.
Two strange other message types are defined: the Mail::Message::Dummy, which fills holes in Mail::Box::Thread::Node lists, and a Mail::Box::Message::Destructed, this is an on purpose demolished message to reduce memory consumption.
Labels (also named "Flags") are used to indicate some special condition on the message, primary targeted on organizational issues: which messages are already read or should be deleted. There is a very strong user relation to labels.
The main complication is that each folder type has its own way of storing
labels. To give an indication: MBOX folders use Status
and X-Status
header fields, MH uses a .mh-sequences
file, MAILDIR encodes the flags
in the message's filename, and IMAP has flags as part of the protocol.
Besides, some folder types can store labels with user defined names, where other lack that feature. Some folders have case-insensitive labels, other don't. Read all about the specifics in the manual page of the message type you actually have.
To standardize the folder types, MailBox has defined the following labels, which can be used with the label() and labels() methods on all kinds of messages:
This message is flagged to be deleted once the folder closes. Be very careful about the concept of 'delete' in a folder context : it is only a flag, and does not involve immediate action! This means, for instance, that the memory which is used by Perl to store the message is not released immediately (see destruct() if you need to).
The methods delete(), deleted(), and isDeleted() are only
short-cuts for managing the delete
label (as of MailBox 2.052).
The user has prepared this message, but is has not been send (yet). This flag is not automatically added to a message by MailBox, and has only a meaning in user applications.
Messages can be flagged for some purpose, for instance as result of a search for spam in a folder. The Mail::Box::messages() method can be used to collect all these flagged messages from the folder.
Probably it is more useful to use an understandable name (like spam
)
for these selections, however these self-defined labels can not stored
in all folder types.
The message was already in the folder when it was opened the last time, so was not recently added to the folder. This flag will never automatically be set by MailBox, because it would probably conflict with the user's idea of what is old.
Not often used or kept, this flag indicates that the message was bounced or forwarded to someone else.
The user (or application) has sent a message back to the sender of the message, as response of this one. This flag is automatically set if you use reply(), but not with forward() or bounce().
When this flag is set, the receiver of the message has consumed the message. A mail user agent (MUA) will set this flag when the user has opened the message once.
Mbox folders have no special means of storing information about messages (except the message separator line), and therefore have to revert to adding fields to the message header when something special comes up. This feature is also enabled for POP3, although whether that works depends on the POP server.
All applications which can handle mbox folders support the Status
and
X-Status
field convensions. The following encoding is used:
Flag Field Label R Status => seen (Read) O Status => old (not recent) A X-Status => replied (Answered) F X-Status => flagged
There is no special flag for deleted
, which most other folders support:
messages flagged to be deleted will never be written to a folder file when
it is closed.