=encoding utf-8

=head1 NAME

Net::IMAP::Simple - Perl extension for simple IMAP account handling.

=head1 SYNOPSIS

    use strict;
    use warnings;
    use Net::IMAP::Simple;
    use Email::Simple;

    # Create the object
    my $imap = Net::IMAP::Simple->new('imap.example.com') ||
       die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";

    # Log on
    if(!$imap->login('user','pass')){
        print STDERR "Login failed: " . $imap->errstr . "\n";
        exit(64);
    }

    # Print the subject's of all the messages in the INBOX
    my $nm = $imap->select('INBOX');

    for(my $i = 1; $i <= $nm; $i++){
        if($imap->seen($i)){
            print "*";
        } else {
            print " ";
        }

        my $es = Email::Simple->new(join '', @{ $imap->top($i) } );

        printf("[%03d] %s\n", $i, $es->header('Subject'));
    }

    $imap->quit;

=head1 DESCRIPTION

This module is a simple way to access IMAP accounts.

=head1 OBJECT CREATION METHOD

    my $imap = Net::IMAP::Simple->new( $server [ :port ]);

    # OR

    my $imap = Net::IMAP::Simple->new( $server [, option_name => option_value ] );

=head2 new

This class method constructs a new L<Net::IMAP::Simple> object. It takes one
required parameter which is the server to connect to, and additional optional
parameters.

The server parameter may specify just the server, or both the server and port
number. To specify an alternate port, separate it from the server with a colon
(C<:>), C<example.com:5143>.

On success an object is returned. On failure, nothing is returned and an error
message is set to C<$Net::IMAP::Simple>.

See L</PREAUTH> below for a special hostname invocation that doesn't use Sockets
(internally).

Options are provided as a hash to C<new()>:

=over 4

=item port => int

Assign the port number (default: 143)

=item timeout => int (default: 90)

Connection timeout in seconds.

=item retry => int (default: 1)

Attempt to retry the connection attmpt (x) times before giving up

=item retry_delay => int (default: 5)

Wait (x) seconds before retrying a connection attempt

=item use_v6 => BOOL

If set to true, attempt to use IPv6 sockets rather than IPv4 sockets.

This option requires the L<IO::Socket::INET6> module

=item use_ssl => BOOL

If set to true, attempt to use L<IO::Socket::SSL> sockets rather than vanilla sockets.

Note that no attempt is made to check the certificate validity by default.  This
is terrible personal security but matches the previous behavior of this module.
Please consider using C<find_ssl_defaults> below.

This option requires the L<IO::Socket::SSL> module

=item ssl_version => version

This should be one or more of the following (space separated): SSLv3 SSLv2
TLSv1.  If you specify, for example, "SSLv3 SSLv2" then L<IO::Socket::SSL> will
attempt auto negotiation.  At the time of this writing, the default string was
v3/v2 auto negotiation -- it may have changed by the time you read this.

Warning: setting this will also set C<use_ssl>.

=item find_ssl_defaults => []

Looks in some standard places for CA certificate libraries and if found sets
reasonable defaults along the lines of the following.

    ssl_options => [ SSL_ca_path => "/etc/ssl/certs/",
        SSL_verify_mode => IO::Socket::SSL::SSL_VERIFY_PEER() ]

Warning: setting this will also set C<use_ssl>.

=item ssl_options => []

You may provide your own L<IO::Socket::SSL> options if you desire to do so.
It is completely overridden by C<find_ssl_defaults> above.

=item bindaddr => str

Assign a local address to bind

=item use_select_cache => BOOL

Enable C<select()> caching internally

=item select_cache_ttl => int

The number of seconds to allow a select cache result live before running
C<< $imap->select() >> again.

=item debug => BOOL | \*HANDLE | warn | file:name

Enable debugging output. If C<\*HANDLE> is a valid file handle, debugging will
be written to it.  If it is the string C<"warn"> then the debugging will be
written using the L<warn> command.  If it is a string of the form C<file:name>
then the named file will be opened for append and the debugs written to it.
Otherwise debugging will be written to C<STDOUT>

