22

✏️ Editing: IMAPClient.pod

=head1 NAME

Mail::IMAPClient - An IMAP Client API

=head1 SYNOPSIS

use Mail::IMAPClient;

my $imap = Mail::IMAPClient->new(
    Server   => 'localhost',
    User     => 'username',
    Password => 'password',
    Ssl      => 1,
    Uid      => 1,
  );

my $folders = $imap->folders
    or die "List folders error: ", $imap->LastError, "\n";
  print "Folders: @$folders\n";

$imap->select( $Opt{folder} )
    or die "Select '$Opt{folder}' error: ", $imap->LastError, "\n";

$imap->fetch_hash("FLAGS", "INTERNALDATE", "RFC822.SIZE")
    or die "Fetch hash '$Opt{folder}' error: ", $imap->LastError, "\n";

$imap->logout
    or die "Logout error: ", $imap->LastError, "\n";

=head1 DESCRIPTION

This module provides methods implementing the IMAP protocol to support
interacting with IMAP message stores.

The module is used by constructing or instantiating a new IMAPClient
object via the L</new> constructor method.  Once the object has been
instantiated, the L</connect> method is either implicitly or
explicitly called.  At that point methods are available that implement
the IMAP client commands as specified in B<RFC3501>.  When processing
is complete, the L</logout> object method should be called.

This documentation is not meant to be a replacement for RFC3501 nor
any other IMAP related RFCs.

Note that this documentation uses the term I<folder> in place of
RFC3501's use of I<mailbox>.  This documentation reserves the use of
the term I<mailbox> to refer to the set of folders owned by a specific
IMAP id.

=head2 Connection State

RFC3501 defines four possible states for an IMAP connection: not
authenticated, authenticated, selected, and logged out.  These
correspond to the IMAPClient constants C<Connected>, C<Authenticated>,
C<Selected>, and C<Unconnected>, respectively.  These constants can be
used in conjunction with the L</Status> method to determine the status
of an IMAPClient object and its underlying IMAP session.

Note that an IMAPClient object can be in the C<Unconnected> state both
before a server connection is made and after it has ended.  This
differs slightly from RFC3501, which does not define a pre-connection
status.  For a discussion of the methods available for examining the
IMAPClient object's status, see the section labeled
L</"Status Methods">, below.

=head2 Advanced Authentication Mechanisms

RFC3501 defines two commands for authenticating to an IMAP server:

=over 4

=item LOGIN

=item AUTHENTICATE

AUTHENTICATE for more advanced and/or secure authentication mechanisms.

=back

Mail::IMAPClient supports the following AUTHENTICATE mechanisms:

=over 4

=item DIGEST-MD5

DIGEST-MD5 authentication requires the L<Authen::SASL> and
L<Digest::MD5> modules.  See also L</Authuser>.

=item CRAM-MD5

CRAM-MD5 requires the L<Digest::HMAC_MD5> module.

=item PLAIN (SASL)

PLAIN (SASL) authentication allows the optional use of the L</Proxy>
parameter.  RFC 4616 documents this syntax for SASL PLAIN:

message = [authzid] UTF8NUL authcid UTF8NUL passwd

When L</Proxy> is defined, L</User> is used as 'authzid' and L</Proxy>
is used as 'authcid'.  Otherwise, L</User> is used as 'authcid'.

=item NTLM

NTLM authentication requires the L<Authen::NTLM> module.  See also
L</Domain>.

=back

=head2 Errors

If you attempt an operation that results in an error, then you can
retrieve the text of the error message by using the L</LastError>
method.  However, the L</LastError> method is an object method (not a
class method) and can only be used once an object is successfully
created.  In cases where an object is not successfully created the
C<$@> variable is set with an error message.

Mail::IMAPClient resets C<$@> and L</LastError> to undef before most
IMAP requests, so the values only have a short lifespan.
L</LastError> will always contain error info from the last error,
until another error is encountered, another IMAP command is issued or
it is explicitly cleared.

Please note that the use of C<$@> is subject to change in the future
release so it is best to use L</LastError> for error checking once a
Mail::IMAPClient object has been created.

Errors in the L</new> method can prevent your object from ever being
created.  If the L</Server>, L</User>, and L</Password> parameters are
supplied to L</new>, it will attempt to call L</connect> and
L</login>.  Any of these methods could fail and cause the L</new>
method call to return C<undef> and leaving the variable C<$@> is set
to an error message.

WARNING: (due to historical API behavior) on errors, many methods may
return undef regardless of LIST/SCALAR context.  Therefore, it may be
wise to use most methods in a scalar context.  Regardless, check
L</LastError> for details on errors.

=head2 Transactions

RFC3501 requires that each line in an IMAP conversation be prefixed
with a tag.  A typical conversation consists of the client issuing a
tag-prefixed command string, and the server replying with one of more
lines of output.  Those lines of output will include a command
completion status code prefixed by the same tag as the original
command string.

The IMAPClient module uses a simple counter to ensure that each client
command is issued with a unique tag value.  This tag value is referred
to by the IMAPClient module as the transaction number.  A history is
maintained by the IMAPClient object documenting each transaction.  The
L</Transaction> method returns the number of the last transaction, and
can be used to retrieve lines of text from the object's history.

The L</Clear> parameter is used to control the size of the session
history so that long-running sessions do not eat up unreasonable
amounts of memory.  See the discussion of L</Clear> parameter for more
information.

The L</Report> transaction returns the history of the entire IMAP
session since the initial connection or for the last L</Clear>
transactions.  This provides a record of the entire conversation,
including client command strings and server responses, and is a
wonderful debugging tool as well as a useful source of raw data for
custom parsing.

=head1 CLASS METHODS

There are a couple of methods that can be invoked as class methods.
Generally they can be invoked as an object method as well.  Note that
if the L</new> method is called as an object method, the object
returned is identical to what have would been returned if L</new> had
been called as a class method.  It doesn't give you a copy of the
original object.

=head2 new

Example:

my $imap = Mail::IMAPClient->new(%args)
    or die "new failed: $@\n";

The L</new> method creates a new instance of an IMAPClient object.

If the L</Server> parameter is passed as an argument to B<new>, then
B<new> will implicitly call the L</connect> method, placing the new
object in the I<Connected> state.  If L</User> and L</Password> values
are also provided, then L</connect> will in turn call L</login>, and
the resulting object will be returned from B<new> in the
I<Authenticated> state.

If the L</Server> parameter is not supplied then the IMAPClient
object is created in the I<Unconnected> state.

If the B<new> method is passed arguments then those arguments will be
treated as a list of key=>value pairs.  The key should be one of the
parameters as documented under L</"Parameters"> below.

Here are some examples:

use Mail::IMAPClient;
  
  # returns an unconnected Mail::IMAPClient object:
  my $imap = Mail::IMAPClient->new;
  # ...
  # intervening code using the 1st object, then:
  # (returns a new, authenticated Mail::IMAPClient object)
  $imap = Mail::IMAPClient->new(
      Server   => $host,
      User     => $id,
      Password => $pass,
      Clear    => 5,   # Unnecessary since '5' is the default
      # ...            # Other key=>value pairs go here
  ) or die "Cannot connect to $host as $id: $@";

See also L</Parameters>, L</connect> and L</login> for more
information on how to manually connect and login after B<new>.

