DESCRIPTION

Introduction

The MailBox package is a suite of classes for accessing and managing email folders in a folder-independent manner. This package is an alternative to the Mail::Folder and MIME::* packages. It abstracts the details of messages, message storage, and message threads, while providing better performance than older mail packages. It is meant to provide an object-oriented toolset for all kinds of e-mail applications, under which Mail User-Agents (MUA) and mail filtering programs.

This package is modular --parts of it can be used independently of the rest. For example, the Mail::Box::Manager can automatically determine that a folder is in Mbox format and return an object of the Mail::Box::Mbox class, or the user program can bypass the manager and create Mail::Box::Mbox objects directly. Similarly, if the user program is only manipulating a single message, a Mail::Message.

The Mail::Box package has special features to help MUA's access folder data quickly in random order. You will not really benefit (neither slower) if you need the full folder sequentially.

You may want to have a look at the sample scripts in the scripts directory.

Distributions

Upto MailBox v2, all Mail::* modules where released as a single distribution. From v3, there are a few separate distributions in an attempt to reduce the dependencies:

The names of the classes are not always ideal: the 'Mail' namespace on CPAN is quite full.

The class relations

Mail::Box::Manager objects play a central role in any program which is built with MailBox. Each program will create one manager, and then open folders via that manager. Besides folders, the manager can also be used to discover message threads: sequences of messages with their follow-ups.

                       <has-a>      Mail::Box::Mbox
  Mail::Box::Manager <---------*    (Mail::Box::MH)
         ^                :         (Mail::Box::Maildir)
         |           (maintains)    (Mail::Box::POP3)
         |                :
         |                :
         `---------------------*  Mail::Box::Thread::Manager
                      (<has-a>)

Each folder maintains a list of messages. Much effort is made to hide differences between folder types and kinds of messages. Your program can be used for MBOX, MH, Maildir, and POP3 folders with no change at all (as long as you stick to the rules).

 Mail::Box::Mbox  <-----------* Mail::Box::Mbox::Message
        ^             <has-a>            ^
        | <isa>                          | <isa>
        |                                |
    Mail::Box     ............. Mail::Box::Message
                                         ^
                                         | <isa>
                                         |
                                   Mail::Message
                                        / \
                                       <has-a>  
                                      /     \
                           Mail::Message   Mail::Message 
                             ::Body            ::Head

The situation for MH and Maildir folders is a little more complicated, because they have an extra intermediate level of abstraction: Mail::Box::Dir. The POP3 folder has an intermediate Mail::Box::Net.

In the future, when more Mbox-like folder types get implemented, there may be a Mail::Box::File level too. The following is also true for the mail boxes

 MB::MH::Message                 MB::POP3::Message
       \  MB::Maildir::Message            /
        \         /                      /
         \       /   MB::Mbox::Message  /
          \     /         |            /
        MB::Dir::Message  |   MB::Net::Message
                     \    |    /
                      \   |   /
                      MB::Message
                          |
                          |
                     Mail::Message

The Manager

The mailbox manager Mail::Box::Manager encapsulates folder management issues. It maintains a set of open mail folders (mailboxes), and provides methods for opening and closing them, efficiently moving messages between folders, and efficiently appending messages to folders. It contains Mail::Box objects which may be of different types. Most folder types can be detected automatically.

The main manager also manages message-thread detector objects, and informs them when the contents of a folder have changed. This manager class is the only one you instantiate yourself: objects of all other classes will be provided by your folder manager.

You are strongly advised to use this object, but you can often do without it and open a specific folder-type directly.

The Messages

The Folder types

Various Other Classes

All classes are written to be extensible.