=item readline_callback => CODE

You may choose to pass a callback function for the purpose of pre-processing
lines before they are handed to the rest of the L<Net::IMAP::Simple> internals.
This can be handy for animating a spinner or modifying the IMAP behavior.

=back

=head1 PREAUTH

Rather than passing a port number and issuing a login, in some situations it may
be convenient to authenticate with (for example) ssh and simply invoke (for
example) dovecot by hand.

If the server name starts with C<cmd:>, then L<Net::IMAP::Simple> will issue the
command rather than building sockets.  This is a typical setup:

    my $cmd = "ssh -C mailhost dovecot --exec-mail imap";
    my $imap = Net::IMAP::Simple->new("cmd:$cmd");
     # $imap->login(); ... don't need this

    my $number_of_messages = $imap->select("INBOX");

=head1 METHODS

=over 4

=item starttls

    $imap->starttls;

If you start an IMAP session and wish to upgrade to SSL later, you can use this
function to start TLS.  This function will try to C<require> L<IO::Socket::SSL>
and L<Net::SSLeay> at runtime.

=item login

  my $inbox_msgs = $imap->login($user, $passwd);

This method takes two required parameters, a username and password. This pair is
authenticated against the server. If authentication is successful TRUE (1) will
be returned

Nothing is returned on failure and the C<errstr()> error handler is set with the
error message.

=item status

    my $num_messages                     = $imap->status($folder);
    my ($unseen, $recent, $num_messages) = $imap->status($folder);

Issue a C<STATUS> command.  The C<STATUS> command counts messages without
altering the state of the named (optionally) mailbox.  It returns either the
number of messages, or the number of unseen messages, recent, and the total
number of messages.

C<$folder> is an optional argument.  C<status()> will use the current mailbox or
C<INBOX> if the C<$folder> argument is not provided.

This method does not use caching.

This method can also query custom status values.  The first argument to the
function (if any) is assumed to be the folder name, so the folder argument is
required when trying to query custom status values.

    my ($f1, $f2) = $imap->status($folder, qw(f1 f2));
    my $f2        = $imap->status($folder, qw(f1 f2));

=item uidnext

    my $uidnext = $imap->uidnext($folder);

Return the C<UIDNEXT> value for a mailbox.  The C<$folder> argument is optional.
This is really just an alias for

    my $uidnext = $imap->status($folder, qw(uidnext));

with the mild difference that it can compute the folder argument for you

=item uidvalidity

    my $uidvalidity = $imap->uidnext($folder);

Return the C<UIDVALIDITY> value for a mailbox.  The C<$folder> argument is
optional.  This is also an alias for the status call like C<uidnext()> above.

=item uid

This function is actually an alias for C<< $imap->uidsearch($msg_range) >>.

    my($uid)= $imap->uid($msgno);
    my @uid = $imap->uid($msg_range); # eg 4:14  or 15,4,14

Return the C<UID> value(s) for a message.  These unique IDs "I<must>" stay the
same during the session and "I<should>" stay the same between sessions.  Whether
they stay the same depends on the C<UIDVALIDITY> value; see: above and RFC3501.

Warning, although you might thing C<@uid> should contain the C<UID>s for 15,
then 4, then 14 in the example above; most IMAP servers seem to return the UIDs
in increasing order.  Normally the sequence numbers are in increasing order
also, so it all maches up.

    my ($uid4, $uid14, $uid15) = $imap->uid("15,4,14"); # warning

One final note, this gives the size of the search match, not the uid like you
might expect:

    my $uid_search_result_list_size = $imap->uid('3'); # probably always 1

=item seq

    my $seq = $imap->seq($uids);
    my @seq = $imap->seq($uids); # eg 58888:58900

Rather like C<uid()> above, but maps uids to sequence numbers.

=item select

    my $num_messages = $imap->select($folder);

Selects a folder named in the single required parameter. The number of messages
in that folder is returned on success. On failure, nothing is returned  and the
C<errstr()> error handler is set with the error message.

=item examine

