NAME
    Net::IMAP::Search - Search multiple mail folders via a IMAP4rev1 server

SYNOPSIS
         use Net::IMAP::Search

         $imap = IMAP::Search->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. Net::IMAP::Search 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 <bhodges@pelemele.com>

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

