SYNOPSIS

 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

DESCRIPTION

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

DETAILS

Structure of a Message

A MIME-compliant message is build upon two parts: the header and the body.

The header

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

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.

Message object implementation

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.

Message class implementation

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

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.

Predefined labels

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:

Status and X-Status fields

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.