This is very nearly a synonym for C<select()>.  The only real difference is that
the EXAMINE command is sent to the server instead of SELECT.
L<Net::IMAP::Simple> is otherwise unaware of the read-only-ness of the mailbox.

=item close

    $imap->close;

Un-selects the current mailbox, leaving no mailbox selected.

=item messages

    print "Messages in Junk Mail -- " . $imap->messages("INBOX.Junk Mail") .  "\n";

This method is an alias for C<< $imap->select >>

=item flags

    print "Available server flags: " . join(", ", $imap->flags) . "\n";

This method accepts an optional folder name and returns the current available
server flags as a list, for the selected folder. If no folder name is provided
the last folder C<< $imap->select >>'ed will be used.

This method uses caching.

=item separator

Returns the folder separator (technically "hierarchy separator", rfc3501§6.3.8)
for the server.

=item recent

    print "Recent messages value: " . $imap->recent . "\n";

This method accepts an optional folder name and returns the 'RECENT' value
provided durning a SELECT result set. If no folder name is provided the last
folder C<< $imap->select >>'ed will be used.

This method uses caching.

See also: L<search>

=item unseen

    print "Unseen messages value: " . $imap->unseen . "\n";

This method accepts an optional folder name and returns the 'UNSEEN' value
provided during a SELECT command result. If no folder name is provided the last
folder C<< $imap->select >>'ed will be used.  If a folder name I<is> provided,
this will issue a SELECT first.

This method uses caching.

If the server does not provide UNSEEN during SELECT -- surprisingly common --
this method will fall back and use STATUS to determine the unseen count.

B<NOTE>: This is not the opposite of L<seen> below.  The UNSEEN value varies
from server to server, but according to the IMAP specification, it should be the
I<number of the first unseen message>, in the case the flag is provided.  (If
the flag is not provided, users would have to use the SEARCH command to find it.)

See also: L<search>

=item current_box

   print "Current Mail Box folder: " . $imap->current_box . "\n";

This method returns the current working mail box folder name.

=item top

    my $header = $imap->top( $message_number ); print for @{$header};

This method accepts a message number as its required parameter. That message
will be retrieved from the currently selected folder. On success this method
returns a list reference containing the lines of the header. Nothing is returned
on failure and the C<errstr()> error handler is set with the error message.

=item seen

    defined( my $seen = $imap->seen( $message_number ) )
        or warn "problem testing for \Seen: "
              . $imap->errstr;

    print "msg #$message_number has been \Seen!" if $seen;

A message number is the only required parameter for this method.  The message's
C<\Seen> flag will be examined and if the message has been seen a true value is
returned.  A defined false value is returned if the message does not have the
C<\Seen> flag set.  The undefined value is returned when an error has occurred
while checking the flag status.

B<NOTE>: This is not the opposite of L<unseen> above.  This issues a C<FETCH>
command and checks to see if the given message has been C<\Seen> before.

=item deleted

    defined( my $deleted = $imap->deleted( $message_number ) )
        or warn "problem testing for \Deleted: "
              . $imap->errstr;

    print "msg #$message_number has been \Deleted!" if $deleted;

A message number is the only required parameter for this method.  The message's
C<\Deleted> flag will be examined and if the message has been deleted a true
value is returned.  A defined false value is returned if the message does not
have the C<\Deleted> flag set.  The undefined value is returned when an error
has occurred while checking the flag status.

=item list

    my $message_size  = $imap->list($message_number);
    my $mailbox_sizes = $imap->list;

This method returns size information for a message, as indicated in the single
optional parameter, or all messages in a mailbox. When querying a single message
a scalar value is returned. When listing the entire mailbox a hash is returned.
On failure, nothing is returned and the C<errstr()> error handler is set with the
error message.

=item fetch

  my $headers = $imap->fetch("1:5")

Fetch the headers for messages 1-5 in the current folder.

  for my $midx ( keys %$headers ) {
      for my $hdr in ($headers->{$midx}) {
          say "$hdr"

          # In many situations the headers will be parsed and may not be simple
          # strings (e.g., with the SimpleX RecDescent parse). The simplest
          # way to get a feel for the output is to use a dumper on it.
      }
  }

