\documentclass{article}
\usepackage{hyperref}

\author{Brad Marshall {\tt <brad.marshall@member.sage-au.org.au>}}
\title{Perl Mail Box Manipulation}

\begin{document}

\maketitle

\section{Introduction}

Perl provides a number of interfaces to mailbox folders of which
Mail::Box is but one.  This article will cover the basic use
of it and show how to open a mailbox folder, be it a flat file
or over POP or IMAP, and how to manipulate the messages inside.

\section{Modules}

First you need to import the required modules - in most cases
this will be sufficient:

\begin{verbatim}
use Mail::Box::Manager;
\end{verbatim}

\section{Opening Mailboxes}

This section will cover how to open mailboxes of 3 different
formats - mbox, POP and IMAP.

\subsection{Mbox Format}

To open a mbox folder, simply do the following:

\begin{verbatim}
my $mailspool = "/var/spool/mail/username";
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => $mailspool);
\end{verbatim}

\subsection{POP3}

There are two ways to open a POP folder, as follows:

\begin{verbatim}
my $url = 'pop3://user:password@pop.example.com'
my $pop = Mail::Box::POP3->new($url);

my $mgr    = Mail::Box::Manager->new;
my $pop = $mgr->open(type => 'pop3',
            username => 'myname',
            password => 'mypassword',
            server_name => 'pop.example.com');
\end{verbatim}

\subsection{IMAP4}

IMAP folders are opened similarly to POP, as follows:

\begin{verbatim}
my $imap   = Mail::Box::IMAP4->new(username => 'myname', 
                     password => 'mypassword',
                     server_name => 'imap.example.com');

my $url    = 'imap4://user:password@imap.example.com');
my $mgr    = Mail::Box::Manager->new;
my $imap   = $mgr->open($url);
\end{verbatim}

\section{Manipulating Folders}

To find out the name of the folder you're accessing, simple do the following:

\begin{verbatim}
$name = $folder->name;
\end{verbatim}

To check the number of messages in the folder, just:

\begin{verbatim}
my $emails = $folder->messages;
\end{verbatim}

To loop over each message simply call the messages subroutine
in array context, like so:

\begin{verbatim}
foreach $msg ($folder->messages) { # all messages
    # Do something with $msg
}
\end{verbatim}

To extract basic information from a message, such as subject,
to, from and the body, simply use the following:

\begin{verbatim}
my $subject = $msg->subject;
my @to = $msg->to;
my $from = $msg->sender->address;
my $body = $msg->decoded;
\end{verbatim}

The array returned from the to subroutine consists of
Mail::Address objects.  To pull the actual address out of it,
something like the similar will do:

\begin{verbatim}
foreach $to (@to) {
    print "to = ".$to->format."\n";
}
\end{verbatim}

\section{Conclusion}

As you can see, Mail::Box provides a very simple interface for
pulling out basic information from a mailbox.  You can do much
more than is shown here, for more information see the perldoc
for Mail::Box, Mail::Box-Overview and Mail::Box-Cookbook.

\end{document}