NAME

Mail::MboxParser - read-only access to UNIX-mailboxes

SYNOPSIS

        use Mail::MboxParser;

        my $mb = Mail::MboxParser->new('some_mailbox');

        for my $msg ($mb->get_messages) {
                my %header = %{$msg->header};
                print $msg->from->{name}, "\n";
                print $msg->from->{email}, "\n";
                print $header{subject}, "\n";
                print $header{'reply-to'}, "\n";
                $msg->store_all_attachements('/tmp');
        }

DESCRIPTION

This module attempts to provide a simplified access to standard UNIX-mailboxes. It offers only a subset of methods to get 'straight to the point'. More sophisticated things can still be done by invoking any method from MIME::Tools on the appropriate return values.

METHODS

The below methods refer to Mail::MboxParser-objects.

new

new(MAILBOX)

This creates a new MboxParser-object opening the specified MAILBOX with either absolute or relative path. It does not necessarily need a parameter in which case you need to pass the mailbox to the object using the method 'open'. Returns nothing.

open(mailbox)

Can be used to either pass a mailbox to the MboxParser-object either the first time or for changing the mailbox. Returns nothing.

get_messages

Returns an array containing all messages in the mailbox respresented as Mail::MboxParser::Mail objects.

nmsgs

Returns the number of messages in a mailbox. You could naturally also call get_messages in an array context, but this one wont create new objects. It just counts them and thus it is much quicker and wont eat a lot of memory.

The below methods refer to Mail::MboxParser::Mail-objects returned by get_messages.

new(header, body)

This is usually not called directly but instead by $mb->get_messages. You could however create a mail-object manually providing the header and body both as one string.

header

Returns the mail-header as a hash-ref with header-fields as keys. All keys are turned to lower-case, so $header{Subject} has to be written as $header{subject}.

body

Returns the body as a single string.

from

Returns a hash-ref with the two fields 'name' and 'email'. Returns undef if empty.

id

Returns the message-id of a message cutting off the leading and trailing '<' and '>' respectively.

num_entitities

Returns the number of MIME-entities. That is, the number of sub-entitities actually.

get_entitities([n])

Either returns an array of all MIME::Entity objects or one particular if called with a number.

get_entity_body(n)

Returns the body of the n-th MIME::Entity as a single string.

store_entity_body(n, FILEHANDLE)

Stores the stringified body of n-th entity to the specified filehandle. That's basically the same as:

        my $body = $mail->get_entity_body(0);
        print FILEHANDLE $body;

and could be shortened to this:

        $mail->store_entity_body(0, \*FILEHANDLE);

store_attachement(n, path)

It is really just a call to store_entity_body but it will take care that the n-th entity really is a saveable attachement. That is, it wont save anything with a MIME-type of, say, text/html or so. It uses the recommended-filename found in the MIME-header. 'path' is the place where the new file will go to.

store_all_attachements(path)

Walks through an entire mail and stores all apparent attachements to 'path'. See the supplied store_att.pl script in the eg-directory of the package to see a useful example.

FIELDS

Mail::MboxParser is basically a pseudo-hash containing two fields.

$mb->{READER}

This is the filehandle from which is read internally. As to yet, it is read-only so you can't use it for writing. This may be changed later.

$mb->{NMSGS}

Having called nmsgs once this field contains the number of messages in the mailbox. Thus there is no need for calling the method twice which speeds up matters a little.

Mail::MboxParser::Mail is a pseudo-hash with four fields.

$mail->{RAW}

Contains the whole message (that is, header plus body) in one string.

$mail->{HEADER}

Well, just the header of the message as a string.

$mail->{BODY}

You guess it.

$mail->{ENTITY}

The top-level MIME::Entity of a message. You can call any suitable methods from the MIME::tools upon this object to give you more specific access to MIME-parts.

BUGS

Don't know yet of any. However, since I only have a limited number of mailboxes on which I could test the module, there might be circumstances under which Mail::MboxParser fails to work correctly. It will probably fail on mal-formated mails produced by some cheap CGI-webmailers.

The way of counting the number of mails in a mailbox is a little suspect. Internally this looks like '$self->{NMSGS}++ if /^Lines: \d+\n$/;'. In case nmsgs really produces bogus then you could try calling get_messages in scalar context: '$mb->{NMSGS} = $mb->get_messages'. Once having done so, a call to nmsgs will produce this number since it only parses once and will only return the previously cached results on later calls.

AUTHOR AND COPYRIGHT

Tassilo von Parseval <Tassilo.Parseval@post.RWTH-Aachen.de>.

Copyright (c) 2001 Tassilo von Parseval. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.