=head2 Quote

Example:

$imap->search( HEADER => 'Message-id' => \$imap->Quote($msg_id) );

The B<Quote> method accepts a value as an argument and returns its
argument as a correctly quoted string or a literal string.  Since
version 3.17 Mail::IMAPClient automatically quotes search arguments we
use a SCALARREF so search will not modify or re-quote the value
returned by B<Quote>.

Note this method should not be used on folder names for
Mail::IMAPClient methods, since methods that accept folder names as an
argument will quote the folder name arguments automatically.

If you are getting unexpected results when running methods with values
that have (or might have) embedded spaces, double quotes, braces, or
parentheses, then calling B<Quote> may be necessary.  This method
should B<not> be used with arguments that are wrapped in quotes or
parens if those quotes or parens are required by RFC3501.  For
example, if the RFC requires an argument in this format:

( argument )

and the argument is (or might be) "pennies (from heaven)", then one
could use:

$argument = "(" . $imap->Quote($argument) . ")"

Of course, the fact that sometimes these characters are sometimes
required delimiters is precisely the reason you must quote them when
they are I<not> delimiting.

However, there are times when a method fails unexpectedly and may
require the use of B<Quote> to work.  Should this happen, you can
probably file a bug/enhancement request for Mail::IMAPClient to
safeguard the particular call/case better.

An example is RFC822 Message-id's, which I<usually> don't contain
quotes or parens.  When dealing with these it is usually best to take
proactive, defensive measures from the very start and use B<Quote>.

=head2 Range

Example:

my $parsed = $imap->parse_headers(
      $imap->Range( $imap->messages ), "Date", "Subject"
  );

The B<Range> method will condense a list of message sequence numbers
or message UID's into the most compact format supported by RFC3501.
It accepts one or more arguments, each of which can be:

=over 4

=item a) a message number,

=item b) a comma-separated list of message numbers,

=item c) a colon-separated range of message numbers (i.e. "$begin:$end")

=item d) a combination of messages and message ranges, separated by commas
(i.e. 1,3,5:8,10), or

=item e) a reference to an array whose elements are like I<a)> through I<d)>.

=back

The B<Range> method returns a L<Mail::IMAPClient::MessageSet> object.
The object uses L<overload> and if treated as a string it will act
like a string.  This means you can ignore its objectivity and just
treat it like a string whose value is your message set expressed in
compact format.

This method provides an easy way to add or remove messages from a
message set.

For more information see L<Mail::IMAPClient::MessageSet>.

=head2 Rfc3501_date

Example:

$Rfc3501_date = $imap->Rfc3501_date($seconds);
  # or:
  $Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);

The B<Rfc3501_date> method accepts one input argument, a number of
seconds since the epoch date.  It returns an RFC3501 compliant date
string for that date (as required in date-related arguments to SEARCH,
such as "since", "before", etc.).

=head2 Rfc3501_datetime

Example:

$date = $imap->Rfc3501_datetime($seconds);
  # or:
  $date = Mail::IMAPClient->Rfc3501_datetime($seconds);

The B<Rfc3501_datetime> method accepts one or two arguments: a
obligatory timestamp and an optional zone.  The zone shall be
formatted as C<< [+-]\d{4} >>, and defaults to C<< +0000 >>.  The
timestamp follows the definition of the output of the platforms
specific C<time>, usually in seconds since Jan 1st 1970.  However, you
have to correct the number yourself for the zone.

=head2 Rfc822_date

Example:

$Rfc822_date = $imap->Rfc822_date($seconds);
  # or:
  $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);

The B<Rfc822_date> method accepts one input argument, a number of
seconds since the epoch date.  It returns an RFC822 compliant date
string for that date (without the 'Date:' prefix).  Useful for putting
dates in message strings before calling L</append>, L</search>, etc.

=head2 Strip_cr

Examples:

my $stripped = $imap->Strip_cr($string);
  # or:
  my @list = $imap->some_imap_method;
  @list = $imap->Strip_cr(@list);
  # or:
  my $list = [ $imap->some_imap_method ];   # returns an array ref
  $list = $imap->Strip_cr($list);

The B<Strip_cr> method strips carriage returns from input and returns
the new string to the caller.  This method accepts one or more lines
of text as arguments, and returns those lines with all <CR><LF>
sequences changed to <LF>.  Any input argument with no carriage
returns is returned unchanged.  If the first argument (not counting
the class name or object reference) is an array reference, then
members of that array are processed as above and subsequent arguments
are ignored.  If the method is called in scalar context then an array
reference is returned instead of an array of results.

NOTE: B<Strip_cr> does not remove new line characters.

=head1 OBJECT METHODS

Object methods must be invoked against objects created via the L</new>
method and cannot be invoked as class methods.

There object methods typically fall into one of two categories.  There
are mailbox methods which participate in the IMAP session's
conversation (i.e. they issue IMAP client commands) and object control
methods which do not result in IMAP commands but which may affect
later commands or provide details of previous ones.

This object control methods can be further broken  down into two
types, Parameter accessor methods, which affect the behavior of future
mailbox methods, and L</"Status Methods">, which report on the affects
of previous mailbox methods.

Methods that do not result in new IMAP client commands being issued
(such as the L</Transaction>, L</Status>, and L</History> methods) all
begin with an uppercase letter, to distinguish them from methods that
do correspond to IMAP client commands.  Class methods and eponymous
parameter methods likewise begin with an uppercase letter because they
also do not correspond to an IMAP client command.

As a general rule, mailbox control methods return C<undef> on failure
and something besides C<undef> when they succeed.  This rule is
modified in the case of methods that return search results.  When
called in a list context, searches that do not find matching results
return an empty list.  When called in a scalar context, searches with
no hits return 'undef' instead of an array reference.  If you want to
know why you received no hits, you should check L</LastError> or
C<$@>, which will be empty if the search was successful but had no
matching results but populated with an error message if the search
encountered a problem (such as invalid parameters).

A number of IMAP commands do not have corresponding Mail::IMAPClient
methods.  Patches are welcome.  In the pre-2.99 releases of this
module, they were automatically created (AUTOLOAD), but that was very
error-prone and stalled the progress of this module.

=head1 Mailbox Control Methods

=head2 append

Example:

my $uid_or_true = $imap->append( $folder, $msgtext )
    or die "Could not append: ", $imap->LastError;

WARNING: This method may be deprecated in the future, consider using
L</append_string> instead of this method.

The B<append> method adds a message to the specified folder.  See
L</append_string> for details as it is effectively an alias for that
method.

DEPRECATED BEHAVIOR: Additional arguments are added to the message
text, separated with <CR><LF>.

=head2 append_string

Example:

# brackets indicate optional arguments (not array refs):
   my $uidort = $imap->append_string( $folder, $msgtext [,$flags [,$date ] ] )
       or die "Could not append_string: ", $imap->LastError;

Arguments:

=over 4

=item $folder

the name of the folder to append the message to

=item $msgtext

the message text (including headers) of the message

=item $flags

An optional list of flags to set.  The list must be specified as
a space-separated list of flags, including any backslashes that may be
necessary and optionally enclosed by parenthesis.

=item $date