=item get

  my $message = $imap->get( $message_number ) or die $imap->errstr;
  my @message_lines = $map->get( $message_number ) or die $imap->errstr;

  my $part = $imap->get( $message_number, '1.1' ) or die $imap->errstr;
  my @part_lines = $imap->get( $message_number, '1.1' ) or die $imap->errstr;

This method fetches a message and returns its lines as an array or, the actual
message.  On failure, either an empty list is returned and the C<errstr()> error
handler is set with the error message.

Optionally, a part can be specified in order to fetch a specific portion of a
message.  This is the raw, encoded body of the message part.  The part number
is a set of zero or more part specifiers delimited by periods.  Every message
has at least one part.  Specifying a part of '1' returns the raw, encoded
body.  This is only useful if you know the header information such as encoding.

Historically, C<get()> returned the array of lines as a reference to the array
instead of returning the message or the array itself.  Please note that it still
does this, although it may be deprecated in the future.

The scalar result returned is actually a blessed arrayref with the stringify
member overloaded.  If you're intending to use the resulting message as a string
more than once, it I<may> make sense to force the stringification first.

    my $message = $imap->get(1);
       $message = "$message"; # force stringification

It is not normally necessary to do this.

=item put

  $imap->put( $mailbox_name, $message, @flags ) or warn $imap->errstr;

Save a message to the server under the folder named C<$mailbox_name>.  You may
optionally specify flags for the mail (e.g. C<\Seen>, C<\Answered>), but they
must start with a slash.

If C<$message> is an arrayref, the lines will be printed correctly.

=item put_with_date

  $imap->put_with_date( $mailbox_name, $message, $date, @flags ) or warn $imap->errstr;

Save a message to the server under the folder named C<$mailbox_name> just like the
put method above, but supplying a date will set the IMAP server internal date for
the message if supported per RFC 3501 Section 6.3.11.

Note when using this with Gmail it expects the date format to be:
DD-Mon-YYYY hh:mm:ss tz  for example  31-Dec-2016 12:59:59 -0500

=item msg_flags

    my @flags = $imap->msg_flags( $message_number );
    my $flags = $imap->msg_flags( $message_number );

    # aught to come out roughly the same
    print "Flags on message #$message_number: @flags\n";
    print "Flags on message #$message_number: $flags\n";

Detecting errors with this member functions is usually desirable.  In the scalar
context, detecting an error is synonymous with testing for defined.

    if( defined( my $flags = $imap->msg_flags($num) ) ) {
        # it has $flags!

    } else {
        warn "problem listing flags for message #$num: "
           . $imap->errstr;
    }

In list context, you must call L<waserr>() to test for success.

    my @flags = $imap->msg_flags($num);
    warn "problem listing flags for msg #$num: "
       . $imap->errstr if $imap->waserr;

=item getfh

  my $file = $imap->getfh( $message_number ); print <$file>;

On success this method returns a file handle pointing to the message identified
by the required parameter. On failure, nothing is returned and the C<errstr()>
error handler is set with the error message.

=item quit

  $imap->quit;

  OR

  $imap->quit(BOOL);

This method logs out of the IMAP server, expunges the selected mailbox, and
closes the connection. No error message will ever be returned from this method.

Optionally if BOOL is TRUE (1) then a hard quit is performed which closes the
socket connection. This hard quit will still issue both EXPUNGE and LOGOUT
commands however the response is ignored and the socket is closed after issuing
the commands.

=item logout

  $imap->logout;

This method is just like the quit method except that it does not have a hard
quit option and it does not expunge the mailbox before it hangs up and closes
the socket.

=item last

  my $message_number = $imap->last;

This method returns the message number of the last message in the selected
mailbox, since the last time the mailbox was selected. On failure, nothing is
returned and the C<errstr()> error handler is set with the error message.

=item delete

  print "Gone!" if $imap->delete( $message_number );

