Provided by: libnet-imap-client-perl_0.9507-1_all bug

NAME

       Net::IMAP::Client - Not so simple IMAP client library

SYNOPSIS

           use Net::IMAP::Client;

           my $imap = Net::IMAP::Client->new(

               server => 'mail.you.com',
               user   => 'USERID',
               pass   => 'PASSWORD',
               ssl    => 1,                              # (use SSL? default no)
               ssl_verify_peer => 1,                     # (use ca to verify server, default yes)
               ssl_ca_file => '/etc/ssl/certs/certa.pm', # (CA file used for verify server) or
             # ssl_ca_path => '/etc/ssl/certs/',         # (CA path used for SSL)
               port   => 993                             # (but defaults are sane)

           ) or die "Could not connect to IMAP server";

           # everything's useless if you can't login
           $imap->login or
             die('Login failed: ' . $imap->last_error);

           # let's see what this server knows (result cached on first call)
           my $capab = $imap->capability;
              # or
           my $knows_sort = $imap->capability( qr/^sort/i );

           # get list of folders
           my @folders = $imap->folders;

           # get total # of messages, # of unseen messages etc. (fast!)
           my $status = $imap->status(@folders); # hash ref!

           # select folder
           $imap->select('INBOX');

           # get folder hierarchy separator (cached at first call)
           my $sep = $imap->separator;

           # fetch all message ids (as array reference)
           my $messages = $imap->search('ALL');

           # fetch all ID-s sorted by subject
           my $messages = $imap->search('ALL', 'SUBJECT');
              # or
           my $messages = $imap->search('ALL', [ 'SUBJECT' ]);

           # fetch ID-s that match criteria, sorted by subject and reverse date
           my $messages = $imap->search({
               FROM    => 'foo',
               SUBJECT => 'bar',
           }, [ 'SUBJECT', '^DATE' ]);

           # fetch message summaries (actually, a lot more)
           my $summaries = $imap->get_summaries([ @msg_ids ]);

           foreach (@$summaries) {
               print $_->uid, $_->subject, $_->date, $_->rfc822_size;
               print join(', ', @{$_->from}); # etc.
           }

           # fetch full message
           my $data = $imap->get_rfc822_body($msg_id);
           print $$data; # it's reference to a scalar

           # fetch full messages
           my @msgs = $imap->get_rfc822_body([ @msg_ids ]);
           print $$_ for (@msgs);

           # fetch single attachment (message part)
           my $data = $imap->get_part_body($msg_id, '1.2');

           # fetch multiple attachments at once
           my $hash = $imap->get_parts_bodies($msg_id, [ '1.2', '1.3', '2.2' ]);
           my $part1_2 = $hash->{'1.2'};
           my $part1_3 = $hash->{'1.3'};
           my $part2_2 = $hash->{'2.2'};
           print $$part1_2;              # need to dereference it

           # copy messages between folders
           $imap->select('INBOX');
           $imap->copy(\@msg_ids, 'Archive');

           # delete messages ("Move to Trash")
           $imap->copy(\@msg_ids, 'Trash');
           $imap->add_flags(\@msg_ids, '\\Deleted');
           $imap->expunge;

DESCRIPTION

       Net::IMAP::Client provides methods to access an IMAP server.  It aims to provide a simple
       and clean API, while employing a rigorous parser for IMAP responses in order to create
       Perl data structures from them.  The code is simple, clean and extensible.

       It started as an effort to improve Net::IMAP::Simple but then I realized that I needed to
       change a lot of code and API so I started it as a fresh module.  Still, the design is
       influenced by Net::IMAP::Simple and I even stole a few lines of code from it ;-) (very
       few, honestly).

       This software was developed for creating a web-based email (IMAP) client: www.xuheki.com.
       Xhueki uses Net::IMAP::Client.

