NAME

Mail::Pegasus - read Pegasus Mail folders and messages.

SYNOPSIS

This is a Perl Module to provide read only access to messsages in a Pegasus Mailbox folder.

CONSTRUCTOR

The following method contructs a new Mail::Pegasus object:

new ( Directory => $directory, [ OPTIONS ] )

Directory is a required argument in the form of a key-value pair, jusr like a hash table. It will identify the mailbox heirarchy for the Pegasus mail folder.

OPTIONS is a list of options given in the form of key-value pairs, just like a hash table. Valid options are

Debug

The value of this option should be a 1 or a 0. When set to 1 extensive debug information is sent to STDERR

Heirarch

The value of this option should be the name of the HEIRARCHY.PM file in the target Pegasus mail folder. The default for this option is 'HEIRARCHY.PM' (all upper case).

A HEIRARCHY.PM file is expected and required in the directory supplied to the constructor.

METHODS

init ( )

Will read the heirarchy file reinitialising the folder list.

print_folders ( )

Will provide a text list of folder names prefixed with a numeric folder identifier. The identifier may then be used to select a folder using the select_by_id method.

select_by_id ( FOLDER-ID )

Will mark a folder as selected and will initialise the message list for that folder. The argument must be a number that identifies a valid folder. WARNING: Everytime init() is called the folder identifiers may be changed.

select ( FOLDER-NAME )

Will mark a folder as selected and will initialise the message list for that folder. The argument must be the folder name as found in the print_folders()

list_folders ( )

Will return a reference to an array which will contain a list of all Pegasus Mail folders found.

get_message ( MSG-ID )

Will return the entire message indexed by the MSG-ID in the currently selected folder.

get_message_status ( MSG-ID )

Will return a flag indicating whether the message has been read or not. A return of 1 indicates the message has been read, 0 that the message has not been read, and undef if the status headers are not found.

messages ( )

Will return the number of messages in the currently selected folder.

list_messages ( )

Will return a visual list of messsages in the currently selected folder. The format of the returned list is:

ID: # Date: message date Subject: <message subject>

The ID number can be used with get_message() and get_message_status() to retrieve the message from the folder.

message ( MSG-ID )

Will return a Mail::Internet object for the message specified by MSG-ID in the currently selected folder.

head ( MSG-ID )

Will return a Mail::Header object for the message specified by MSG-ID in the currently selected folder.

body ( MSG-ID )

Will return a body of the message. This is a reference to an array. Each entry in the array represents a single line in the message.

EXAMPLE

This example will show the Data and Subject of every folder of a user, then it will show the first message of the INBOX for the same user and finally it will return the status of the first message in the INBOX.

    my $mailbox = Mail::Pegasus->new(Directory => "$ENV{USER}/pmail");

    foreach my $mailFolder (@{$mailbox->list_folders()})
    {
        $mailbox->select($mailFolder);
        print "Selected $mailFolder [" . $mailbox->messages() . " messages]\n";
        $mailbox->list_messages();
    }

    $mailbox->select("INBOX");
    print $mailbox->get_message("1");
    my $status = $mailbox->get_message_status("1");

    if (defined($status))
    {
        print "Message has " . ($status ? "" : "not ") . "been read!\n";
    } else {
        print "Unable to determine the message status!\n";
    }

    exit;

BUGS

Known issues are:

    Drives and Paths in the heirarchy file will cause the folder
    not to be read.

    If present a seperate folder called INBOX will not be accessable.

    Duplicate folder names render the first read folders with the
    same name inaccessable.

SEE ALSO

Mail::Internet Mail::Header

AUTHOR

Matthew Sullivan <sorbs@cpan.org>

COPYRIGHT

Copyright (c) 2004 Matthew Sullivan & Rodney McDuff. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.