This method sets the C<\Deleted> flag on the given message (or messages). On
success it returns true, false on failure and the C<errstr()> error handler is
set with the error message.  If the flag was already there, no error is
produced.  I takes either a message number or L<sequence set> as the only
argument.  Note that messages aren't actually deleted until they are expunged
(see L<expunge_mailbox>).

=item undelete

  print "Resurrected!" if $imap->undelete( $message_number );

This method removes the C<\Deleted> flag on the given message. On success it
returns true, false on failure and the C<errstr()> error handler is set with the
error message.  If the flag wasn't there, no error is produced.

=item see

  print "You've seen message #$msgno" if $imap->see( $messageno );

This method sets the C<\Seen> flag on the given message. On success it returns
true, false on failure and the C<errstr()> error handler is set with the error
message.  If the flag was already there, no error is produced.

=item unsee

  print "You've not seen message #$msgno" if $imap->unsee( $messageno );

This method removes the C<\Seen> flag on the given message. On success it
returns true, false on failure and the C<errstr()> error handler is set with the
error message.  If the flag wasn't there, no error is produced.

=item add_flags

L<delete> and L<see> above really just call this function for those flags.

   $imap->add_flags( $msgno, qw(\Seen \Deleted) )
        or die $imap->errstr;

=item sub_flags

L<unsee> above really just calls this function for that flag.

   $imap->sub_flags( $msgno, '\Seen' ) or die $imap->errstr;

=item mailboxes

  my @boxes   = $imap->mailboxes;
  my @folders = $imap->mailboxes("Mail/%");
  my @lists   = $imap->mailboxes("lists/perl/*", "/Mail/");

This method returns a list of mailboxes. When called with no arguments it
recurses from the IMAP root to get all mailboxes. The first optional argument is
a mailbox path and the second is the path reference. RFC 3501 section 6.3.8 has
more information.

On failure nothing is returned and the C<errstr()> error handler is set with the
error message.

=item mailboxes_subscribed

  my @boxes   = $imap->mailboxes_subscribed;
  my @folders = $imap->mailboxes_subscribed("Mail/%");
  my @lists   = $imap->mailboxes_subscribed("lists/perl/*", "/Mail/");

This method returns a list of mailboxes subscribed to. When called with no
arguments it recurses from the IMAP root to get all mailboxes. The first
optional argument is a mailbox path and the second is the path reference. RFC
3501 has more information.

On failure nothing is returned and the C<errstr()> error handler is set with the
error message.

=item create_mailbox

  print "Created" if $imap->create_mailbox( "/Mail/lists/perl/advocacy" );

This method creates the mailbox named in the required argument. Returns true on
success, false on failure and the C<errstr()> error handler is set with the error
message.

=item expunge_mailbox

  my @expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );
  die $imap->errstr if $imap->waserr;

  my $expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" )
      or die $imap->errstr;

This method removes all mail marked as deleted in the mailbox named in the
required argument. Returns either the number of messages that were expunged, or
the indexes of those messages -- which has a questionable usefulness since it
tends to return numbers that don't relate to the message numbers marked with the
C<\Deleted> flags.

If 0 messages were expunged without error, the function will return C<0E0> so it
will still test true, but also evaluate to 0.

In list context, you must call L<waserr>() to test for success.

=item delete_mailbox

  print "Deleted" if $imap->delete_mailbox( "/Mail/lists/perl/advocacy" );

This method deletes the mailbox named in the required argument. Returns true on
success, false on failure and the C<errstr()> error handler is set with the error
message.

=item rename_mailbox

  print "Renamed" if $imap->rename_mailbox( $old => $new );

This method renames the mailbox in the first required argument to the mailbox
named in the second required argument. Returns true on success, false on failure
and the C<errstr()> error handler is set with the error message.

=item folder_subscribe

  print "Subscribed" if $imap->folder_subscribe( "/Mail/lists/perl/advocacy" );

This method subscribes to the folder. Returns true on success, false on failure
and the C<errstr()> error handler is set with the error message.