API REFERENCE

       Unless otherwise specified, if a method fails it returns undef and you can inspect the
       error by calling $imap->last_error.  For a successful call most methods will return a
       meaningful value but definitely not undef.

   new(%args)  # constructor
           my $imap = Net::IMAP::Client->new(%args);

       Pass to the constructor a hash of arguments that can contain:

       - server (STRING)
           Host name or IP of the IMAP server.

       - user (STRING)
           User ID (only "clear" login is supported for now!)

       - pass (STRING)
           Password

       - ssl (BOOL, optional, default FALSE)
           Pass a true value if you want to use IO::Socket::SSL You may not set both "ssl" and
           "tls" at the same time.

       - tls (BOOL, optional, default FALSE)
           Pass a true value if you want to use connect without SSL and then use "STARTTLS" to
           upgrade the connection to an encrypted session using IO::Socket::SSL.  The other
           "ssl_*" options also apply.

           You may not set both "ssl" and "tls" at the same time.

       - ssl_verify_peer (BOOL, optional, default TRUE)
           Pass a false value if you do not want to use SSL CA to verify server

           only need when you set ssl to true

       - ssl_ca_file (STRING, optional)
           Pass a file path which used as CA file to verify server

           at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify
            server

       -ssl_ca_path (STRING, optional)
           Pass a dir which will be used as CA file search dir, found CA file will be used to
           verify server

           On linux, by default is '/etc/ssl/certs/'

           at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify
            server

       - ssl_options (HASHREF, optional)
           Optional arguments to be passed to the IO::Socket::SSL object.

       - uid_mode (BOOL, optional, default TRUE)
           Whether to use UID command (see RFC3501).  Recommended.

       - socket (IO::Handle, optional)
           If you already have a socket connected to the IMAP server, you can pass it here.

       The ssl_ca_file and ssl_ca_path only need when you set ssl_verify_peer to TRUE.

       If you havn't apply an ssl_ca_file and ssl_ca_path, on linux, the ssl_ca_path will use the
       value '/etc/ssl/certs/', on other platform ssl_verify_peer will be disabled.

       The constructor doesn't login to the IMAP server -- you need to call $imap->login for
       that.

   last_error
       Returns the last error from the IMAP server.

   login($user, $pass)
       Login to the IMAP server.  You can pass $user and $pass here if you wish; if not passed,
       the values used in constructor will be used.

       Returns undef if login failed.

   logout / quit
       Send EXPUNGE and LOGOUT then close connection.  "quit" is an alias for "logout".

   noop
       "Do nothing" method that calls the IMAP "NOOP" command.  It returns a true value upon
       success, undef otherwise.

       This method fetches any notifications that the server might have for us and you can get
       them by calling $imap->notifications.  See the "notifications()" method.

   capability() / capability(qr/^SOMETHING/)
       With no arguments, returns an array of all capabilities advertised by the server.  If
       you're interested in a certain capability you can pass a RegExp.  E.g. to check if this
       server knows 'SORT', you can do this:

           if ($imap->capability(/^sort$/i)) {
               # speaks it
           }

       This data is cached, the server will be only hit once.

   select($folder)
       Selects the current IMAP folder.  On success this method also records some information
       about the selected folder in a hash stored in $self->{FOLDERS}{$folder}.  You might want
       to use Data::Dumper to find out exactly what, but at the time of this writing this is:

       - messages
           Total number of messages in this folder

       - flags
           Flags available for this folder (as array ref)

       - recent
           Total number of recent messages in this folder

       - sflags
           Various other flags here, such as PERMANENTFLAGS of UIDVALIDITY.  You might want to
           take a look at RFC3501 at this point. :-p

       This method is basically stolen from Net::IMAP::Simple.

   examine($folder)
       Selects the current IMAP folder in read-only (EXAMINE) mode.  Otherwise identical to
       select.

   status($folder), status(\@folders)
       Returns the status of the given folder(s).

       If passed an array ref, the return value is a hash ref mapping folder name to folder
       status (which are hash references in turn).  If passed a single folder name, it returns
       the status of that folder only.

           my $inbox = $imap->status('INBOX');
           print $inbox->{UNSEEN}, $inbox->{MESSAGES};
           print Data::Dumper::Dumper($inbox);

           my $all = $imap->status($imap->folders);
           while (my ($name, $status) = each %$all) {
               print "$name : $status->{MESSAGES}/$status->{UNSEEN}\n";
           }

       This method is designed to be very fast when passed multiple folders.  It's a lot faster
       to call:

           $imap->status(\@folders);

       than:

           $imap->status($_) foreach (@folders);

       because it sends all the STATUS requests to the IMAP server before it starts receiving the
       answers.  In my tests with my remote IMAP server, for 40 folders this method takes 0.6
       seconds, compared to 6+ seconds when called individually for each folder alone.

   separator
       Returns the folder hierarchy separator.  This is provided as a result of the following
       IMAP command:

           FETCH "" "*"

       I don't know of any way to change this value on a server so I have to assume it's a
       constant.  Therefore, this method caches the result and it won't hit the server a second
       time on subsequent calls.

   folders
       Returns a list of all folders available on the server.  In scalar context it returns a
       reference to an array, i.e.:

           my @a = $imap->folders;
           my $b = $imap->folders;
           # now @a == @$b;

   folders_more
       Returns an hash reference containing more information about folders.  It maps folder name
       to an hash ref containing the following:

         - flags -- folder flags (array ref; i.e. [ '\\HasChildren' ])
         - sep   -- one character containing folder hierarchy separator
         - name  -- folder name (same as the key -- thus redundant)

   namespace
       Returns an hash reference containing the namespaces for this server (see RFC 2342).  Since
       the RFC defines 3 possible types of namespaces, the hash contains the following keys:

        - `personal' -- the personal namespace
        - `other' -- "other users" namespace
        - `shared' -- shared namespace

       Each one can be undef if the server returned "NIL", or an array reference.  If an array
       reference, each element is in the form:

        {
           sep    => '.',
           prefix => 'INBOX.'
        }

       (sep is the separator for this hierarchy, and prefix is the prefix).

   seq_to_uid(@sequence_ids)
       I recommend usage of UID-s only (see "uid_mode") but this isn't always possible.  Even
       when "uid_mode" is on, the server will sometimes return notifications that only contain
       message sequence numbers.  To convert these to UID-s you can use this method.

       On success it returns an hash reference which maps sequence numbers to message UID-s.  Of
       course, on failure it returns undef.

   search($criteria, $sort, $charset)
       Executes the "SEARCH" or "SORT" IMAP commands (depending on wether $sort is undef) and
       returns the results as an array reference containing message ID-s.

       Note that if you use $sort and the IMAP server doesn't have this capability, this method
       will fail.  Use "capability" to investigate.

       - $criteria
           Can be a string, in which case it is passed literally to the IMAP command (which can
           be "SEARCH" or "SORT").

           It can also be an hash reference, in which case keys => values are collected into a
           string and values are properly quoted, i.e.:

              { subject => 'foo',
                from    => 'bar' }

           will translate to:

              'SUBJECT "foo" FROM "bar"'

           which is a valid IMAP SEARCH query.

           If you want to retrieve all messages (no search criteria) then pass 'ALL' here.

       - $sort
           Can be a string or an array reference.  If it's an array, it will simply be joined
           with a space, so for instance passing the following is equivalent:

               'SUBJECT DATE'
               [ 'SUBJECT', 'DATE' ]

           The SORT command in IMAP allows you to prefix a sort criteria with 'REVERSE' which
           would mean descending sorting; this module will allow you to prefix it with '^', so
           again, here are some equivalent constructs:

               'SUBJECT REVERSE DATE'
               'SUBJECT ^DATE'
               [ 'SUBJECT', 'REVERSE', 'DATE' ]
               [ 'subject', 'reverse date' ]
               [ 'SUBJECT', '^DATE' ]

           It'll also uppercase whatever you passed here.

           If you omit $sort (or pass undef) then this method will use the SEARCH command.
           Otherwise it uses the SORT command.

       - $charset
           The IMAP SORT recommendation [2] requires a charset declaration for SORT, but not for
           SEARCH.  Interesting, huh?

           Our module is a bit more paranoid and it will actually add charset for both SORT and
           SEARCH.  If $charset is omitted (or undef) the it will default to "UTF-8", which,
           supposedly, is supported by all IMAP servers.

   get_rfc822_body($msg_id)
       Fetch and return the full RFC822 body of the message.  $msg_id can be a scalar but also an
       array of ID-s.  If it's an array, then all bodies of those messages will be fetched and
       the return value will be a list or an array reference (depending how you call it).

       Note that the actual data is returned as a reference to a scalar, to speed things up.

       Examples:

           my $data = $imap->get_rfc822_body(10);
           print $$data;   # need to dereference it

           my @more = $imap->get_rfc822_body([ 11, 12, 13 ]);
           print $$_ foreach @more;

               or

           my $more = $imap->get_rfc822_body([ 11, 12, 13 ]);
           print $$_ foreach @$more;

   get_part_body($msg_id, $part_id)
       Fetches and returns the body of a certain part of the message.  Part ID-s look like '1' or
       '1.1' or '2.3.1' etc. (see RFC3501 [1], "FETCH Command").

       Scalar reference

       Note that again, this data is returned as a reference to a scalar rather than the scalar
       itself.  This decision was taken purely to save some time passing around potentially large
       data from Perl subroutines.

       Undecoded

       One other thing to note is that the data is not decoded.  One simple way to decode it is
       use Email::MIME::Encodings, i.e.:

           use Email::MIME::Encodings;
           my $summary = $imap->get_summaries(10)->[0];
           my $part = $summary->get_subpart('1.1');
           my $body = $imap->get_part_body('1.1');
           my $cte = $part->transfer_encoding;  # Content-Transfer-Encoding
           $body = Email::MIME::Encodings::decode($cte, $$body);

           # and now you should have the undecoded (perhaps binary) data.

       See get_summaries below.

   get_parts_bodies($msg_id, \@part_ids)
       Similar to get_part_body, but this method is capable to retrieve more parts at once.  It's
       of course faster than calling get_part_body for each part alone.  Returns an hash
       reference which maps part ID to part body (the latter is a reference to a scalar
       containing the actual data).  Again, the data is not unencoded.

           my $parts = $imap->get_parts_bodies(10, [ '1.1', '1.2', '2.1' ]);
           print ${$parts->{'1.1'}};

   get_summaries($msg, $headers) / get_summaries(\@msgs, $headers)
       ($headers is optional).

       Fetches, parses and returns "message summaries".  $msg can be an array ref, or a single
       id.  The return value is always an array reference, even if a single message is queried.

       If $headers is passed, it must be a string containing name(s) of the header fields to
       fetch (space separated).  Example:

           $imap->get_summaries([1, 2, 3], 'References X-Original-To')

       The result contains Net::IMAP::Client::MsgSummary objects.  The best way to understand the
       result is to actually call this function and use Data::Dumper to see its structure.

       Following is the output for a pretty complicated message, which contains an HTML part with
       an embedded image and an attached message.  The attached message in turn contains an HTML
       part and an embedded message.

         bless( {
           'message_id' => '<48A71D17.1000109@foobar.com>',
           'date' => 'Sat, 16 Aug 2008 21:31:51 +0300',
           'to' => [
               bless( {
                   'at_domain_list' => undef,
                   'name' => undef,
                   'mailbox' => 'kwlookup',
                   'host' => 'foobar.com'
               }, 'Net::IMAP::Client::MsgAddress' )
           ],
           'cc' => undef,
           'from' => [
               bless( {
                   'at_domain_list' => undef,
                   'name' => 'Mihai Bazon',
                   'mailbox' => 'justme',
                   'host' => 'foobar.com'
               }, 'Net::IMAP::Client::MsgAddress' )
           ],
           'flags' => [
               '\\Seen',
               'NonJunk',
               'foo_bara'
           ],
           'uid' => '11',
           'subject' => 'test with message attachment',
           'rfc822_size' => '12550',
           'in_reply_to' => undef,
           'bcc' => undef,
           'internaldate' => '16-Aug-2008 21:29:23 +0300',
           'reply_to' => [
               bless( {
                   'at_domain_list' => undef,
                   'name' => 'Mihai Bazon',
                   'mailbox' => 'justme',
                   'host' => 'foobar.com'
               }, 'Net::IMAP::Client::MsgAddress' )
           ],
           'sender' => [
               bless( {
                   'at_domain_list' => undef,
                   'name' => 'Mihai Bazon',
                   'mailbox' => 'justme',
                   'host' => 'foobar.com'
               }, 'Net::IMAP::Client::MsgAddress' )
           ],
           'parts' => [
               bless( {
                   'part_id' => '1',
                   'parts' => [
                       bless( {
                           'parameters' => {
                               'charset' => 'UTF-8'
                           },
                           'subtype' => 'html',
                           'part_id' => '1.1',
                           'encoded_size' => '365',
                           'cid' => undef,
                           'type' => 'text',
                           'description' => undef,
                           'transfer_encoding' => '7bit'
                       }, 'Net::IMAP::Client::MsgSummary' ),
                       bless( {
                           'disposition' => {
                               'inline' => {
                                   'filename' => 'someimage.png'
                               }
                           },
                           'language' => undef,
                           'encoded_size' => '4168',
                           'description' => undef,
                           'transfer_encoding' => 'base64',
                           'parameters' => {
                               'name' => 'someimage.png'
                           },
                           'subtype' => 'png',
                           'part_id' => '1.2',
                           'type' => 'image',
                           'cid' => '<part1.02030404.05090202@foobar.com>',
                           'md5' => undef
                       }, 'Net::IMAP::Client::MsgSummary' )
                   ],
                   'multipart_type' => 'related'
               }, 'Net::IMAP::Client::MsgSummary' ),
               bless( {
                   'message_id' => '<48A530CE.3050807@foobar.com>',
                   'date' => 'Fri, 15 Aug 2008 10:31:26 +0300',
                   'encoded_size' => '6283',
                   'to' => [
                       bless( {
                           'at_domain_list' => undef,
                           'name' => undef,
                           'mailbox' => 'kwlookup',
                           'host' => 'foobar.com'
                       }, 'Net::IMAP::Client::MsgAddress' )
                   ],
                   'subtype' => 'rfc822',
                   'cc' => undef,
                   'from' => [
                       bless( {
                           'at_domain_list' => undef,
                           'name' => 'Mihai Bazon',
                           'mailbox' => 'justme',
                           'host' => 'foobar.com'
                       }, 'Net::IMAP::Client::MsgAddress' )
                   ],
                   'subject' => 'Test with images',
                   'in_reply_to' => undef,
                   'description' => undef,
                   'transfer_encoding' => '7bit',
                   'parameters' => {
                       'name' => 'Attached Message'
                   },
                   'bcc' => undef,
                   'part_id' => '2',
                   'sender' => [
                       bless( {
                           'at_domain_list' => undef,
                           'name' => 'Mihai Bazon',
                           'mailbox' => 'justme',
                           'host' => 'foobar.com'
                       }, 'Net::IMAP::Client::MsgAddress' )
                   ],
                   'reply_to' => [
                       bless( {
                           'at_domain_list' => undef,
                           'name' => 'Mihai Bazon',
                           'mailbox' => 'justme',
                           'host' => 'foobar.com'
                       }, 'Net::IMAP::Client::MsgAddress' )
                   ],
                   'parts' => [
                       bless( {
                           'parameters' => {
                               'charset' => 'UTF-8'
                           },
                           'subtype' => 'html',
                           'part_id' => '2.1',
                           'encoded_size' => '344',
                           'cid' => undef,
                           'type' => 'text',
                           'description' => undef,
                           'transfer_encoding' => '7bit'
                       }, 'Net::IMAP::Client::MsgSummary' ),
                       bless( {
                           'disposition' => {
                               'inline' => {
                                   'filename' => 'logo.png'
                               }
                           },
                           'language' => undef,
                           'encoded_size' => '4578',
                           'description' => undef,
                           'transfer_encoding' => 'base64',
                           'parameters' => {
                               'name' => 'logo.png'
                           },
                           'subtype' => 'png',
                           'part_id' => '2.2',
                           'type' => 'image',
                           'cid' => '<part1.02060209.09080406@foobar.com>',
                           'md5' => undef
                       }, 'Net::IMAP::Client::MsgSummary' )
                   ],
                   'cid' => undef,
                   'type' => 'message',
                   'multipart_type' => 'related'
               }, 'Net::IMAP::Client::MsgSummary' )
           ],
           'multipart_type' => 'mixed'
         }, 'Net::IMAP::Client::MsgSummary' );

       As you can see, the parser retrieves all data, including from the embedded messages.

       There are many other modules you can use to fetch such information.  Email::Simple and
       Email::MIME are great.  The only problem is that you have to have fetched already the full
       (RFC822) body of the message, which is impractical over IMAP.  When you want to quickly
       display a folder summary, the only practical way is to issue a FETCH command and retrieve
       only those headers that you are interested in (instead of full body).  "get_summaries"
       does exactly that (issues a FETCH (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE
       BODYSTRUCTURE)).  It's acceptably fast even for huge folders.

   fetch($msg_id, $attributes)
       This is a low level interface to FETCH.  It calls the imap FETCH command and returns a
       somewhat parsed hash of the results.

       $msg_id can be a single message ID or an array of IDs.  If a single ID is given, the
       return value will be a hash reference containing the requested values.  If $msg_id is an
       array, even if it contains a single it, then the return value will be an array of hashes.

       $attributes is a string of attributes to FETCH, separated with a space, or an array (ref)
       of attributes.

       Examples:

       # retrieve the UID of the most recent message

           my $last_uid = $imap->fetch('*', 'UID')->{UID};

       # fetch the flags of the first message

           my $flags = $imap->fetch(1, 'FLAGS')->{FLAGS};

       # fetch flags and some headers (Subject and From)

           my $headers = 'BODY[HEADER.FIELDS (Subject From)]';
           my $results = $imap->fetch([1, 2, 3], "FLAGS $headers");
           foreach my $hash (@$results) {
               print join(" ", @{$hash->{FLAGS}}), "\n";
               print $hash->{$headers}, "\n";
           }

   notifications()
       The IMAP server may send various notifications upon execution of commands.  They are
       collected in an array which is returned by this method (returns an array ref in scalar
       context, or a list otherwise).  It clears the notifications queue so on second call it
       will return an empty array (unless new notifications were collected in the meantime).

       Each element in this array (notification) is a hash reference containing one or more or
       the following:

         - seq       : the *sequence number* of the changed message
         - uid       : UID of the changed message (NOT ALWAYS available!)
         - flags     : new flags for this message
         - deleted   : when the \Deleted flag was set for this message
         - messages  : new number of messages in this folder
         - recent    : number of recent messages in this folder
         - flags     : new flags of this folder (seq is missing)
         - destroyed : when this message was expunged
         - folder    : the name of the selected folder

       "folder" is always present.  "seq" is present when a message was changed some flags (in
       which case you have "flags") or was expunged (in which case "destroyed" is true).  When
       "flags" were changed and the \Deleted flag is present, you also get "deleted" true.

       "seq" is a message sequence number.  Pretty dumb, I think it's preferable to work with
       UID-s, but that's what the IMAP server reports.  In some cases the UID might be readily
       available (i.e. my IMAP server sends notifications in the same body as a response to, say,
       a FETCH BODY command), but when it's not, you have to rely on seq_to_uid().  Note that
       when "destroyed" is true, the message has been expunged; there is no way in this case to
       retrieve the UID so you have to rely solely on "seq" in order to update your caches.

       When "flags" is present but no "seq", it means that the list of available flags for the
       "folder" has changed.

       You get "messages" upon an "EXISTS" notification, which usually means "you have new mail".
       It indicates the total number of messages in the folder, not just "new" messages.  I've
       yet to come up with a good way to measure the number of new/unseen messages, other than
       calling "status($folder)".

       I rarely got "recent" from my IMAP server in my tests; if more clients are simultaneously
       logged in as the same IMAP user, only one of them will receive "RECENT" notifications;
       others will have to rely on "EXISTS" to tell when new messages have arrived.  Therefore I
       can only say that "RECENT" is useless and I advise you to ignore it.

   append($folder, \$rfc822, $flags, $date)
       Appends a message to the given $folder.  You must pass the full RFC822 body in $rfc822.
       $flags and $date are optional.  If you pass $flags, it must be an array of strings
       specifying the initial flags of the appended message.  If undef, the message will be
       appended with an empty flag set, which amongst other things means that it will be regarded
       as an "\Unseen" message.

       $date specifies the INTERNALDATE of the appended messge.  If undef it will default to the
       current date/time.  NOTE: this functionality is not tested; $date should be in a format
       understood by IMAP.

   get_flags($msg_id) / get_flags(\@msg_ids)
       Returns the flags of one or more messages.  The return value is an array (reference) if
       one message ID was passed, or a hash reference if an array (of one or more) message ID-s
       was passed.

       When an array was passed, the returned hash will map each message UID to an array of
       flags.

   store($msg, $flag) / store(\@msgs, \@flags)
       Resets FLAGS of the given message(s) to the given flag(s).  $msg can be an array of ID-s
       (or UID-s), or a single (U)ID.  $flags can be a single string, or an array reference as
       well.

       Note that the folder where these messages reside must have been already selected.

       Examples:

           $imap->store(10, '\\Seen');
           $imap->store([11, 12], '\\Deleted');
           $imap->store(13, [ '\\Seen', '\\Answered' ]);

       The IMAP specification defines certain reserved flags (they all start with a backslash).
       For example, a message with the flag "\Deleted" should be regarded as deleted and will be
       permanently discarded by an EXPUNGE command.  Although, it is possible to "undelete" a
       message by removing this flag.

       The following reserved flags are defined by the IMAP spec:

           \Seen
           \Answered
           \Flagged
           \Deleted
           \Draft
           \Recent

       The "\Recent" flag is considered "read-only" -- you cannot add or remove it manually; the
       server itself will do this as appropriate.

   add_flags($msg, $flag) / add_flags(\@msgs, \@flags)
       Like store() but it doesn't reset all flags -- it just specifies which flags to add to the
       message.

   del_flags($msg, $flag) / del_flags(\@msgs, \@flags)
       Like store() / add_flags() but it removes flags.

   delete_message($msg) / delete_message(\@msgs)
       Stores the \Deleted flag on the given message(s).  Equivalent to:

           $imap->add_flags(\@msgs, '\\Deleted');

   expunge()
       Permanently removes messages that have the "\Deleted" flag set from the current folder.

   copy($msg, $folder) / copy(\@msg_ids, $folder)
       Copies message(s) from the selected folder to the given $folder.  You can pass a single
       message ID, or an array of message ID-s.

   create_folder($folder)
       Creates the folder with the given name.

   delete_folder($folder)
       Deletes the folder with the given name.  This works a bit different from the IMAP specs.
       The IMAP specs says that any subfolders should remain intact.  This method actually
       deletes subfolders recursively.  Most of the time, this is What You Want.

       Note that all messages in $folder, as well as in any subfolders, are permanently lost.

   get_threads($algorithm, $msg_id)
       Returns a "threaded view" of the current folder.  Both arguments are optional.

       $algorithm should be undef, "REFERENCES" or "SUBJECT".  If undefined, "REFERENCES" is
       assumed.  This selects the threading algorithm, as per IMAP THREAD AND SORT extensions
       specification.  I only tested "REFERENCES".

       $msg_id can be undefined, or a message ID.  If it's undefined, then a threaded view of the
       whole folder will be returned.  If you pass a message ID, then this method will return the
       top-level thread that contains the message.

       The return value is an array which actually represents threads.  Elements of this array
       are message ID-s, or other arrays (which in turn contain message ID-s or other arrays,
       etc.).  The first element in an array will represent the start of the thread.  Subsequent
       elements are child messages or subthreads.

       An example should help (FIXME).

TODO

       - authentication schemes other than plain text (help wanted)
       - better error handling?

SEE ALSO

       Net::IMAP::Simple, Mail::IMAPClient, Mail::IMAPTalk

       Email::Simple, Email::MIME

       RFC3501 [1] is a must read if you want to do anything fancier than what this module
       already supports.

REFERENCES

       [1] http://ietfreport.isoc.org/rfc/rfc3501.txt

       [2] http://ietfreport.isoc.org/all-ids/draft-ietf-imapext-sort-20.txt

AUTHOR

       Mihai Bazon, <mihai.bazon@gmail.com>
           http://www.xuheki.com/
           http://www.dynarchlib.com/
           http://www.bazon.net/mishoo/

COPYRIGHT

       Copyright (c) Mihai Bazon 2008.  All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

DISCLAIMER OF WARRANTY

       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE,
       TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
       COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF
       ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
       THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE
       DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
       HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY
       THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
       INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
       LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY
       OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
       SUCH DAMAGES.