An optional RFC3501 date argument to set as the internal date.  It
should be in the format described for I<date_time> fields in RFC3501,
i.e. "dd-Mon-yyyy hh:mm:ss +0000".

If you want to specify a date/time but you don't want any flags then
specify I<undef> as the third ($flags) argument.

=back

Returns:

=over 4

=item error: undef

On error, undef can be returned regardless of LIST/SCALAR context.
Check L</LastError> for details.

=item success: UID or $imap

With UIDPLUS the UID of the new message is returned otherwise a true
value (currently $self) is returned.

=back

To protect against "bare newlines", B<append> will insert a carriage
return before any newline that is "bare".

=head2 append_file

Example:

my $new_msg_uid = $imap->append_file(
      $folder,
      $file,
      [ undef, $flags, $date ] # optional
  ) or die "Could not append_file: ", $imap->LastError;

The B<append_file> method adds a message to the specified folder.
Note: The brackets in the example indicate optional arguments; they do
not mean that the argument should be an array reference.

Arguments:

=over 4

=item $folder

the name of the folder to append the message to

=item $file

a filename, filehandle or SCALAR reference which holds an
RFC822-formatted message

=item undef

a deprecated argument used as a place holder for backwards
compatibility

=item $flags

The optional argument is handled the same as append_string.

=item $date

The optional argument is handled the same as append_string (RFC3501
date), with the exception that if $date is "1" (one) then the
modification time (mtime) of the file will be used.

=back

Returns:

=over 4

=item error: undef

On error, undef can be returned regardless of LIST/SCALAR context.
Check L</LastError> for details.

=item success: UID or $imap

With UIDPLUS the UID of the new message is returned otherwise a true
value (currently $self) is returned.

=back

To protect against "bare newlines", B<append_file> will insert a
carriage return before any newline that is "bare".

The B<append_file> method provides a mechanism for allowing large
messages to be appended without holding the whole file in memory.

Version note: In 2.x an optional third argument to use for
C<input_record_separator> was allowed, however this argument is
ignored/not supported as of 3.x.

=head2 authenticate

Example:

$imap->authenticate( $authentication_mechanism, $coderef )
    or die "Could not authenticate: ", $imap->LastError;

This method implements the AUTHENTICATE IMAP client command.  It can
be called directly or may be called by L</login> if the
L</Authmechanism> parameter is set to anything except 'LOGIN'.

The B<authenticate> method accepts two arguments, an authentication
type to be used (ie CRAM-MD5) and a code or subroutine reference to
execute to obtain a response.  The B<authenticate> method assumes that
the authentication type specified in the first argument follows a
challenge-response flow.  The B<authenticate> method issues the IMAP
Client AUTHENTICATE command and receives a challenge from the server.
That challenge (minus any tag prefix or enclosing '+' characters but
still in the original base64 encoding) is passed as the only argument
to the code or subroutine referenced in the second argument.  The
return value from the 2nd argument's code is written to the server as
is, except that a <CR><LF> sequence is appended if necessary.

If one or both of the arguments are not specified in the call to
B<authenticate> but their corresponding parameters have been set
(L</Authmechanism> and L</Authcallback>, respectively) then the parameter
values are used. Arguments provided to the method call however will
override parameter settings.

If you do not specify a second argument and you have not set the
L</Authcallback> parameter, then the first argument must be
one of the authentication mechanisms for which Mail::IMAPClient
has built in support.

See also the L</login> method, which is the simplest form of
authentication defined by RFC3501.

=head2 before

Example:

my @msgs = $imap->before($Rfc3501_date)
    or warn "No messages found before $Rfc3501_date.\n";

The B<before> method works just like the L</"since"> method, below,
except it returns a list of messages whose internal system dates are
before the date supplied as the argument to the B<before> method.

=head2 body_string

Example:

my $string = $imap->body_string($msgId)
    or die "body_string failed: ", $imap->LastError;

The B<body_string> method accepts a message sequence number (or a
message UID, if the L</Uid> parameter is set to true) as an argument
and returns the message body as a string.  The returned value contains
the entire message in one scalar variable, without the message
headers.

=head2 bodypart_string

Example:

my $string = $imap->bodypart_string(
      $msgid, $part_number, $length, $offset
  ) or die "Could not get bodypart string: ", $imap->LastError;

The B<bodypart_string> method accepts a message sequence number (or a
message UID, if the L</Uid> parameter is set to true) and a body part
as arguments and returns the message part as a string.  The returned
value contains the entire message part (or, optionally, a portion of
the part) in one scalar variable.

If an optional third argument is provided, that argument is the number
of bytes to fetch.  (The default is the whole message part.)  If an
optional fourth argument is provided then that fourth argument is the
offset into the part at which the fetch should begin.  The default is
offset zero, or the beginning of the message part.

If you specify an offset without specifying a length then the offset
will be ignored and the entire part will be returned.

B<bodypart_string> will return C<undef> if it encounters an error.

=head2 capability

Example:

my $features = $imap->capability
    or die "Could not determine capability: ", $imap->LastError;

The B<capability> method returns an array (or arrayref in scalar
context) of capabilities as returned by the CAPABILITY IMAP client
command.  If the CAPABILITY IMAP client command fails for any reason
then the B<capability> method will return C<undef>.  Supported
capabilities are cached by the client, however, this cache is deleted
after a connection is set to I<Authenticated> and when L</starttls> is
called.

See also C<Supportedflags>.

=head2 move

Example:

my $newUid = $imap->move( $newFolder, $oldUid )
    or die "Could not move: $@\n";
  $imap->expunge;

The B<move> method moves messages from the currently selected folder
to the folder specified in the first argument to B<move>.  If the
L</Uid> parameter is not true, then the rest of the arguments should
be either:

=over 4

=item a)

a message sequence number,

=item b)

a comma-separated list of message sequence numbers, or

=item c)

a reference to an array of message sequence numbers.

=back

If the L</Uid> parameter is true, then the arguments should be:

=over 4

=item a)

a message UID,

=item b)

a comma-separated list of message UID's, or

=item c)

a reference to an array of message UID's.

=back

If the target folder does not exist then it will be created.

If move is successful, then it returns a true value.  Furthermore, if
the Mail::IMAPClient object is connected to a server that has the
UIDPLUS capability, then the true value will be the comma-separated
list of UID's for the newly copied messages.  The list will be in the
order in which the messages were moved which should correspond to the
order of the message UID provided by the caller.

If the move is not successful then B<move> returns C<undef>.

Note that a move really just involves copying the message to the new
folder and then setting the I<\Deleted> flag.  To actually delete the
original message you will need to run L</expunge> (or L</close>).

=head2 namespace

Example:

my $refs = $imap->namespace
    or die "namespace failed: $@\n";

The namespace method runs the NAMESPACE IMAP command (as defined in
RFC 2342).  When called in a list context, it returns a list of three
references.  Each reference looks like this:

[
    [ $prefix_1, $separator_1 ],
    [ $prefix_2, $separator_2 ],
    [ $prefix_n, $separator_n ],
  ]

The first reference provides a list of prefixes and separator
characters for the available personal namespaces.  The second
reference provides a list of prefixes and separator characters for the
available shared namespaces.  The third reference provides a list of
prefixes and separator characters for the available public namespaces.