=item folder_unsubscribe

  print "Unsubscribed" if $imap->folder_unsubscribe( "/Mail/lists/perl/advocacy" );

This method un-subscribes to the folder. Returns true on success, false on
failure and the C<errstr()> error handler is set with the error message.

=item copy

  print "copied" if $imap->copy( $message_number, $mailbox );

This method copies the message number (or L<sequence set>) in the currently
selected mailbox to the folder specified in the second argument.  Both arguments
are required.  On success this method returns true. Returns false on failure and
the C<errstr()> error handler is set with the error message.

=item uidcopy

  print "copied" if $imap->uidcopy( $message_uid, $mailbox );

This method is identical to C<copy()> above, except that it uses UID numbers
instead of sequence numbers.

=item noop

  $imap->noop;

Performs a null operation.  This may be needed to get updates on a
mailbox, or ensure that the server does not close the connection as
idle.  RFC 3501 states that servers' idle timeouts must not be less
than 30 minutes.

=item errstr

 print "Login ERROR: " . $imap->errstr . "\n" if !$imap->login($user, $pass);

Return the last error string captured for the last operation which failed.

=item waserr

 my @flags = $imap->msg_flags(14);
 die $imap->errstr if $imap->waserr;

Because C<msg_flags()> can optionally return a list, it's not really possible to
detect failure in list context.  Therefore, you must call C<waserr()> if you
wish to detect errors.

Few of the L<Net::IMAP::Simple> methods use C<waserr()>.  The ones that do will
mention it.

=item list2range

Sometimes you have a long list of sequence numbers which are consecutive
and really want to be an IMAP-style range.

    my @list  = (5..9, 13..38, 55,56,57);
    my $short = $imap->list2range(@list);

    # $short how says: 5:9,13:38,55:57

=item range2list

Pretty much the opposite of C<list2range>.

    my @list = $imap->range2list("1,3,5:9");
    # @list is (1,3,5,6,7,8,9);

=back

=head1 SEARCHING

=over 4

=item search

This function returns an array of message numbers (in list context) or the
number of matched messages (in scalar context).  It takes a single argument: the
search.

IMAP searching can be a little confusing and this function makes no attempt to
parse your searches.  If you wish to do searches by hand, please see RFC 3501.

IMAP sorting (see RFC 5256) is supported via an optional second argument.  The
RFC requires the charset be specified, which can be provided via the optional
third argument (defaults to UTF-8).

Here are a few examples:

    my @ids = $imap->search("UNSEEN");
    my @ids = $imap->search('SUBJECT "blarg is \"blarg\""');
    my @ids = $imap->search('FROM "joe@aol.com"');
    my @ids = $imap->search("DELETED");

    # example from RFC 3501, search terms are ANDed together
    my @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"');
    # example from RFC 3501, search terms are ORed together
    my @ids = $imap->search('OR BODY "blard" SUBJECT "blarg"');

    # flagged and ( since x or !from y ):
    my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
      # no typo above, see the RFC

    # example from RFC 5256, sorted by subject and reverse date
    my @ids = $imap->search('BODY "zaphod"', 'SUBJECT REVERSE DATE');


Since this module is meant to be simple, L<Net::IMAP::Simple> has a few search
helpers.  If you need fancy booleans and things, you'll have to learn search.
If you need a quick search for unseen messages, see below.

These all return an array of messages or count of messages exactly as the search
function does.  Some of them take arguments, some do not.  They do try to grok
your arguments slightly, the mechanics of this (if any) will be mentioned below.

=over 4

=item search_seen

Returns numbers of messages that have the \Seen flag.

=item search_recent

Returns numbers of messages that have the \Recent flag.

=item search_answered

Returns numbers of messages that have the \Answered flag.

=item search_deleted

Returns numbers of messages that have the \Deleted flag.

=item search_flagged

Returns numbers of messages that have the \Flagged flag.

=item search_draft

Returns numbers of messages that have the \Draft flag.

=item search_unseen

Returns numbers of messages that do not have the \Seen flag.

=item search_old

Returns numbers of messages that do not have the \Recent flag.

=item search_unanswered

