text: Mail::IMAPClient - An IMAP Client API";
  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 "new" constructor method. Once the object has been instantiated, the "connect" method is either implicitly or explicitly called. At that point methods are available that implement the IMAP client commands as specified in RFC.
  RFC3501 defines four possible states for an IMAP connection: not authenticated, authenticated, selected, and logged out. These correspond to the IMAPClient constants
  Connected,
  Authenticated,
  Selected, and
  Unconnected, respectively. These constants can be used in conjunction with the "Status" method to determine the status of an IMAPClient object and its underlying IMAP session.
  Note that an IMAPClient object can be in the
  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 "Status Methods", below.
  RFC3501 defines two commands for authenticating to an IMAP server:
  LOGIN is for plain text authentication.
  AUTHENTICATE for more advanced and/or secure authentication mechanisms.
  Mail::IMAPClient supports the following AUTHENTICATE mechanisms:
  DIGEST-MD5 authentication requires the Authen::SASL and Digest::MD5 modules. See also "Authuser".
  CRAM-MD5 requires the Digest::HMAC_MD5 module. authentication requires the Authen::NTLM module. See also "Domain"..
  RFC3501 "Transaction"" parameter for more information.
  The "Report". Note that if the "new" method is called as an object method, the object returned is identical to what have would been returned if "new" had been called as a class method. It doesn't give you a copy of the original object.
  Example:
  my $imap = Mail::IMAPClient->new(%args) or die "new failed: $@\n";
  The "new" method creates a new instance of an IMAPClient object.
  If the "Server" parameter is passed as an argument to new, then new will implicitly call the "connect" method, placing the new object in the Connected state. If "User" and "Password" values are also provided, then "connect" will in turn call "login",", "connect" and "login" for more information on how to manually connect and login after new. appropriately. "append", "search", etc. can be further broken down into two types, Parameter accessor methods, which affect the behavior of future mailbox methods, and "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 "Transaction", "Status", and "History" >.
  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:
  the name of the folder to append the message to
  the message text (including headers) of the message
  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..
  Returns:
  On error, undef can be returned regardless of LIST/SCALAR context. Check "LastError" for details.
  With UIDPLUS the UID of the new message is returned otherwise a true value (currently $self) is returned.
  To protect against "bare newlines", append will insert a carriage return before any newline that is "bare".:
  the name of the folder to append the message to
  a filename, filehandle or SCALAR reference which holds an RFC822-formatted message
  a deprecated argument used as a place holder for backwards compatibility
  The optional argument is handled the same as append_string.
  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.
  Returns:
  On error, undef can be returned regardless of LIST/SCALAR context. Check "LastError" for details.
  With UIDPLUS the UID of the new message is returned otherwise a true value (currently $self) is returned.
  To protect against "bare newlines", append.
  Example:
  my @msgs = $imap->before($Rfc3501_date) or warn "No messages found before $Rfc3501: ", $imap->LastError;: ", $imap->LastError;: ",  the initialization process.
  Version note: method added in Mail::IMAPClient 3.30 "login" method after connecting and return the result of the "login" method to connect's caller. If either or both of the "User" and "Password" parameters are unavailable but the connection to the server succeeds then connect returns a pointer to the IMAPClient object.
  The "Server" parameter must be set (either during "new" method invocation or via the "Server" object method) before invoking connect. When the parameter is an absolute file path, an UNIX socket will get opened. If the "Server" parameter is supplied to the "new" currently.) mileage.
  ADDITIONAL NOTE: In the grand tradition of the IMAP protocol, deleting a message doesn't actually delete the message. Really. If you want to make sure the message has been deleted, you need to expunge the folder (via the "expunge" method, which is implemented via the default method). Or at least "close" it. This is generally considered a feature, since after deleting a message, you can change your mind and undelete it at any time before your "expunge" or "close".
  See also: the "delete" method, to delete a folder, the "expunge" method, to expunge a folder, the "restore_message" method to undelete a message, and the "close" method (implemented here via the default method) to close a folder. Oh, and don't forget about RFC3501. logout: $@\n";
  This method calls "logout", see "logout" for details.". "select".
  Usage:
  $imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
  Example:
  my $hashref = {}; $imap->fetch_hash( "RFC822.SIZE", $hashref ); print "Msg #$m is $hashref->{$m} bytes\n" foreach my $m (keys %$hashref);
  The fetch_hash method accepts a list of message attributes to be fetched (as described in RFC3501). Data::Dumper', } };. Mail::IMAPClient::BodyStructure Mail::IMAPClient::BodyStructure white space ". "folders" method, above.)
  An
  undef value is returned in case of errors. Be sure to check for it. commmand.. "subscribed" "status" method (see above) and parses out the results to obtain the number of messages. If you don't supply an argument to message_count then it will return the number of messages in the currently selected folder (assuming of course that you've used the "select" or "examine" method to select it instead of trying something funky). Note that RFC2683 contains warnings about the use of the IMAP STATUS command (and thus the "status" method and therefore the message_count method) against the currently selected folder. You should carefully consider this before using message_count on the currently selected folder. You may be better off using "search" or one of its variants (especially "messages"), and then counting the results. On the other hand, I regularly violate this rule on my server without suffering any dire consequences. Your mileage handle, if a file handle is passed). The returned value is true on success and
  undef on failure.
  If the first argument is a reference, it is assumed to be an open file handle and will not be closed when the method completes, If it is a file, it is opened in append mode, written to, then closed.
  Note that using this method will set the message's "\Seen" flag as a side effect. But you can use the "deny_seeing" method to set it back, or set the "Peek" currently_src->migrate( $imap_dest, "ALL", $targetFolder ) or die "Could not migrate: ", $imap_src->LastError;
  The migrate method copies the indicated message(s) from the currently selected folder to another Mail::IMAPClient object's session. It requires these arguments:
  "search"("ALL").
  The target ($imap_dest) Mail::IMAPClient object must not be the same object as the source ($imap_src).
  This method does not attempt to minimize memory usage. In the future it could be enhanced to (optionaly) write message data to a temporary file to avoid storing the entire message in memory.
  To work around potential network timeouts on large messages, consider setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
  See also
  Supportedflags.:
  a successful, "expunge" (or "close"). 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 ];
  Example:
  my @msgs = $imap->on($Rfc3501_date) or warn "Could not find messages sent on $Rfc3501_date: $@\n";
  The on method works just like the "since" formatted "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 "get_envelope" method as an alternative to "parse_headers". );  "delete_message" operation (but not if there has been an intervening "expunge" or "close"). The IMAPClient object must be in "Selected" status to use the restore_message method.
  The restore_message method accepts a list of arguments. If the "Uid" parameter is not set to a true value, then each item in the list should be either:
  a message sequence number,
  a comma-separated list of message sequence numbers,
  a reference to an array of message sequence numbers, or
  If the "Uid" parameter is set to a true value, then each item in the list should be either:
  a message UID,
  a comma-separated list of UID's, or
  a reference to an array of message UID's.";
  The run method is provided to make those uncommon things possible... however, we would like you to contribute the knowledge of missing features with us. (or arrayref in scalar context) tags then see "tag_and_run", below.):3501_date) or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
  The sentbefore method works just like "sentsince", below, except it searches for messages that were sent before the date supplied as an argument to the method.3501. 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.)
  Example:
  $imap->setacl( $folder, $userid, $acl perlfunc and as accepted by "localtime" in perlfunc) or in the date_text format as defined in RFC3501  "search",); warn "Error in sort: $@\n" if $@;
  The sort method is just like the "search" method, only different. It implements the SORT extension as described in. It would be wise to use the "has_capability" "search" "search" method. These are all documented in RFC3501. "search" method does.
  Example:
  my @rawdata = $imap->status( $folder, qw/(Messages)/ ) or die "Error obtaining status: $@\n";
  The status method accepts one argument, the name of a folder (or mailbox, to use RFC3501 "see", "deny_seeing", "delete_message", and "restore_message". Or "mark", "unmark", "set_flag", and "unset_flag". "folders",:
  3501. a message from the currently selected folder in the the folder whose name is in
   "search" method's behavior (which returns a list of message numbers) but would rather have an array of raw data returned from your "search" "search")..
  Example:
  $Buffer = $imap->Buffer(); # or: $imap->Buffer($new_value);
  The Buffer parameter sets the size of a block of I/O. It is ignored unless "Fast_io", below, is set to a true value (the default), or unless you are using the "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 "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 "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 Buffer parameter affects the behavior of the "migrate" method regardless of whether you have "Fast_io" turned on. Believe me, you don't want to go around migrating tons of mail without using buffered I/O!
  Example:
  $Clear = $imap->Clear(); # or: $imap->Clear($integer); (5) in order to conserve memory.
  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 "new" method call or separately by calling the Debug object method. Use of this parameter is strongly recommended when debugging scripts and required when reporting bugs.
  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=>1, "Debug" is set to a true value.
  The Domain parameter is used by the NTLM "Authmechanism". The domain is an optional parameter for NTLM authentication.
  Removed in 2.99_01 (now autodetect)).
  Example:
  $Folder = $imap->Folder(); # or: $imap->Folder($new_value);
  The Folder parameter returns the name of the currently-selected folder (in case you forgot). It can also be used to set the name of the currently selected folder, which is completely unnecessary if you used the "select" method (or "select"'s read-only equivalent, the "examine" method) to select it.
  Note that setting the Folder parameter does not automatically select a new folder; you use the "select" or "examine".
  Certain (caching) servers, like Exchange 2007, often report the wrong message size. Instead of chopping the message into a size that it fits the specified size, the reported size will be simply ignored when this parameter is set to. "new" "body_string", "message_string" and "message_to_file". A default value of 993 (if "Ssl" is true) or 143 is set during a call to "connect" if no value is provided by the caller. This argument can be supplied with the "new" method call or separately by calling the "Port" object method..
  See also "Readmethod". "search" method will return a Mail::IMAPClient::MessageSet.($ssl);
  then it will be up to you to establish the connection AND to authenticate, either via the "login" method, or the fancier "authenticate", or, since you know so much anyway, by just doing raw I/O against the socket until you're logged in. If you do any of this then you should also set the "State" parameter yourself to reflect the current state of the object (i.e. Connected, Authenticated, etc). "Socket".
  See also "Prewritemethod".
  Example:
  $Server = $imap->Server(); # or: $imap->Server($hostname);
  Specifies the hostname or IP address of the host running the IMAP server. If provided as part of the "new" method call, then the new IMAP object will automatically be connected at the time of instantiation. (See the "new" method, below.) Can be supplied with the "new" occured.
  Version note: attribute added in Mail::IMAPClient 3.22
  If an IMAP connection requires SSL you can set the Ssl attribute to '1' and Mail::IMAPClient will automatically use IO::Socket::SSL instead of IO::Socket::INET to connect to the server. This attribute is used in the "connect" method.
  See also "connect" for details on connection initiatiation and "Socket" and "Rawsocket" if you need to take more control of connection management.
  Version note: attribute added in Mail::IMAPClient 3.18.
  Example:
  $Uid = $imap->Uid(); # or: $imap->Uid($true_or_false);
  If "Uid" is set to a true value (i.e. 1) then the behavior of the "fetch", "search", "copy", and "store" methods (and their derivatives) is changed so that arguments that would otherwise be message sequence numbers are treated as message UID's and so that return values (in the case of the "search"35 "search" "new" method call or separately by calling the User object method.
  Parameters can be set during "new" "new" method invocation. The status methods are:
  Example:
  my @results = $imap->Escaped_results;
  The Escaped_results method is almost identical to the History method. Unlike the History method, however, server output transmitted literally will be wrapped in double quotes, with all of the parentheses, double quotes, backslashes, newlines, and carriage "Results" method. Unlike the "Results" "exists" method to see if a folder exists and the folder does not exist, then an error message will be recorded in LastError even though this is not a particularly serious error. On the other hand, if you didn't use "exists" and just tried to "select" a non-existing folder, then "select" "Status", below.
  Normally you will not have to invoke this function. An exception is if you are bypassing the Mail::IMAPClient module's "connect" and/or "login" modules to set up your own connection (say, for example, over a secure socket), in which case you must manually do what the "connect" and "login" methods would otherwise do for you.. "authenticate". also, examples/imtestExample.pl, can be found in the
  examples subdirectory of the source distribution.
  The following list summarizes the methods and parameters that you may find useful in implementing advanced authentication:
  The "authenticate" method uses the "Authmechanism" parameter to determine how to authenticate with the server see the method documentation for details..
  If you need to make your own connection to the server and perform your authentication manually, then you can set these parameters to keep your Mail::IMAPClient object in sync with its actual status. Of these, only the "State" parameter is always necessary. The others need to be set only if you think your program will need them later." "authenticate" method to the server..
  Please send bug reports to
  bug-Mail-IMAPClient@rt.cpan.org or
  Copyright (C) 1999-2003 The Kernen Group, Inc. Copyright (C) 2007-2009 Mark Overmeer Copyright (C) 2010-2012.