If any of the three namespaces are unavailable on the current server
then an 'undef' is returned instead of a reference.  So for example if
shared folders were not supported on the server but personal and
public namespaces were both available (with one namespace each), the
returned value might resemble this:

[ [ "", "/" ] , undef, [ "#news", "." ] ];

If the B<namespace> method is called in scalar context, it returns a
reference to the above-mentioned list of three references, thus
creating a single structure that would pretty-print something like
this:

$VAR1 = [
      [
          [ $user_prefix_1, $user_separator_1 ],
          [ $user_prefix_2, $user_separator_2 ],
          [ $user_prefix_n, $user_separator_n ],
      ],                    # or undef
      [
          [ $shared_prefix_1, $shared_separator_1 ],
          [ $shared_prefix_2, $shared_separator_2 ],
          [ $shared_prefix_n, $shared_separator_n ],
      ],                    # or undef
      [
          [ $public_prefix_1, $public_separator_1 ],
          [ $public_prefix_2, $public_separator_2 ],
          [ $public_prefix_n, $public_separator_n ],
      ],                    # or undef
  ];

=head2 on

Example:

my @msgs = $imap->on($Rfc3501_date)
    or warn "Could not find messages sent on $Rfc3501_date: $@\n";

The B<on> method works just like the L</since> method, below, except
it returns a list of messages whose internal system dates are the same
as the date supplied as the argument.

=head2 parse_headers

Example:

my $hashref = $imap->parse_headers( $msg || \@msgs, "Date", "Subject" )
    or die "Could not parse_headers: $@\n";

The B<parse_headers> method accepts as arguments a message sequence
number and a list of header fields.  It returns a hash reference in
which the keys are the header field names (without the colon) and the
values are references to arrays of values.  On failure <undef> is
returned and L</LastError> is set.

A picture would look something like this:

$hashref = $imap->parse_headers( 1, "Date", "Received", "Subject", "To");
  $hashref = {
      "Date"     => [ "Thu, 09 Sep 1999 09:49:04 -0400" ]  ,
      "Received" => [ q/
        from mailhub ([111.11.111.111]) by mailhost.bigco.com
        (Netscape Messaging Server 3.6)  with ESMTP id AAA527D for
        <bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
        /, q/
        from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
        id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
        (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
        /, q/
        from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
        with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
        18 Jun 1999 16:29:05 +0000 (GMT)
        /] ,
      "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
      "To"      => [ "Big Shot <big.shot@bigco.com> ] ,
  };

The text in the example for the "Received" array has been formatted to
make reading the example easier.  The actual values returned are just
strings of words separated by spaces and with newlines and carriage
returns stripped off.  The I<Received> header is probably the main
reason that the B<parse_headers> method creates a hash of lists rather
than a hash of values.

If the second argument to B<parse_headers> is 'ALL' or if it is
unspecified then all available headers are included in the returned
hash of lists.

If you're not emotionally prepared to deal with a hash of lists then
you can always call the L</fetch> method yourself with the appropriate
parameters and parse the data out any way you want to.  Also, in the
case of headers whose contents are also reflected in the envelope, you
can use the L</get_envelope> method as an alternative to
L</parse_headers>.

If the L</Uid> parameter is true then the first argument will be
treated as a message UID.  If the first argument is a reference to an
array of message sequence numbers (or UID's if L</Uid> is true), then
B<parse_headers> will be run against each message in the array.  In
this case the return value is a hash, in which the key is the message
sequence number (or UID) and the value is a reference to a hash as
described above.

An example of using B<parse_headers> to print the date and subject of
every message in your demo folder could look like this:

use Mail::IMAPClient;
  my $imap = Mail::IMAPClient->new(
      Server => $imaphost, User => $login, Password => $pass, Uid => 1
  );

$imap->select("demo");

my $msgs = $imap->search("ALL");
  for my $h (

# get the Subject and Date from every message in folder "demo" the
   # first arg is a reference to an array listing all messages in the
   # folder (which is what gets returned by the $imap->search("ALL")
   # method when called in scalar context) and the remaining arguments
   # are the fields to parse out The key is the message number, which
   # in this case we don't care about:

values %{ $imap->parse_headers( $msgs , "Subject", "Date") } )
  {
      # $h is the value of each element in the hash ref returned
      # from parse_headers, and $h is also a reference to a hash.
      # We'll only print the first occurrence of each field because
      # we don't expect more than one Date: or Subject: line per
      # message.
      print map { "$_:\t$h->{$_}[0]\n"} keys %$h;
  }

=head2 recent

Example:

my @recent = $imap->recent or warn "No recent msgs: $@\n";

The B<recent> method performs an IMAP SEARCH RECENT search against the
selected folder and returns an array of sequence numbers (or UID's, if
the L</Uid> parameter is true) of messages that are recent.

=head2 recent_count

Example:

my $count = 0;
  defined($count = $imap->recent_count($folder))
    or die "recent_count failed: $@\n";

The B<recent_count> method accepts as an argument a folder name.  It
returns the number of recent messages in the folder (as returned by
the IMAP client command "STATUS folder RECENT"), or C<undef> in the
case of an error.  The B<recent_count> method was contributed by Rob
Deker (deker@ikimbo.com).

=head2 noop

Example:

$imap->noop or die "noop failed: $@\n";

The B<noop> method performs an IMAP NOOP command.  Per RFC3501 this
command does nothing and always succeeds.  However, if a connection
times out or other errors occur while communicating with the server,
this method can still fail.  This command can be used as a periodic
poll to check for (untagged) status updates (new messages, etc.) from
the server and also to reset any inactivity/auto-logout timers the
server may maintain.

=head2 reconnect

Example:

$imap->noop or $imap->reconnect or die "noop failed: $@\n";

Attempt to reconnect if the IMAP connection unless $imap is already in
the IsConnected state.  This method calls L</connect> and optionally
L</select> if a Folder was previously selected.  On success, returns
the (same) $imap object.  On failure <undef> is returned and
L</LastError> is set.

Version note: method added in Mail::IMAPClient 3.17

=head2 rename

Example:

$imap->rename( $oldname, $nedwname )
    or die "rename failed: $@\n";

The B<rename> method accepts two arguments: the name of an existing
folder, and a new name for the folder.  The existing folder will be
renamed to the new name using the RENAME IMAP client command.
B<rename> will return a true value if successful, or C<undef> if
unsuccessful.

=head2 restore_message

Example:

$imap->restore_message(@msgs) or die "restore_message failed: $@\n";

The B<restore_message> method is used to undo a previous
L</delete_message> operation (but not if there has been an intervening
L</expunge> or L</close>).  The IMAPClient object must be in
L</Selected> status to use the B<restore_message> method.

The B<restore_message> method accepts a list of arguments.  If the
L</Uid> parameter is not set to a true value, then each item in the
list should be either:

=over 4

=item >

a message sequence number,

=item >

a comma-separated list of message sequence numbers,

=item >

a reference to an array of message sequence numbers, or

=back

If the L</Uid> parameter is set to a true value, then each item in the
list should be either:

=over 4

=item >

a message UID,

=item >

a comma-separated list of UID's, or

=item >

a reference to an array of message UID's.

=back

The messages identified by the sequence numbers or UID's will have
their I<\Deleted> flags cleared, effectively "undeleting" the
messages.  B<restore_message> returns the number of messages it was
able to restore.

Note that B<restore_messages> is similar to calling
C<L</unset_flag>("\Deleted",@msgs)>, except that B<restore_messages>
returns a (slightly) more meaningful value. Also it's easier to type.

=head2 run

Example:

$imap->run(@args) or die "run failed: $@\n";

The B<run> method is provided to make those uncommon things
possible... however, we would like you to contribute the knowledge of
missing features with us.

The B<run> method excepts one or two arguments.  The first argument is
a string containing an IMAP client command, including a tag and all
required arguments.  The optional second argument is a string to look
for that will indicate success.  (The default is C</OK.*/>).  The
B<run> method returns an array (or arrayref in scalar context) of
output lines from the command, which you are free to parse as you see
fit.

The B<run> method does not do any syntax checking, other than
rudimentary checking for a tag.

When B<run> processes the command, it increments the transaction count
and saves the command and responses in the History buffer in the same
way other commands do.  However, it also creates a special entry in
the History buffer named after the tag supplied in the string passed
as the first argument.  If you supply a numeric value as the tag then
you may risk overwriting a previous transaction's entry in the History
buffer.

If you want the control of B<run> but you don't want to worry about
tags then see L</"tag_and_run">, below.

=head2 search

Example:

my $msgs1 = $imap->search(@args);
  if ($msgs1) {
      print "search matches: @$msgs1";
  }
  else {
      warn "Error in search: $@\n" if $@;
  }

# or  note: be sure to quote string properly
  my $msgs2 = $imap->search( \( $imap->Quote($msgid), "FROM", q{"me"} ) )
    or warn "search failed: $@\n";

# or  note: be sure to quote string properly
  my $msgs3 = $imap->search('TEXT "string not in mailbox"')
    or warn "search failed: $@\n";

The B<search> method implements the SEARCH IMAP client command.  Any
arguments supplied to B<search> are prefixed with a space then
appended to the SEARCH IMAP client command.  The SEARCH IMAP client
command allows for many options and arguments.  See RFC3501 for
details.

As of version 3.17 B<search> tries to "DWIM" by automatically quoting
things that likely need quotes when the words do not match any of the
following:

ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED
    FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
    SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
    TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
    UNKEYWORD UNSEEN

The following options exist to avoid the automatic quoting (note:
caller is responsible for verifying the data sent in these cases is
properly escaped/quoted):

=over 4

=item *

specify a single string/argument in the call to search.

=item *

specify args as scalar references (SCALAR) and the values of those
SCALAR refs will be passed along as-is.

=back

The B<search> method returns an array containing sequence numbers of
messages that passed the SEARCH IMAP client command's search criteria.
If the L</Uid> parameter is true then the array will contain message
UID's.  If B<search> is called in scalar context then a pointer to the
array will be passed, instead of the array itself.  If no messages
meet the criteria then B<search> returns an empty list (when in list
context) or C<undef> (in scalar context).

Since a valid, successful search can legitimately return zero matches,
you may wish to distinguish between a search that correctly returns
zero hits and a search that has failed for some other reason (i.e.
invalid search parameters).  Therefore, the C<$@> variable will always
be cleared before the I<SEARCH> command is issued to the server, and
will thus remain empty unless the server gives a I<BAD> or I<NO>
response to the I<SEARCH> command.

=head2 see

Example:

$imap->see(@msgs) or die "see failed: $@\n";

The B<see> method accepts a list of one or more messages sequence
numbers, or a single reference to an array of one or more message
sequence numbers, as its argument(s).  It then sets the I<\Seen> flag
for those message(s).  Of course, if the L</Uid> parameter is set to a
true value then those message sequence numbers had better be unique
message id's, but then you already knew that, didn't you?

Note that specifying C<$imap-E<gt>see(@msgs)> is just a shortcut for
specifying C<$imap-E<gt>L</set_flag>("Seen",@msgs)>.

=head2 seen

Example:

my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";

The B<seen> method performs an IMAP SEARCH SEEN search against the
selected folder and returns an array of sequence numbers of messages
that have already been seen (ie their I<\Seen> flag is set).  If the
L</Uid> parameter is true then an array of message UID's will be
returned instead.  If called in scalar context than a reference to the
array (rather than the array itself) will be returned.

=head2 select

Example:

$imap->select($folder) or die "select failed: $@\n";

The B<select> method selects a folder and changes the object's state
to I<Selected>.  It accepts one argument, which is the name of the
folder to select.

=head2 selectable

Example:

foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
      $imap->select($f);
  }

The B<selectable> method accepts one value, a folder name, and returns
true if the folder is selectable or false if it is not selectable.

=head2 sentbefore

Example:

my @msgs = $imap->sentbefore($Rfc3501_date)
    or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";

The B<sentbefore> method works just like L</"sentsince">, below,
except it searches for messages that were sent before the date
supplied as an argument to the method.

=head2 senton

Example:

my @msgs = $imap->senton($Rfc3501_date)
    or warn "Could not find any messages sent on $Rfc3501_date: $@\n";

The B<senton> method works just like L</"sentsince">, below, except it
searches for messages that were sent on the exact date supplied as an
argument to the method.

=head2 sentsince

Example:

my @msgs = $imap->sentsince($Rfc3501_date)
    or warn "Could not find any messages sent since $Rfc3501_date: $@\n";

The B<sentsince> method accepts one argument, a date in either epoch
time format (seconds since 1/1/1970, or as output by
L<time|perlfunc/time> and as accepted by
L<localtime|perlfunc/localtime>) or in the I<date_text> format as
defined in RFC3501 (dd-Mon-yyyy, where Mon is the English-language
three-letter abbreviation for the month).

It searches for items in the currently selected folder for messages
sent since the day whose date is provided as the argument.  It uses
the RFC822 I<Date:> header to determine the I<sentsince> date.
(Actually, it the server that uses the I<Date:> header; this
documentation just assumes that the date is coming from the I<Date:>
header because that's what RFC3501 dictates.)

In the case of arguments supplied as a number of seconds, the returned
result list will include items sent on or after that day, regardless
of whether they arrived before the specified time on that day.  The
IMAP protocol does not support searches at a granularity finer than a
day, so neither do I.  On the other hand, the only thing I check for
in a I<date_text> argument is that it matches the pattern
C</\d\d-\D\D\D-\d\d\d\d/> (notice the lack of anchors), so if your
server lets you add something extra to a I<date_text> string then so
will Mail::IMAPClient.

If you'd like, you can use the L</Rfc3501_date> method to convert from
epoch time (as returned by L<time|perlfunc/time>) into an RFC3501 date
specification.

=head2 separator

Example:

my $sepChar = $imap->separator(@args)
    or die "Could not get separator: $@\n";

The B<separator> method returns the character used as a separator
character in folder hierarchies.  On UNIX-based servers, this is often
but not necessarily a forward slash (/).  It accepts one argument, the
name of a folder whose hierarchy's separator should be returned.  If
no folder name is supplied then the separator for the INBOX is
returned, which probably is good enough.

If you want your programs to be portable from IMAP server brand X to
IMAP server brand Y, then you should never use hard-coded separator
characters to specify subfolders.  (In fact, it's even more
complicated than that, since some server don't allow any subfolders at
all, some only allow subfolders under the "INBOX" folder, and some
forbid subfolders in the inbox but allow them "next" to the inbox.
Furthermore, some server implementations do not allow folders to
contain both subfolders and mail messages; other servers allow this.)

=head2 set_flag

Example:

$imap->set_flag( "Seen", @msgs )
    or die "Could not set flag: $@\n";

The B<set_flag> method accepts the name of a flag as its first
argument and a list of one or more messages sequence numbers, or a
single reference to an array of one or more message sequence numbers,
as its next argument(s).  It then sets the flag specified for those
message(s).  Of course, if the L</Uid> parameter is set to a true
value then those message sequence numbers had better be unique message
id's, just as you'd expect.

Note that when specifying the flag in question, the preceding
backslash (\) is entirely optional.  (For you, that is.
Mail::IMAPClient still has remember to stick it in there before
passing the command to the server if the flag is one of the reserved
flags specified in RFC3501.  This is in fact so important that the
method checks its argument and adds the backslash when necessary,
which is why you don't have to worry about it overly much.)

=head2 setacl

Example:

$imap->setacl( $folder, $userid, $aclstring )
    or die "Could not set acl: $@\n";

The B<setacl> method accepts three input arguments, a folder name, a
user id (or authentication identifier, to use the terminology of
RFC2086), and an access rights modification string.  See RFC2086 for
more information.  (This is somewhat experimental and its
implementation may change.)

=head2 since

Example:

my @msgs = $imap->since($date)
    or warn "Could not find any messages since $date: $@\n";

The B<since> method accepts a date in either epoch format (seconds
since 1/1/1970, or as output by L<perlfunc/time> and as accepted by
L<perlfunc/localtime>) or in the I<date_text> format as defined in
RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter
abbreviation for the month).  It searches for items in the currently
selected folder for messages whose internal dates are on or after the
day whose date is provided as the argument.  It uses the internal
system date for a message to determine if that message was sent since
the given date.

In the case of arguments supplied as a number of seconds, the returned
result list will include items whose internal date is on or after that
day, regardless of whether they arrived before the specified time on
that day.

If B<since> is called in a list context then it will return a list of
messages meeting the I<SEARCH SINCE> criterion, or an empty list if no
messages meet the criterion.

If B<since> is called in a scalar context then it will return a
reference to an array of messages meeting the I<SEARCH SINCE>
criterion, or C<undef> if no messages meet the criterion.

Since B<since> is a front-end to L</search>, some of the same rules
apply.  For example, the C<$@> variable will always be cleared before
the I<SEARCH> command is issued to the server, and will thus remain
empty unless the server gives a I<BAD> or I<NO> response to the
I<SEARCH> command.

=head2 size

Example:

my $size = $imap->size($msgId)
    or die "Could not find size of message $msgId: $@\n";

The B<size> method accepts one input argument, a sequence number (or
message UID if the L</Uid> parameter is true).  It returns the size of
the message in the currently selected folder with the supplied
sequence number (or UID).  The IMAPClient object must be in a
I<Selected> state in order to use this method.

=head2 sort

Example:

my @msgs = $imap->sort(@args);
  warn "Error in sort: $@\n" if $@;

The B<sort> method is just like the L</search> method, only different.
It implements the SORT extension as described in
F<https://tools.ietf.org/html/rfc5256>.
It would be wise to use the L</has_capability> method to verify that
the SORT capability is available on your server before trying to use
the B<sort> method.  If you forget to check and you're connecting to a
server that doesn't have the SORT capability then B<sort> will return
undef.  L</LastError> will then say you are "BAD".  If your server
doesn't support the SORT capability then you'll have to use L</search>
and then sort the results yourself.

The first argument to B<sort> is a space-delimited list of sorting
criteria.  The Internet Draft that describes SORT requires that this
list be wrapped in parentheses, even if there is only one sort
criterion.  If you forget the parentheses then the B<sort> method will
add them.  But you have to forget both of them, or none.  This isn't
CMS running under VM!

The second argument is a character set to use for sorting.  Different
character sets use different sorting orders, so this argument is
important.  Since all servers must support UTF-8 and US-ASCII if they
support the SORT capability at all, you can use one of those if you
don't have some other preferred character set in mind.

The rest of the arguments are searching criteria, just as you would
supply to the L</search> method.  These are all documented in RFC3501.
If you just want all of the messages in the currently selected folder
returned to you in sorted order, use I<ALL> as your only search
criterion.

The B<sort> method returns an array containing sequence numbers of
messages that passed the SORT IMAP client command's search criteria.
If the L</Uid> parameter is true then the array will contain message
UID's.  If B<sort> is called in scalar context then a pointer to the
array will be passed, instead of the array itself.  The message
sequence numbers or unique identifiers are ordered according to the
sort criteria specified.  The sort criteria are nested in the order
specified; that is, items are sorted first by the first criterion, and
within the first criterion they are sorted by the second criterion,
and so on.

The sort method will clear C<$@> before attempting the I<SORT>
operation just as the L</search> method does.

=head2 starttls

Example:

$imap->starttls() or die "starttls failed: $@\n";

The B<starttls> method accepts no arguments.  This method is used to
upgrade an exiting connection which is not authenticated to a TLS/SSL
connection by using the IMAP STARTTLS command followed by using the
B<start_SSL> class method from L<IO::Socket::SSL> to do the necessary
TLS negotiation.  The negotiation is done in a blocking fashion with a
default B<Timeout> of 30 seconds.  The arguments used in the call to
B<start_SSL> can be controlled by setting the Mail::IMAPClient
L</Starttls> attribute to an ARRAY reference containing the desired
arguments.

Version note: method added in Mail::IMAPClient 3.22

=head2 status

Example:

my @rawdata = $imap->status( $folder, qw/(Messages)/ )
    or die "Error obtaining status: $@\n";

The B<status> method accepts one argument, the name of a folder (or
mailbox, to use RFC3501's terminology), and returns an array
containing the results of running the IMAP STATUS client command
against that folder.  If additional arguments are supplied then they
are appended to the IMAP STATUS client command string, separated from
the rest of the string and each other with spaces.

If B<status> is not called in an array context then it returns a
reference to an array rather than the array itself.

The B<status> method should not be confused with the B<Status> method
(with an uppercase 'S'), which returns information about the
IMAPClient object.  (See the section labeled L</"Status Methods">,
below).

=head2 store

Example:

$imap->store(@args) or die "Could not store: $@\n";

The B<store> method accepts a message sequence number or
comma-separated list of message sequence numbers as a first argument,
a message data item name, and a value for the message data item.
Currently, data items are the word "FLAGS" followed by a space and a
list of flags (in parens).  The word "FLAGS" can be modified by
prefixing it with either a "+" or a "-" (to indicate "add these flags"
or "remove these flags") and by suffixing it with ".SILENT" (which
reduces the amount of output from the server; very useful with large
message sets).  Normally you won't need to call B<store> because there
are oodles of methods that will invoke store for you with the correct
arguments.  Furthermore, these methods are friendlier and more
flexible with regards to how you specify your arguments.  See for
example L</see>, L</deny_seeing>, L</delete_message>, and
L</restore_message>.  Or L</mark>, L</unmark>, L</set_flag>, and
L</unset_flag>.

=head2 subject

Example:

my $subject = $imap->subject($msg);

The B<subject> method accepts one argument, a message sequence number
(or a message UID, if the I<Uid> parameter is true).  The text in the
"Subject" header of that message is returned (without the "Subject: "
prefix).  This method is a short-cut for:

my $subject = $imap->get_header($msg, "Subject");

=head2 subscribed

Example:

my @subscribedFolders = $imap->subscribed
    or warn "Could not find subscribed folders: $@\n";

The B<subscribed> method works like the B<folders> method, above,
except that the returned list (or array reference, if called in scalar
context) contains only the subscribed folders.

Like L</folders>, you can optionally provide a prefix argument to the
B<subscribed> method.

=head2 tag_and_run

Example:

my $output = $imap->tag_and_run(@args)
    or die "Could not tag_and_run: $@\n";

The B<tag_and_run> method accepts one or two arguments.  The first
argument is a string containing an IMAP client command, without a tag
but with all required arguments.  The optional second argument is a
string to look for that will indicate success (without pattern
delimiters).  The default is C<OK.*>.

The B<tag_and_run> method will prefix your string (from the first
argument) with the next transaction number and run the command.  It
returns an array of output lines from the command, which you are free
to parse as you see fit.  Using this method instead of B<run> (above)
will free you from having to worry about handling the tags (and from
worrying about the side affects of naming your own tags).

=head2 uidexpunge

Example:

$imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";

The B<uidexpunge> method implements the UID EXPUNGE IMAP (RFC4315
UIDPLUS ext) client command to permanently remove all messages that
have the \Deleted flag set and have a UID that is included in the list
of UIDs.

B<uidexpunge> returns an array or arrayref (scalar context) of output
lines returned from the UID EXPUNGE command.

B<uidexpunge> returns undef on failure.

If the server does not support the UIDPLUS extension, this method
returns undef.

=head2 uidnext

Example:

my $nextUid = $imap->uidnext($folder) or die "uidnext failed: $@\n";

The B<uidnext> method accepts one argument, the name of a folder, and
returns the numeric string that is the next available message UID for
that folder.

=head2 thread

Example:

my $thread = $imap->thread( $algorithm, $charset, @search_args );

The B<thread> method accepts zero to three arguments.  The first
argument is the threading algorithm to use, generally either
I<ORDEREDSUBJECT> or I<REFERENCES>.  The second argument is the
character set to use, and the third argument is the set of search
arguments to use.

If the algorithm is not supplied, it defaults to I<REFERENCES> if
available, or I<ORDEREDSUBJECT> if available.  If neither of these is
available then the B<thread> method returns undef.

If the character set is not specified it will default to I<UTF-8>.

If the search arguments are not specified, the default is I<ALL>.

If B<thread> is called for an object connected to a server that does
not support the THREADS extension then the B<thread> method will
return C<undef>.

The B<threads> method will issue the I<THREAD> command as defined in
F<https://tools.ietf.org/html/rfc5256>.
It returns an array of threads.  Each element in the array is either a
message id or a reference to another array of (sub)threads.

If the L</Uid> parameter is set to a true value then the message id's
returned in the thread structure will be message UID's.  Otherwise
they will be message sequence numbers.

=head2 uidvalidity

Example:

my $validity = $imap->uidvalidity($folder)
    or die "uidvalidity failed: $@\n";

The B<uidvalidity> method accepts one argument, the name of a folder,
and returns the numeric string that is the unique identifier validity
value for the folder.

=head2 unmark

Example:

$imap->unmark(@msgs) or die "Could not unmark: $@\n";

The B<unmark> method accepts a list of one or more messages sequence
numbers, or a single reference to an array of one or more message
sequence numbers, as its argument(s).  It then unsets the I<\Flagged>
flag for those message(s).  Of course, if the L</Uid> parameter is set
to a true value then those message sequence numbers should really be
unique message id's.

Note that specifying C<$imap-E<gt>unmark(@msgs)> is just a shortcut
for specifying C<$imap-E<gt>unset_flag("Flagged",@msgs)>.

Note also that the I<\Flagged> flag is just one of many possible
flags.  This is a little confusing, but you'll have to get used to the
idea that among the reserved flags specified in RFC3501 is one name
I<\Flagged>.  There is no specific meaning for this flag; it means
whatever the mailbox owner (or delegate) wants it to mean when it is
turned on.

=head2 unseen

Example:

my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";

The B<unseen> method performs an IMAP SEARCH UNSEEN search against the
selected folder and returns an array of sequence numbers of messages
that have not yet been seen (ie their I<\Seen> flag is not set).  If
the L</Uid> parameter is true then an array of message UID's will be
returned instead.  If called in scalar context than a pointer to the
array (rather than the array itself) will be returned.

=head2 unseen_count

Example:

foreach my $f ($imap->folders) {
      print "The $f folder has ",
        $imap->unseen_count($f)||0, " unseen messages.\n";
  }

The B<unseen_count> method accepts the name of a folder as an argument
and returns the number of unseen messages in that folder.  If no
folder argument is provided then it returns the number of unseen
messages in the currently selected Folder.

=head2 unset_flag

Example:

$imap->unset_flag( "\Seen", @msgs )
    or die "unset_flag failed: $@\n";

The B<unset_flag> method accepts the name of a flag as its first
argument and a list of one or more messages sequence numbers, or a
single reference to an array of one or more message sequence numbers,
as its next argument(s).  It then unsets the flag specified for those
message(s).  Of course, if the L</Uid> parameter is set to a true
value then those message sequence numbers had better be unique message
id's, just as you'd expect.

=head1 Other IMAP Client Commands

Until release C<2.99>, when you called a method which did not exist,
they where automatically translated into an IMAP call with the same
name via an AUTOLOAD hack.  This "feature" was removed for various
reasons: people made typos in the capitalization of method names, and
the program still seemed to work correctly.  Besides, it blocked
further development of this module, because people did not contribute
their private extensions to the protocol implementation.

=head2 copy($msg, $folder)

Copy a message from the currently selected folder in the folder whose
name is in C<$folder>

=head2 subscribe($folder)

Subscribe to a folder

B<CAUTION:> Once again, remember to quote your quotes (or use the
L</Quote> method) if you want quotes to be part of the IMAP command
string.

You can also use the default method to override the behavior of
implemented IMAP methods by changing the case of the method name,
preferably to all-uppercase so as not to conflict with the Class
method and accessor method namespace.  For example, if you don't want
the L</search> method's behavior (which returns a list of message
numbers) but would rather have an array of raw data returned from your
L</search> operation, you can issue the following snippet:

my @raw = $imap->SEARCH("SUBJECT","Whatever...");

which is slightly more efficient than the equivalent:

$imap->search("SUBJECT","Whatever...");
  my @raw = $imap->Results;

Of course you probably want the search results tucked nicely into a
list for you anyway, in which case you might as well use the
L</search> method.

=head1 Parameters

There are several parameters that influence the behavior of an
IMAPClient object.  Each is set by specifying a named value pair
during new method invocation as follows:

my $imap = Mail::IMAPClient->new ( parameter  => "value",
      parameter2 => "value",
      ...
  );

Parameters can also be set after an object has been instantiated by
using the parameter's eponymous accessor method like this:

my $imap = Mail::IMAPClient->new;
     $imap->parameter( "value");
     $imap->parameter2("value");

The eponymous accessor methods can also be used without arguments to
obtain the current value of the parameter as follows:

my $imap = Mail::IMAPClient->new;
     $imap->parameter( "value");
     $imap->parameter2("value");

...    # A whole bunch of awesome Perl code, omitted for brevity

my $forgot  = $imap->parameter;
  my $forgot2 = $imap->parameter2;

Note that in these examples I'm using 'parameter' and 'parameter2' as
generic parameter names.  The IMAPClient object doesn't actually have
parameters named 'parameter' and 'parameter2'.  On the contrary, the
available parameters are:

=head2 Authmechanism

Example:

$imap->Authmechanism("CRAM-MD5");
  # or
  my $authmech = $imap->Authmechanism();

If specified, the I<Authmechanism> causes the specified authentication
mechanism to be used whenever Mail::IMAPClient would otherwise invoke
B<login>.  If the value specified for the I<Authmechanism> parameter
is not a valid authentication mechanism for your server then you will
never ever be able to log in again for the rest of your Perl script,
probably.  So you might want to check, like this:

my $authmech = "CRAM-MD5";
  $imap->has_capability($authmech) and $imap->Authmechanism($authmech);

Of course if you know your server supports your favorite authentication
mechanism then you know, so you can then include your I<Authmechanism>
with your B<new> call, as in:

my $imap = Mail::IMAPClient->new(
      User    => $user,
      Passord => $passord,
      Server  => $server,
      Authmechanism  => $authmech,
      %etc
  );

If I<Authmechanism> is supplied but I<Authcallback> is not then you
had better be supporting one of the authentication mechanisms that
Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).

=head2 Authcallback

Example:

$imap->Authcallback( \&callback );

This specifies a default callback to the default authentication
mechanism (see L</Authmechanism>, above).  Together, these two methods
replace automatic calls to login with automatic calls that look like
this (sort of):

$imap->authenticate($imap->Authmechanism,$imap->Authcallback);

If I<Authmechanism> is supplied but I<Authcallback> is not then you
had better be supporting one of the authentication mechanisms that
Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).

=head2 Authuser

The I<Authuser> parameter is used by the DIGEST-MD5 L</Authmechanism>.

Typically when you authenticate the username specified in the User
parameter is used.  However, when using the DIGEST-MD5
I<Authmechanism> the I<Authuser> can be used to specify a different
username for the login.

This can be useful to mark messages as seen for the I<Authuser> if you
don't know the password of the user as the seen state is often a
per-user state.

=head2 Buffer

Example:

$Buffer = $imap->Buffer();
  # or:
  $imap->Buffer($new_value);

The I<Buffer> parameter sets the size of a block of I/O.  It is
ignored unless L</Fast_io>, below, is set to a true value (the
default), or unless you are using the L</migrate> method.  It's value
should be the number of bytes to attempt to read in one I/O operation.
The default value is 4096.

When using the L</migrate> method, you can often achieve dramatic
improvements in throughput by adjusting this number upward.  However,
doing so also entails a memory cost, so if set too high you risk
losing all the benefits of the L</migrate> method's chunking
algorithm.  Your program can thus terminate with an "out of memory"
error and you'll have no one but yourself to blame.

Note that, as hinted above, the I<Buffer> parameter affects the
behavior of the L</migrate> method regardless of whether you have
L</Fast_io> turned on.  Believe me, you don't want to go around
migrating tons of mail without using buffered I/O!

=head2 Clear

Example:

$Clear = $imap->Clear();
  # or:
  $imap->Clear($integer);

The name of this parameter, for historical reasons, is somewhat
misleading.  It should be named I<Wrap>, because it specifies how many
transactions are stored in the wrapped history buffer.  But it didn't
always work that way; the buffer used to actually get cleared.  The
name though remains the same in the interests of backwards
compatibility.

I<Clear> specifies that the object's history buffer should be wrapped
after every I<n> transactions, where I<n> is the value specified for
the I<Clear> parameter.  Calling the eponymous B<Clear> method without
an argument will return the current value of the I<Clear> parameter
but will not cause clear the history buffer to wrap.

Setting I<Clear> to 0 turns off automatic history buffer wrapping, and
setting it to 1 turns off the history buffer facility (except for the
last transaction, which cannot be disabled without breaking the
IMAPClient module).  Setting I<Clear> to 0 will not cause an immediate
clearing of the history buffer; setting it to 1 (or any other number)
will (except of course for that inevitable last transaction).

The default I<Clear> value is set to five (5) in order to conserve
memory.

=head2 Compress

If set, Mail::IMAPClient attempts to enable use of the RFC4978
COMPRESS DEFLATE extension.  This requires that the server supports
this CAPABILITY.  This attribute can be set to a true value to enable
or an ARRAYREF to control the arguments used in the call to
Compress::Zlib::deflateInit().

Mail::IMAPClient will automatically use L<Compress::Zlib> to
deflate/inflate the data to/from the server.  This attribute is used
in the L</login> method.

See also L</compress> and L</capability>.

Version note: attribute added in Mail::IMAPClient 3.30

=head2 Debug

Example:

$Debug = $imap->Debug();
  # or:
  $imap->Debug($true_or_false);

Sets the debugging flag to either a true or false value.  Can be
supplied with the L</new> method call or separately by calling the
B<Debug> object method.  Use of this parameter is strongly recommended
when debugging scripts and required when reporting bugs.

=head2 Debug_fh

Example:

$Debug_fh = $imap->Debug_fh();
  # or:
  $imap->Debug_fh($fileHandle);

Specifies the file handle to which debugging information should be
printed.  It can either a file handle object reference or a file handle
glob.  The default is to print debugging info to STDERR.

For example, you can:

use Mail::IMAPClient;
  use IO::File;
  # set $user, $pass, and $server here
  my $dh = IO::File->new(">debugging.output")
    or die "Can't open debugging.output: $!\n";
  my $imap = Mail::IMAPClient->new(
      User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh
  );

which is the same as:

use Mail::IMAPClient;
  use IO::File;
  # set $user, $pass, and $server here
  my $imap = Mail::IMAPClient->new(
      User     => $user,
      Password => $pass,
      Server   => $server,
      Debug    => "yes, please",
      Debug_fh => IO::File->new(">debugging.output")
        || die "Can't open debugging.output: $!\n"
  );

You can also:

use Mail::IMAPClient;
  # set $user, $pass, and $server here
  open(DBG,">debugging.output")
    or die "Can't open debugging.output: $!\n";
  my $imap = Mail::IMAPClient->new(
    User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG
  );

Specifying this parameter is not very useful unless L</Debug> is set
to a true value.

=head2 Domain

The I<Domain> parameter is used by the NTLM L</Authmechanism>.  The
domain is an optional parameter for NTLM authentication.

=head2 EnableServerResponseInLiteral

Removed in 2.99_01 (now autodetect)

=head2 Fast_io

Example:

$Fast_io = $imap->Fast_io();
  # or:
  $imap->Fast_io($true_or_false);

The I<Fast_io> parameter controls whether or not the Mail::IMAPClient
object will attempt to use non-blocking I/O on the IMAP socket.  It is
turned on by default (unless the caller provides the socket to be
used).

MR SKB