Returns numbers of messages that do not have the \Answered flag.

=item search_undeleted

Returns numbers of messages that do not have the \Deleted flag.

=item search_unflagged

Returns numbers of messages that do not have the \Flagged flag.

=item search_smaller

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that are smaller than C<< <x> >> octets.  This function will try to
force your argument to be a number before passing it to the IMAP server.

=item search_larger

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that are larger than C<< <x> >> octets.  This function will try to
force your argument to be a number before passing it to the IMAP server.

=item search_from

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the from header.  This function will attempt
to force your string into the RFC3501 quoted-string format.

=item search_to

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the to header.  This function will attempt
to force your string into the RFC3501 quoted-string format.

=item search_cc

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the cc header.  This function will attempt
to force your string into the RFC3501 quoted-string format.

=item search_bcc

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the bcc header.  This function will attempt
to force your string into the RFC3501 quoted-string format.

=item search_subject

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the subject header.  This function will attempt
to force your string into the RFC3501 quoted-string format.

=item search_body

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have C<< <x> >> in the message body.  This function will
attempt to force your string into the RFC3501 quoted-string format.

=item search_before

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that were received before C<< <x> >>.  If you have L<Date::Manip>
installed (optional), this function will attempt to force the date into the
format C<%d-%b-%Y> (date-monthName-year) as RFC3501 requires.  If you do not
have that module, no attempt will be made to coerce your date into the correct
format.

=item search_since

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that were received after C<< <x> >>.  If you have L<Date::Manip>
installed (optional), this function will attempt to force the date into the
format C<%d-%m-%Y> (date-month-year) as RFC3501 requires.  If you do not have
that module, no attempt will be made to coerce your date into the correct
format.

=item search_sent_before

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have a header date before C<< <x> >>.  If you have L<Date::Manip>
installed (optional), this function will attempt to force the date into the
format C<%d-%m-%Y> (date-month-year) as RFC3501 requires.  If you do not have
that module, no attempt will be made to coerce your date into the correct
format.

=item search_sent_since

This function takes a single argument we'll call C<< <x> >> and returns numbers
of messages that have a header date after C<< <x> >>.  If you have L<Date::Manip>
installed (optional), this function will attempt to force the date into the
format C<%d-%m-%Y> (date-month-year) as RFC3501 requires.  If you do not have
that module, no attempt will be made to coerce your date into the correct
format.

=back

=item uidsearch

This function works exactly like C<search()> but it returns UIDs instead of
sequence numbers.  The convenient shortcuts above are not provided for it.

=back

=head1 OTHER NOTES

=over 4

=item sequence set

Message numbers are never checked before being passed to the IMAP server (this
is a "simple" module after all), so in most places where a message number is
required, you can instead use so-called I<sequence sets>.  Examples:

    $imap->copy(   "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
    $imap->delete( "3,4,9:22" ) or die $imap->errstr;

=back

=head1 AUTHOR

=over 4

=item Creator

Joao Fonseca C<< <joao_g_fonseca@yahoo.com> >>

=item Maintainer 2004

Casey West C<< <casey@geeknst.com> >>

=item Maintainer 2005

Colin Faber C<< <cfaber@fpsn.net> >>

=item Maintainer 2009

Paul Miller C<< <jettero@cpan.org> >>

=back

=head1 COPYRIGHT

Copyright (c) 2009-2010 Paul Miller
Copyright (c) 2005 Colin Faber
Copyright (c) 2004 Casey West
Copyright (c) 1999 Joao Fonseca

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

=head1 LICENSE

This module is free software.  You can redistribute it and/or
modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful,
but without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

[This software may have had previous licenses, of which the current maintainer
is completely unaware.  If this is so, it is possible the above license is
incorrect or invalid.]

=head1 BUGS

There are probably bugs.  But don't worry, the current maintainer takes them
very seriously and will usually triage (at least) within a single day.

L<https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>

=head1 SEE ALSO

L<perl>, L<Net::IMAP::Server>, L<IO::Socket::SSL>, L<IO::Socket::INET6>