NAME

Mail::IMAPFolderSearch - Search multiple mail folders via a IMAP4rev1 server

SYNOPSIS

     use Mail::IMAPFolderSearch;

     $imap = Mail::IMAPFolderSearch->new(SSL => 1,
                               Server => 'mail.example.com',
                               );

     $imap->login(User => 'imapuser',
                  Password => 'xxxx'
                  );

     $keywords = { Keyword1 => { Word => 'brian',
                                 What => 'FROM' },
                   Keyword2 => { Word => 'imap',
                                 What => 'NOT BODY' },
                   Keyword3 => { Word => '1-Dec-2001',
                                 What => 'SINCE' },
                   Keyword4 => { Word => '13-Jan-2002',
                                 What => 'BEFORE' },
                   Keyword5 => { Word => 'nobody',
                                 What => 'NOT TO' },
                   Keyword6 => { Word => 'test' }
                  };

     $imap->searchFolders(Keywords => $keywords);

     $imap->logout();

REQUIRES

IO::Socket, IO::Socket::SSL

DESCRIPTION

Many e-mail clients such as PINE allow the user to search for a string within a single folder. Mail::IMAPFolderSearch allows for scripting of multiple string searches, spanning multiple mail folders. Results are placed in a new folder allowing the user to use their existing mail client to view matching messages. The results folder is named IMAPSearch by default, but it is possible to specify a different name.

CONSTRUCTOR

new(%options)

The constructor takes a list of attributes that provide information about the IMAP server.

OPTIONS are as follows:

Server Server to connect to. This is required.

SSL Use SSL or not. Takes 0 or 1. SSL is disabled by default.

Port Port to connect to. If SSL is disabled, the default is 143. If it is enabled, the default is 993.

Prefix If mail folders are located in the user's home directory (e.g. under ~user/mail/), enable searching in this location with 1. Default is 0.

PrefixPath If Prefix is enabled, specify the subdirectory under ~user/ that contains mail folders. Default is 'mail'.

Debug Turn on debugging with 1. This will display output from the IMAP server. Default is 0.

Count Specify the command number to start with when interacting with the IMAP server. Default is 0.

METHODS

login(%options)

Authenticate with the IMAP server. login() accepts User and Password.

logout()

Disconnect from the IMAP server.

searchFolders(%options)

Do a search for provided keywords and place the results in a separate mail folder.

OPTIONS are as follows:

Keywords is required and must point to a hashref of keywords.

Folders can be a reference to an array of folders or 'ALL' with 'ALL' being the default.

OutFolder can take a folder name as the location to place search results. The default is 'IMAPSearch'.

Expunge can be set to 1 or 0 with 0 being the default. If Expunge is true, all messages in OutFolder will be deleted and expunged. When Expunge is set, be careful not to set OutFolder to an existing folder that you care about, such as INBOX!

Boolean can be either 'AND' or 'OR'.

getFolders()

Returns a reference to an array containing all mail folders.

messageCount($folder)

Returns the number of messages in $folder.

KEYWORDS

Keyword searching follows RFC 2060's specification for SEARCH. For a full list of options, check there.

As for the main points, note that:

• When specifying 'OR', either of the first two keywords given will match. When specifying more than 2 search terms, elements 3 and above will be matched with 'AND'.

• When setting up your keywords hashref, please consider that keyword keys (i.e. Keyword1, Keyword2, etc.) will be processed in a sorted order. Word is the option used to match a string and is required. What specifies the portion of the message that should be searched. Commonly used criteria are TEXT (full message including headers), FROM (from: header), TO (to: header), SUBJECT (subject: header), SINCE (messages sent since date), BEFORE (messages sent before date), BODY (limit search to message body)

  If What is not specified, it will default to TEXT.

• You may negate 'AND' elements with 'NOT $what' where $what is an acceptable IMAP SEARCH parameter.

• Regular expressions do not work, as per RFC 2060.

AUTHOR

Brian Hodges <bhodgescpan ^at^ pelemele ^dot^ com>

SEE ALSO

perl(1), IO::Socket, IO::Socket::SSL