1Mail::IMAPClient(3)   User Contributed Perl Documentation  Mail::IMAPClient(3)
2
3
4

NAME

6       Mail::IMAPClient - An IMAP Client API
7

SYNOPSIS

9         use Mail::IMAPClient;
10
11         my $imap = Mail::IMAPClient->new(
12           Server   => 'localhost',
13           User     => 'username',
14           Password => 'password',
15           Ssl      => 1,
16           Uid      => 1,
17         );
18
19         my $folders = $imap->folders
20           or die "List folders error: ", $imap->LastError, "\n";
21         print "Folders: @$folders\n";
22
23         $imap->select( $Opt{folder} )
24           or die "Select '$Opt{folder}' error: ", $imap->LastError, "\n";
25
26         $imap->fetch_hash("FLAGS", "INTERNALDATE", "RFC822.SIZE")
27           or die "Fetch hash '$Opt{folder}' error: ", $imap->LastError, "\n";
28
29         $imap->logout
30           or die "Logout error: ", $imap->LastError, "\n";
31

DESCRIPTION

33       This module provides methods implementing the IMAP protocol to support
34       interacting with IMAP message stores.
35
36       The module is used by constructing or instantiating a new IMAPClient
37       object via the "new" constructor method.  Once the object has been
38       instantiated, the "connect" method is either implicitly or explicitly
39       called.  At that point methods are available that implement the IMAP
40       client commands as specified in RFC3501.  When processing is complete,
41       the "logout" object method should be called.
42
43       This documentation is not meant to be a replacement for RFC3501 nor any
44       other IMAP related RFCs.
45
46       Note that this documentation uses the term folder in place of RFC3501's
47       use of mailbox.  This documentation reserves the use of the term
48       mailbox to refer to the set of folders owned by a specific IMAP id.
49
50   Connection State
51       RFC3501 defines four possible states for an IMAP connection: not
52       authenticated, authenticated, selected, and logged out.  These
53       correspond to the IMAPClient constants "Connected", "Authenticated",
54       "Selected", and "Unconnected", respectively.  These constants can be
55       used in conjunction with the "Status" method to determine the status of
56       an IMAPClient object and its underlying IMAP session.
57
58       Note that an IMAPClient object can be in the "Unconnected" state both
59       before a server connection is made and after it has ended.  This
60       differs slightly from RFC3501, which does not define a pre-connection
61       status.  For a discussion of the methods available for examining the
62       IMAPClient object's status, see the section labeled "Status Methods",
63       below.
64
65   Advanced Authentication Mechanisms
66       RFC3501 defines two commands for authenticating to an IMAP server:
67
68       LOGIN
69           LOGIN is for plain text authentication.
70
71       AUTHENTICATE
72           AUTHENTICATE for more advanced and/or secure authentication
73           mechanisms.
74
75       Mail::IMAPClient supports the following AUTHENTICATE mechanisms:
76
77       DIGEST-MD5
78           DIGEST-MD5 authentication requires the Authen::SASL and Digest::MD5
79           modules.  See also "Authuser".
80
81       CRAM-MD5
82           CRAM-MD5 requires the Digest::HMAC_MD5 module.
83
84       PLAIN (SASL)
85           PLAIN (SASL) authentication allows the optional use of the "Proxy"
86           parameter.  RFC 4616 documents this syntax for SASL PLAIN:
87
88             message = [authzid] UTF8NUL authcid UTF8NUL passwd
89
90           When "Proxy" is defined, "User" is used as 'authzid' and "Proxy" is
91           used as 'authcid'.  Otherwise, "User" is used as 'authcid'.
92
93       NTLM
94           NTLM authentication requires the Authen::NTLM module.  See also
95           "Domain".
96
97   Errors
98       If you attempt an operation that results in an error, then you can
99       retrieve the text of the error message by using the "LastError" method.
100       However, the "LastError" method is an object method (not a class
101       method) and can only be used once an object is successfully created.
102       In cases where an object is not successfully created the $@ variable is
103       set with an error message.
104
105       Mail::IMAPClient resets $@ and "LastError" to undef before most IMAP
106       requests, so the values only have a short lifespan.  "LastError" will
107       always contain error info from the last error, until another error is
108       encountered, another IMAP command is issued or it is explicitly
109       cleared.
110
111       Please note that the use of $@ is subject to change in the future
112       release so it is best to use "LastError" for error checking once a
113       Mail::IMAPClient object has been created.
114
115       Errors in the "new" method can prevent your object from ever being
116       created.  If the "Server", "User", and "Password" parameters are
117       supplied to "new", it will attempt to call "connect" and "login".  Any
118       of these methods could fail and cause the "new" method call to return
119       "undef" and leaving the variable $@ is set to an error message.
120
121       WARNING: (due to historical API behavior) on errors, many methods may
122       return undef regardless of LIST/SCALAR context.  Therefore, it may be
123       wise to use most methods in a scalar context.  Regardless, check
124       "LastError" for details on errors.
125
126   Transactions
127       RFC3501 requires that each line in an IMAP conversation be prefixed
128       with a tag.  A typical conversation consists of the client issuing a
129       tag-prefixed command string, and the server replying with one of more
130       lines of output.  Those lines of output will include a command
131       completion status code prefixed by the same tag as the original command
132       string.
133
134       The IMAPClient module uses a simple counter to ensure that each client
135       command is issued with a unique tag value.  This tag value is referred
136       to by the IMAPClient module as the transaction number.  A history is
137       maintained by the IMAPClient object documenting each transaction.  The
138       "Transaction" method returns the number of the last transaction, and
139       can be used to retrieve lines of text from the object's history.
140
141       The "Clear" parameter is used to control the size of the session
142       history so that long-running sessions do not eat up unreasonable
143       amounts of memory.  See the discussion of "Clear" parameter for more
144       information.
145
146       The "Report" transaction returns the history of the entire IMAP session
147       since the initial connection or for the last "Clear" transactions.
148       This provides a record of the entire conversation, including client
149       command strings and server responses, and is a wonderful debugging tool
150       as well as a useful source of raw data for custom parsing.
151

CLASS METHODS

153       There are a couple of methods that can be invoked as class methods.
154       Generally they can be invoked as an object method as well.  Note that
155       if the "new" method is called as an object method, the object returned
156       is identical to what have would been returned if "new" had been called
157       as a class method.  It doesn't give you a copy of the original object.
158
159   new
160       Example:
161
162         my $imap = Mail::IMAPClient->new(%args)
163           or die "new failed: $@\n";
164
165       The "new" method creates a new instance of an IMAPClient object.
166
167       If the "Server" parameter is passed as an argument to new, then new
168       will implicitly call the "connect" method, placing the new object in
169       the Connected state.  If "User" and "Password" values are also
170       provided, then "connect" will in turn call "login", and the resulting
171       object will be returned from new in the Authenticated state.
172
173       If the "Server" parameter is not supplied then the IMAPClient object is
174       created in the Unconnected state.
175
176       If the new method is passed arguments then those arguments will be
177       treated as a list of key=>value pairs.  The key should be one of the
178       parameters as documented under "Parameters" below.
179
180       Here are some examples:
181
182         use Mail::IMAPClient;
183
184         # returns an unconnected Mail::IMAPClient object:
185         my $imap = Mail::IMAPClient->new;
186         # ...
187         # intervening code using the 1st object, then:
188         # (returns a new, authenticated Mail::IMAPClient object)
189         $imap = Mail::IMAPClient->new(
190             Server   => $host,
191             User     => $id,
192             Password => $pass,
193             Clear    => 5,   # Unnecessary since '5' is the default
194             # ...            # Other key=>value pairs go here
195         ) or die "Cannot connect to $host as $id: $@";
196
197       See also "Parameters", "connect" and "login" for more information on
198       how to manually connect and login after new.
199
200   Quote
201       Example:
202
203         $imap->search( HEADER => 'Message-id' => \$imap->Quote($msg_id) );
204
205       The Quote method accepts a value as an argument and returns its
206       argument as a correctly quoted string or a literal string.  Since
207       version 3.17 Mail::IMAPClient automatically quotes search arguments we
208       use a SCALARREF so search will not modify or re-quote the value
209       returned by Quote.
210
211       Note this method should not be used on folder names for
212       Mail::IMAPClient methods, since methods that accept folder names as an
213       argument will quote the folder name arguments automatically.
214
215       If you are getting unexpected results when running methods with values
216       that have (or might have) embedded spaces, double quotes, braces, or
217       parentheses, then calling Quote may be necessary.  This method should
218       not be used with arguments that are wrapped in quotes or parens if
219       those quotes or parens are required by RFC3501.  For example, if the
220       RFC requires an argument in this format:
221
222         ( argument )
223
224       and the argument is (or might be) "pennies (from heaven)", then one
225       could use:
226
227         $argument = "(" . $imap->Quote($argument) . ")"
228
229       Of course, the fact that sometimes these characters are sometimes
230       required delimiters is precisely the reason you must quote them when
231       they are not delimiting.
232
233       However, there are times when a method fails unexpectedly and may
234       require the use of Quote to work.  Should this happen, you can probably
235       file a bug/enhancement request for Mail::IMAPClient to safeguard the
236       particular call/case better.
237
238       An example is RFC822 Message-id's, which usually don't contain quotes
239       or parens.  When dealing with these it is usually best to take
240       proactive, defensive measures from the very start and use Quote.
241
242   Range
243       Example:
244
245         my $parsed = $imap->parse_headers(
246             $imap->Range( $imap->messages ), "Date", "Subject"
247         );
248
249       The Range method will condense a list of message sequence numbers or
250       message UID's into the most compact format supported by RFC3501.  It
251       accepts one or more arguments, each of which can be:
252
253       a) a message number,
254       b) a comma-separated list of message numbers,
255       c) a colon-separated range of message numbers (i.e. "$begin:$end")
256       d) a combination of messages and message ranges, separated by commas
257       (i.e. 1,3,5:8,10), or
258       e) a reference to an array whose elements are like a) through d).
259
260       The Range method returns a Mail::IMAPClient::MessageSet object.  The
261       object uses overload and if treated as a string it will act like a
262       string.  This means you can ignore its objectivity and just treat it
263       like a string whose value is your message set expressed in compact
264       format.
265
266       This method provides an easy way to add or remove messages from a
267       message set.
268
269       For more information see Mail::IMAPClient::MessageSet.
270
271   Rfc3501_date
272       Example:
273
274         $Rfc3501_date = $imap->Rfc3501_date($seconds);
275         # or:
276         $Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);
277
278       The Rfc3501_date method accepts one input argument, a number of seconds
279       since the epoch date.  It returns an RFC3501 compliant date string for
280       that date (as required in date-related arguments to SEARCH, such as
281       "since", "before", etc.).
282
283   Rfc3501_datetime
284       Example:
285
286         $date = $imap->Rfc3501_datetime($seconds);
287         # or:
288         $date = Mail::IMAPClient->Rfc3501_datetime($seconds);
289
290       The Rfc3501_datetime method accepts one or two arguments: a obligatory
291       timestamp and an optional zone.  The zone shall be formatted as
292       "[+-]\d{4}", and defaults to +0000.  The timestamp follows the
293       definition of the output of the platforms specific "time", usually in
294       seconds since Jan 1st 1970.  However, you have to correct the number
295       yourself for the zone.
296
297   Rfc822_date
298       Example:
299
300         $Rfc822_date = $imap->Rfc822_date($seconds);
301         # or:
302         $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
303
304       The Rfc822_date method accepts one input argument, a number of seconds
305       since the epoch date.  It returns an RFC822 compliant date string for
306       that date (without the 'Date:' prefix).  Useful for putting dates in
307       message strings before calling "append", "search", etc.
308
309   Strip_cr
310       Examples:
311
312         my $stripped = $imap->Strip_cr($string);
313         # or:
314         my @list = $imap->some_imap_method;
315         @list = $imap->Strip_cr(@list);
316         # or:
317         my $list = [ $imap->some_imap_method ];   # returns an array ref
318         $list = $imap->Strip_cr($list);
319
320       The Strip_cr method strips carriage returns from input and returns the
321       new string to the caller.  This method accepts one or more lines of
322       text as arguments, and returns those lines with all <CR><LF> sequences
323       changed to <LF>.  Any input argument with no carriage returns is
324       returned unchanged.  If the first argument (not counting the class name
325       or object reference) is an array reference, then members of that array
326       are processed as above and subsequent arguments are ignored.  If the
327       method is called in scalar context then an array reference is returned
328       instead of an array of results.
329
330       NOTE: Strip_cr does not remove new line characters.
331

OBJECT METHODS

333       Object methods must be invoked against objects created via the "new"
334       method and cannot be invoked as class methods.
335
336       There object methods typically fall into one of two categories.  There
337       are mailbox methods which participate in the IMAP session's
338       conversation (i.e. they issue IMAP client commands) and object control
339       methods which do not result in IMAP commands but which may affect later
340       commands or provide details of previous ones.
341
342       This object control methods can be further broken  down into two types,
343       Parameter accessor methods, which affect the behavior of future mailbox
344       methods, and "Status Methods", which report on the affects of previous
345       mailbox methods.
346
347       Methods that do not result in new IMAP client commands being issued
348       (such as the "Transaction", "Status", and "History" methods) all begin
349       with an uppercase letter, to distinguish them from methods that do
350       correspond to IMAP client commands.  Class methods and eponymous
351       parameter methods likewise begin with an uppercase letter because they
352       also do not correspond to an IMAP client command.
353
354       As a general rule, mailbox control methods return "undef" on failure
355       and something besides "undef" when they succeed.  This rule is modified
356       in the case of methods that return search results.  When called in a
357       list context, searches that do not find matching results return an
358       empty list.  When called in a scalar context, searches with no hits
359       return 'undef' instead of an array reference.  If you want to know why
360       you received no hits, you should check "LastError" or $@, which will be
361       empty if the search was successful but had no matching results but
362       populated with an error message if the search encountered a problem
363       (such as invalid parameters).
364
365       A number of IMAP commands do not have corresponding Mail::IMAPClient
366       methods.  Patches are welcome.  In the pre-2.99 releases of this
367       module, they were automatically created (AUTOLOAD), but that was very
368       error-prone and stalled the progress of this module.
369

Mailbox Control Methods

371   append
372       Example:
373
374         my $uid_or_true = $imap->append( $folder, $msgtext )
375           or die "Could not append: ", $imap->LastError;
376
377       WARNING: This method may be deprecated in the future, consider using
378       "append_string" instead of this method.
379
380       The append method adds a message to the specified folder.  See
381       "append_string" for details as it is effectively an alias for that
382       method.
383
384       DEPRECATED BEHAVIOR: Additional arguments are added to the message
385       text, separated with <CR><LF>.
386
387   append_string
388       Example:
389
390          # brackets indicate optional arguments (not array refs):
391          my $uidort = $imap->append_string( $folder, $msgtext [,$flags [,$date ] ] )
392              or die "Could not append_string: ", $imap->LastError;
393
394       Arguments:
395
396       $folder
397           the name of the folder to append the message to
398
399       $msgtext
400           the message text (including headers) of the message
401
402       $flags
403           An optional list of flags to set.  The list must be specified as a
404           space-separated list of flags, including any backslashes that may
405           be necessary and optionally enclosed by parenthesis.
406
407       $date
408           An optional RFC3501 date argument to set as the internal date.  It
409           should be in the format described for date_time fields in RFC3501,
410           i.e. "dd-Mon-yyyy hh:mm:ss +0000".
411
412           If you want to specify a date/time but you don't want any flags
413           then specify undef as the third ($flags) argument.
414
415       Returns:
416
417       error: undef
418           On error, undef can be returned regardless of LIST/SCALAR context.
419           Check "LastError" for details.
420
421       success: UID or $imap
422           With UIDPLUS the UID of the new message is returned otherwise a
423           true value (currently $self) is returned.
424
425       To protect against "bare newlines", append will insert a carriage
426       return before any newline that is "bare".
427
428   append_file
429       Example:
430
431         my $new_msg_uid = $imap->append_file(
432             $folder,
433             $file,
434             [ undef, $flags, $date ] # optional
435         ) or die "Could not append_file: ", $imap->LastError;
436
437       The append_file method adds a message to the specified folder.  Note:
438       The brackets in the example indicate optional arguments; they do not
439       mean that the argument should be an array reference.
440
441       Arguments:
442
443       $folder
444           the name of the folder to append the message to
445
446       $file
447           a filename, filehandle or SCALAR reference which holds an
448           RFC822-formatted message
449
450       undef
451           a deprecated argument used as a place holder for backwards
452           compatibility
453
454       $flags
455           The optional argument is handled the same as append_string.
456
457       $date
458           The optional argument is handled the same as append_string (RFC3501
459           date), with the exception that if $date is "1" (one) then the
460           modification time (mtime) of the file will be used.
461
462       Returns:
463
464       error: undef
465           On error, undef can be returned regardless of LIST/SCALAR context.
466           Check "LastError" for details.
467
468       success: UID or $imap
469           With UIDPLUS the UID of the new message is returned otherwise a
470           true value (currently $self) is returned.
471
472       To protect against "bare newlines", append_file will insert a carriage
473       return before any newline that is "bare".
474
475       The append_file method provides a mechanism for allowing large messages
476       to be appended without holding the whole file in memory.
477
478       Version note: In 2.x an optional third argument to use for
479       "input_record_separator" was allowed, however this argument is
480       ignored/not supported as of 3.x.
481
482   authenticate
483       Example:
484
485         $imap->authenticate( $authentication_mechanism, $coderef )
486           or die "Could not authenticate: ", $imap->LastError;
487
488       This method implements the AUTHENTICATE IMAP client command.  It can be
489       called directly or may be called by "login" if the "Authmechanism"
490       parameter is set to anything except 'LOGIN'.
491
492       The authenticate method accepts two arguments, an authentication type
493       to be used (ie CRAM-MD5) and a code or subroutine reference to execute
494       to obtain a response.  The authenticate method assumes that the
495       authentication type specified in the first argument follows a
496       challenge-response flow.  The authenticate method issues the IMAP
497       Client AUTHENTICATE command and receives a challenge from the server.
498       That challenge (minus any tag prefix or enclosing '+' characters but
499       still in the original base64 encoding) is passed as the only argument
500       to the code or subroutine referenced in the second argument.  The
501       return value from the 2nd argument's code is written to the server as
502       is, except that a <CR><LF> sequence is appended if necessary.
503
504       If one or both of the arguments are not specified in the call to
505       authenticate but their corresponding parameters have been set
506       ("Authmechanism" and "Authcallback", respectively) then the parameter
507       values are used. Arguments provided to the method call however will
508       override parameter settings.
509
510       If you do not specify a second argument and you have not set the
511       "Authcallback" parameter, then the first argument must be one of the
512       authentication mechanisms for which Mail::IMAPClient has built in
513       support.
514
515       See also the "login" method, which is the simplest form of
516       authentication defined by RFC3501.
517
518   before
519       Example:
520
521         my @msgs = $imap->before($Rfc3501_date)
522           or warn "No messages found before $Rfc3501_date.\n";
523
524       The before method works just like the "since" method, below, except it
525       returns a list of messages whose internal system dates are before the
526       date supplied as the argument to the before method.
527
528   body_string
529       Example:
530
531         my $string = $imap->body_string($msgId)
532           or die "body_string failed: ", $imap->LastError;
533
534       The body_string method accepts a message sequence number (or a message
535       UID, if the "Uid" parameter is set to true) as an argument and returns
536       the message body as a string.  The returned value contains the entire
537       message in one scalar variable, without the message headers.
538
539   bodypart_string
540       Example:
541
542         my $string = $imap->bodypart_string(
543             $msgid, $part_number, $length, $offset
544         ) or die "Could not get bodypart string: ", $imap->LastError;
545
546       The bodypart_string method accepts a message sequence number (or a
547       message UID, if the "Uid" parameter is set to true) and a body part as
548       arguments and returns the message part as a string.  The returned value
549       contains the entire message part (or, optionally, a portion of the
550       part) in one scalar variable.
551
552       If an optional third argument is provided, that argument is the number
553       of bytes to fetch.  (The default is the whole message part.)  If an
554       optional fourth argument is provided then that fourth argument is the
555       offset into the part at which the fetch should begin.  The default is
556       offset zero, or the beginning of the message part.
557
558       If you specify an offset without specifying a length then the offset
559       will be ignored and the entire part will be returned.
560
561       bodypart_string will return "undef" if it encounters an error.
562
563   capability
564       Example:
565
566         my $features = $imap->capability
567           or die "Could not determine capability: ", $imap->LastError;
568
569       The capability method returns an array (or arrayref in scalar context)
570       of capabilities as returned by the CAPABILITY IMAP client command.  If
571       the CAPABILITY IMAP client command fails for any reason then the
572       capability method will return "undef".  Supported capabilities are
573       cached by the client, however, this cache is deleted after a connection
574       is set to Authenticated and when "starttls" is called.
575
576       See also "has_capability".
577
578   close
579       Example:
580
581         $imap->close or die "Could not close: $@\n";
582
583       The close method is used to close the currently selected folder via the
584       CLOSE IMAP client command.  According to RFC3501, the CLOSE command
585       performs an implicit EXPUNGE, which means that any messages that are
586       flagged as \Deleted (i.e. with the "delete_message" method) will now be
587       deleted.  If you haven't deleted any messages then close can be thought
588       of as an "unselect".
589
590       Note: this closes the currently selected folder, not the IMAP session.
591
592       See also "delete_message", "expunge", and RFC3501.
593
594   compress
595       Example:
596
597         $imap->compress or die "Could not enable RFC4978 compression: $@\n";
598
599       The compress method accepts no arguments.  This method is used to
600       instruct the server to use the DEFLATE (RFC1951) compression extension.
601       See the "Compress" attribute for how to specify arguments for use
602       during the initialization process.
603
604       Version note: method added in Mail::IMAPClient 3.30
605
606   connect
607       Example:
608
609         $imap->connect or die "Could not connect: $@\n";
610
611       The connect method connects an imap object to the server.  It returns
612       "undef" if it fails to connect for any reason.  If values are available
613       for the "User" and "Password" parameters at the time that connect is
614       invoked, then connect will call the "login" method after connecting and
615       return the result of the "login" method to connect's caller.  If either
616       or both of the "User" and "Password" parameters are unavailable but the
617       connection to the server succeeds then connect returns a pointer to the
618       IMAPClient object.
619
620       The "Server" parameter must be set (either during "new" method
621       invocation or via the "Server" object method) before invoking connect.
622       When the parameter is an absolute file path, an UNIX socket will get
623       opened.  If the "Server" parameter is supplied to the "new" method then
624       connect is implicitly called during object construction.
625
626       The connect method sets the state of the object to "Connected" if it
627       successfully connects to the server.  It returns "undef" on failure.
628
629   copy
630       Example:
631
632         # Here brackets indicate optional arguments:
633         my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
634           or die "Could not copy: $@\n";
635
636       Or:
637
638         # Now brackets indicate an array ref!
639         my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
640           or die "Could not copy: $@\n";
641
642       The copy method requires a folder name as the first argument, and a
643       list of one or more messages sequence numbers (or messages UID's, if
644       the UID parameter is set to a true value).  The message sequence
645       numbers or UID's should refer to messages in the currently selected
646       folder.  Those messages will be copied into the folder named in the
647       first argument.
648
649       The copy method returns "undef" on failure and a true value if
650       successful.  If the server to which the current Mail::IMAPClient object
651       is connected supports the UIDPLUS capability then the true value
652       returned by copy will be a comma separated list of UID's, which are the
653       UID's of the newly copied messages in the target folder.
654
655   create
656       Example:
657
658         $imap->create($new_folder)
659           or die "Could not create $new_folder: $@\n";
660
661       The create method accepts one argument, the name of a folder (or what
662       RFC3501 calls a "mailbox") to create.  If you specify additional
663       arguments to the create method and your server allows additional
664       arguments to the CREATE IMAP client command then the extra argument(s)
665       will be passed to your server.
666
667       If you specify additional arguments to the create method and your
668       server does not allow additional arguments to the CREATE IMAP client
669       command then the extra argument(s) will still be passed to your server
670       and the create will fail.
671
672       create returns a true value on success and "undef" on failure.
673
674   date
675       Example:
676
677         my $date = $imap->date($msg);
678
679       The date method accepts one argument, a message sequence number (or a
680       message UID if the "Uid" parameter is set to a true value).  It returns
681       the date of message as specified in the message's RFC822 "Date: "
682       header, without the "Date: " prefix.
683
684       The date method is a short-cut for:
685
686         my $date = $imap->get_header($msg,"Date");
687
688   delete
689       Example:
690
691         $imap->delete($folder) or die "Could not delete $folder: $@\n";
692
693       The delete method accepts a single argument, the name of a folder to
694       delete.  It returns a true value on success and "undef" on failure.
695
696   deleteacl
697       Example:
698
699         $imap->deleteacl( $folder, $userid )
700           or die "Could not delete acl: $@\n";
701
702       The deleteacl method accepts two input arguments, a folder name, a user
703       id (or authentication identifier, to use the terminology of RFC2086).
704       See RFC2086 for more information.  (This is somewhat experimental and
705       its implementation may change.)
706
707   delete_message
708       Example:
709
710         my @msgs = $imap->seen;
711         scalar(@msgs) and $imap->delete_message(\@msgs)
712           or die "Could not delete_message: $@\n";
713
714       The above could also be rewritten like this:
715
716         # scalar context returns array ref
717         my $msgs = scalar($imap->seen);
718
719         scalar(@$msgs) and $imap->delete_message($msgs)
720           or die "Could not delete_message: $@\n";
721
722       Or, as a one-liner:
723
724         $imap->delete_message( scalar($imap->seen) )
725           or warn "Could not delete_message: $@\n";
726         # just give warning in case failure is
727         # due to having no 'seen' msgs in the 1st place!
728
729       The delete_message method accepts a list of arguments.  If the "Uid"
730       parameter is not set to a true value, then each item in the list should
731       be either:
732
733       •   a message sequence number,
734
735       •   a comma-separated list of message sequence numbers,
736
737       •   a reference to an array of message sequence numbers, or
738
739       If the "Uid" parameter is set to a true value, then each item in the
740       list should be either:
741
742       •   a message UID,
743
744       •   a comma-separated list of UID's, or
745
746       •   a reference to an array of message UID's.
747
748       The messages identified by the sequence numbers or UID's will be
749       deleted.  If successful, delete_message returns the number of messages
750       it was told to delete.  However, since the delete is done by issuing
751       the +FLAGS.SILENT option of the STORE IMAP client command, there is no
752       guarantee that the delete was successful for every message.  In this
753       manner the delete_message method sacrifices accuracy for speed.
754       Generally, though, if a single message in a list of messages fails to
755       be deleted it's because it was already deleted, which is what you
756       wanted anyway so why worry about it? If there is a more severe error,
757       i.e. the server replies "NO", "BAD", or, banish the thought, "BYE",
758       then delete_message will return "undef".
759
760       If you must have guaranteed results then use the IMAP STORE client
761       command (via the default method) and use the +FLAGS (\Deleted) option,
762       and then parse your results manually.
763
764       Eg:
765
766         $imap->store( $msg_id, '+FLAGS (\Deleted)' );
767         my @results = $imap->History( $imap->Transaction );
768           ...           # code to parse output goes here
769
770       (Frankly I see no reason to bother with any of that; if a message
771       doesn't get deleted it's almost always because it's already not there,
772       which is what you want anyway.  But 'your mileage may vary' and all
773       that.)
774
775       The IMAPClient object must be in "Selected" status to use the
776       delete_message method.
777
778       NOTE: All the messages identified in the input argument(s) must be in
779       the currently selected folder.  Failure to comply with this requirement
780       will almost certainly result in the wrong message(s) being deleted.
781
782       ADDITIONAL NOTE: In the grand tradition of the IMAP protocol, deleting
783       a message doesn't actually delete the message.  Really.  If you want to
784       make sure the message has been deleted, you need to expunge the folder
785       (via the "expunge" method, which is implemented via the default
786       method).  Or at least "close" it.  This is generally considered a
787       feature, since after deleting a message, you can change your mind and
788       undelete it at any time before your "expunge" or "close".
789
790       See also: the "delete" method, to delete a folder, the "expunge"
791       method, to expunge a folder, the "restore_message" method to undelete a
792       message, and the "close" method (implemented here via the default
793       method) to close a folder.  Oh, and don't forget about RFC3501.
794
795   deny_seeing
796       Example:
797
798         # Reset all read msgs to unread
799         # (produces error if there are no seen msgs):
800         $imap->deny_seeing( scalar($imap->seen) )
801           or die "Could not deny_seeing: $@\n";
802
803       The deny_seeing method accepts a list of one or more message sequence
804       numbers, or a single reference to an array of one or more message
805       sequence numbers, as its argument(s).  It then unsets the "\Seen" flag
806       for those messages (so that you can "deny" that you ever saw them).  Of
807       course, if the "Uid" parameter is set to a true value then those
808       message sequence numbers should be unique message id's.
809
810       Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
811       specifying "$imap->unset_flag("Seen",@msgs)".
812
813   disconnect
814       Example:
815
816         $imap->disconnect or warn "Could not logout: $@\n";
817
818       This method calls "logout", see "logout" for details.
819
820   done
821       Example:
822
823         my $tag = $imap->idle or warn "idle failed: $@\n";
824         doSomethingA();
825         my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
826         doSomethingB();
827         my $results = $imap->done($tag) or warn "Error from done: $@\n";
828
829       The done method tells the IMAP server to terminate the IDLE command.
830       The only argument is the tag (identifier) received from the previous
831       call to "idle".  If tag is not specified a default tag based on the
832       Count attribute is assumed to be the tag to look for in the response
833       from the server.
834
835       If an invalid tag is specified, or the default tag is wrong, then done
836       will hang indefinitely or until a timeout occurs.
837
838       If done is called when an "idle" command is not active then the server
839       will likely respond with an error like * BAD Invalid tag.
840
841       On failure <undef> is returned and "LastError" is set.
842
843       See also "idle", "idle_data" and "Results".
844
845   examine
846       Example:
847
848         $imap->examine($folder) or die "Could not examine: $@\n";
849
850       The examine method selects a folder in read-only mode and changes the
851       object's state to "Selected".  The folder selected via the examine
852       method can be examined but no changes can be made unless it is first
853       selected via the "select" method.
854
855       The examine method accepts one argument, which is the name of the
856       folder to select.
857
858   exists
859       Example:
860
861         $imap->exists($folder) or warn "$folder not found: $@\n";
862
863       Accepts one argument, a folder name.  Returns true if the folder exists
864       or false if it does not exist.
865
866   expunge
867       Example:
868
869         $imap->expunge($folder) or die "Could not expunge: $@\n";
870
871       The expunge method accepts one optional argument, a folder name.  It
872       expunges the folder specified as the argument, or the currently
873       selected folder (if any) when no argument is supplied.
874
875       Although RFC3501 does not permit optional arguments (like a folder
876       name) to the EXPUNGE client command, the "expunge" method does.  Note:
877       expunging a folder deletes the messages that have the \Deleted flag set
878       (i.e. messages flagged via "delete_message").
879
880       See also the "close" method, which "deselects" as well as expunges.
881
882   fetch
883       Usage:
884
885         $imap->fetch( [$seq_set|ALL], @msg_data_items )
886
887       Example:
888
889         my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
890
891       The fetch method implements the FETCH IMAP client command.  It accepts
892       a list of arguments, which will be converted into a space-delimited
893       list of arguments to the FETCH IMAP client command.  If no arguments
894       are supplied then fetch does a FETCH ALL.  If the "Uid" parameter is
895       set to a true value then the first argument will be treated as a UID or
896       list of UID's, which means that the UID FETCH IMAP client command will
897       be run instead of FETCH.  (It would really be a good idea at this point
898       to review RFC3501.)
899
900       If called in array context, fetch will return an array of output lines.
901       The output lines will be returned just as they were received from the
902       server, so your script will have to be prepared to parse out the bits
903       you want.  The only exception to this is literal strings, which will be
904       inserted into the output line at the point at which they were
905       encountered (without the {nnn} literal field indicator).  See RFC3501
906       for a description of literal fields.
907
908       If fetch is called in a scalar context, then a reference to an array
909       (as described above) is returned instead of the entire array.
910
911       fetch returns "undef" on failure.  Inspect "LastError" or $@ for an
912       explanation of your error.
913
914   fetch_hash
915       Usage:
916
917         $imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
918
919       Examples:
920
921         my $hashref = $imap->fetch_hash("RFC822.SIZE");
922
923        OR
924
925         my $hashref = {};
926         $imap->fetch_hash( "RFC822.SIZE", $hashref );
927         print "Msg #$_ is $hashref->{$_}->{'RFC822.SIZE'} bytes\n" for (keys %$hashref);
928
929       The fetch_hash method accepts a list of message attributes to be
930       fetched (as described in RFC3501).  It returns a hash whose keys are
931       all the messages in the currently selected folder and whose values are
932       key-value pairs of fetch keywords and the message's value for that
933       keyword (see sample output below).
934
935       If fetch_hash is called in scalar context, it returns a reference to
936       the hash instead of the hash itself.  If the last argument is a hash
937       reference, then that hash reference will be used as the place where
938       results are stored (and that reference will be returned upon successful
939       completion).  If the last argument is not a reference then it will be
940       treated as one of the FETCH attributes and a new hash will be created
941       and returned (either by value or by reference, depending on the context
942       in which fetch_hash was called).
943
944       For example, if you have a folder with 3 messages and want the size and
945       internal date for each of them, you could do the following:
946
947         use Mail::IMAPClient;
948         use Data::Dumper;
949         # ... other code goes here
950         $imap->select($folder);
951         my $hash = $imap->fetch_hash( "RFC822.SIZE", "INTERNALDATE" );
952         # (Same as:
953         #  my $hash = $imap->fetch_hash("RFC822.SIZE");
954         #  $imap->fetch_hash( "INTERNALDATE", $hash );
955         # ).
956         print Data::Dumper->Dumpxs( [$hash], ['$hash'] );
957
958       This would result in Data::Dumper output similar to the following:
959
960          $hash = {
961              '1' => {
962                         'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
963                         'RFC822.SIZE' => '1586',
964                     },
965              '2' => {
966                         'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
967                         'RFC822.SIZE' => '1945',
968                     },
969              '3' => {
970                         'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
971                         'RFC822.SIZE' => '134314',
972                     }
973            };
974
975       By itself this method may be useful for tasks like obtaining the size
976       of every message in a folder.  It issues one command and receives one
977       (possibly long!) response from the server.
978
979       If the fetch request causes the server to return data in a
980       parenthesized list, the data within the parenthesized list may be
981       escaped via the Escape() method. Use the Unescape() method to get the
982       raw values back in this case.
983
984   flags
985       Example:
986
987         my $flags = $imap->flags($msgid)
988           or die "flags failed: $@\n";
989
990       The flags method implements the FETCH IMAP client command to list a
991       single message's flags.  It accepts one argument, a message sequence
992       number (or a message UID, if the "Uid" parameter is true), and returns
993       an array (or a reference to an array, if called in scalar context)
994       listing the flags that have been set.  Flag names are provided with
995       leading backslashes.
996
997       As of version 1.11, you can supply either a list of message id's or a
998       reference to an array of message id's (which means either sequence
999       number, if the Uid parameter is false, or message UID's, if the Uid
1000       parameter is true) instead of supplying a single message sequence
1001       number or UID.  If you do, then the return value will not be an array
1002       or array reference; instead, it will be a hash reference, with each key
1003       being a message sequence number (or UID) and each value being a
1004       reference to an array of flags set for that message.
1005
1006       For example, if you want to display the flags for every message in the
1007       folder where you store e-mail related to your plans for world
1008       domination, you could do something like this:
1009
1010         use Mail::IMAPClient;
1011         my $imap = Mail::IMAPClient->new(
1012             Server   => $imaphost,
1013             User     => $login,
1014             Password => $pass,
1015             Uid      => 1,        # optional
1016         );
1017
1018         $imap->select("World Domination");
1019         # get the flags for every message in my 'World Domination' folder
1020         $flaghash = $imap->flags( scalar( $imap->search("ALL") ) );
1021
1022         # pump through sorted hash keys to print results:
1023         for my $k ( sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash ) {
1024             # print: Message 1: \Flag1, \Flag2, \Flag3
1025             print "Message $k:\t", join( ", ", @{$flaghash->{$k}} ), "\n";
1026         }
1027
1028   folders
1029       Example:
1030
1031         $imap->folders or die "Could not list folders: $@\n";
1032
1033       The folders method returns an array listing the available folders.  It
1034       will only be successful if the object is in the Authenticated or
1035       Selected states.
1036
1037       The folders method accepts one optional argument, which is a prefix.
1038       If a prefix is supplied to the folders method, then only folders
1039       beginning with the prefix will be returned.
1040
1041       For example:
1042
1043         print join( ", ", $imap->folders ), ".\n";
1044         # Prints:
1045         # INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1046         print join( ", ", $imap->folders("Projects") ), ".\n";
1047         # Prints:
1048         # Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1049         print join( ", ", $imap->folders("Projects" . $imap->separator) ), ".\n";
1050         # Prints:
1051         # Projects/Completed, Projects/Ongoing
1052
1053       Please note that documentation previously suggested that if you just
1054       want to list a folder's subfolders (and not the folder itself), then
1055       you need to include the hierarchy separator character (as returned by
1056       the "separator" method). However, this does not match the behavior of
1057       the existing implementation, so you will need to manually exclude the
1058       parent folder from the results.
1059
1060   folders_hash
1061         my @fhashes = $imap->folders_hash
1062           or die "Could not get list of folder hashes.\n";
1063
1064       The folders_hash method accepts one optional argument, which is a
1065       prefix.  If a prefix is supplied to the folders_hash method, then only
1066       folders beginning with the prefix will be returned.
1067
1068       An array(ref) of hashes is returned that contain information about the
1069       requested folders.  Each hash contains three keys (name, attrs, delim)
1070       and looks like the following:
1071
1072         {
1073           name  => 'Mail/Box/Name',
1074           attrs => [ '\Marked', '\HasNoChildren' ],
1075           delim => '/',
1076         }
1077
1078       IMAP servers implementing RFC6154 return attributes to be used to
1079       identify special-use mailboxes (folders).
1080
1081         my $sattr_re = /\A\\(?:All|Archive|Drafts|Flagged|Junk|Sent|Trash)\Z/;
1082         foreach my $fhash (@fhashes) {
1083             next unless defined $fhash->{name};
1084             my @special = grep { $sattr_re } @{ $fhash->{attrs} };
1085             print("special: $fhash->{name} : @special\n") if (@special);
1086         }
1087
1088       Version note: method added in Mail::IMAPClient 3.34
1089
1090   xlist_folders (DEPRECATED)
1091       This method is deprecated as of version 3.34.  Please use folders_hash
1092       instead.  See RFC6154 for attributes to be used to identify special-use
1093       mailboxes (folders).
1094
1095       Example:
1096
1097         my $xlist = $imap->xlist_folders
1098           or die "Could not get xlist folders.\n";
1099
1100       IMAP servers implementing the XLIST extension (such as Gmail) designate
1101       particular folders to be used for particular functions.  This is useful
1102       in the case where you want to know which folder should be used for
1103       Trash when the actual folder name can't be predicted (e.g. in the case
1104       of Gmail, the folder names change depending on the user's locale
1105       settings).
1106
1107       The xlist_folders method returns a hash listing any "xlist" folder
1108       names, with the values listing the actual folders that should be used
1109       for those names.  For example, using this method with a Gmail user
1110       using the English (US) locale might give this output from Data::Dumper:
1111
1112         $VAR1 = {
1113             'Inbox'   => 'Inbox',
1114             'AllMail' => '[Gmail]/All Mail',
1115             'Trash'   => '[Gmail]/Trash',
1116             'Drafts'  => '[Gmail]/Drafts',
1117             'Sent'    => '[Gmail]/Sent Mail',
1118             'Spam'    => '[Gmail]/Spam',
1119             'Starred' => '[Gmail]/Starred'
1120         };
1121
1122       The same list for a user using the French locale might look like this:
1123
1124         $VAR1 = {
1125             'Inbox'   => 'Bo&AO4-te de r&AOk-ception',
1126             'AllMail' => '[Gmail]/Tous les messages',
1127             'Trash'   => '[Gmail]/Corbeille',
1128             'Drafts'  => '[Gmail]/Brouillons',
1129             'Sent'    => '[Gmail]/Messages envoy&AOk-s',
1130             'Spam'    => '[Gmail]/Spam',
1131             'Starred' => '[Gmail]/Suivis'
1132         };
1133
1134       Mail::IMAPClient recognizes the following "xlist" folder names:
1135
1136       Inbox
1137       AllMail
1138       Trash
1139       Drafts
1140       Sent
1141       Spam
1142       Starred
1143
1144       These are currently the only ones supported by Gmail.  The XLIST
1145       extension is not documented, and there are no other known
1146       implementations other than Gmail, so this list is based on what Gmail
1147       provides.
1148
1149       If the server does not support the XLIST extension, this method returns
1150       undef.
1151
1152       Version note: method added in Mail::IMAPClient 3.21
1153
1154   has_capability
1155       Example:
1156
1157         my $has_feature = $imap->has_capability($feature)
1158           or die "Could not do has_capability($feature): $@\n";
1159
1160       Returns:
1161
1162       "undef"
1163           If the underlying "capability" calls fails then "undef" is
1164           returned.
1165
1166       "" or "()"
1167           If the server does not have the requested capability, then either
1168           an empty string ("" in scalar context) or an empty list ("()" in
1169           list context) is returned.
1170
1171       a true value
1172           If the server has the requested capability, then a true value is
1173           returned.  The true value depends upon the server response for the
1174           capability requested.  The value will be an array reference in
1175           scalar context or an array in list context. The returned data is
1176           useful for understanding more about specific capabilities.  For
1177           example, consider the following server CAPABILITY response:
1178
1179             * CAPABILITY IMAP4rev1 SORT SORT=DISPLAY I18NLEVEL=1 AUTH=PLAIN AUTH=XTEST
1180
1181           Results are returned as shown by the trailing comments:
1182
1183             $c = $imap->has_capability("IMAP4rev1");    # [ "IMAP4rev1" ]
1184             @c = $imap->has_capability("IMAP4rev1");    # ( "IMAP4rev1" )
1185             $c = $imap->has_capability("SORT");         # [ "DISPLAY" ]
1186             @c = $imap->has_capability("SORT=DISPLAY"); # ( "SORT=DISPLAY" )
1187             $c = $imap->has_capability("AUTH");         # [ "PLAIN", "XTEST" ]
1188             @c = $imap->has_capability("AUTH");         # ( "PLAIN", "XTEST" )
1189             $c = $imap->has_capability("AUTH=XTEST");   # [ "AUTH=XTEST" ]
1190             @c = $imap->has_capability("AUTH=XTEST");   # ( "AUTH=XTEST" )
1191             $c = $imap->has_capability("AUTH=NADA");    # ''
1192             @c = $imap->has_capability("AUTH=NADA");    # ()
1193             $c = $imap->has_capability("NADA");         # ''
1194             @c = $imap->has_capability("NADA");         # ()
1195
1196   idle
1197       Example:
1198
1199         my $tag = $imap->idle or warn "idle failed: $@\n";
1200         doSomethingA();
1201         my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1202         doSomethingB();
1203         my $results = $imap->done($tag) or warn "Error from done: $@\n";
1204
1205       The idle method tells the IMAP server the client is ready to accept
1206       unsolicited mailbox update messages (on the selected folder/mailbox).
1207       This method is only valid on servers that support the IMAP IDLE
1208       extension, see RFC2177 for details.
1209
1210       The idle method accepts no arguments and returns the tag (identifier)
1211       that was sent by the client for this command.  This tag should be
1212       supplied as the argument to "done" when ending the IDLE command.
1213
1214       On failure <undef> is returned and "LastError" is set.
1215
1216       The method "idle_data" may be used once idle has been successful.
1217       However, no mailbox operations may be called until the idle command has
1218       been terminated by calling "done".  Failure to do so will result in an
1219       error and the idle command will typically be terminated by the server.
1220
1221       See also "idle_data" and "done".
1222
1223   idle_data
1224       Usage:
1225
1226         # an optional timeout in seconds may be specified
1227         $imap->idle_data( [$timeout] )
1228
1229       Example:
1230
1231         my $tag = $imap->idle or warn "idle failed: $@\n";
1232         doSomethingA();
1233         my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1234         doSomethingB();
1235         my $results = $imap->done($tag) or warn "Error from done: $@\n";
1236
1237       The idle_data method can be used to accept any unsolicited mailbox
1238       update messages that have been sent by the server during an "idle"
1239       command.  This method does not send any commands to the server, it
1240       simply looks for and optionally waits for data from the server and
1241       returns that data to the caller.
1242
1243       The idle_data method accepts an optional $timeout argument and returns
1244       an array (or an array reference if called in scalar context) with the
1245       messages from the server.
1246
1247       By default a timeout of 0 seconds is used (do not block).  Internally
1248       the timeout is passed to "select" in perlfunc.  The timeout controls
1249       how long the select call blocks if there are no messages waiting to be
1250       read from the server.
1251
1252       On failure <undef> is returned and "LastError" is set.
1253
1254       See also "imap" and "done".
1255
1256       Version note: method added in Mail::IMAPClient 3.23 Warning: this
1257       method is considered experimental and the interface/output may change
1258       in a future version.
1259
1260   imap4rev1
1261       Example:
1262
1263         $imap->imap4rev1 or die "Could not imap4rev1: $@\n";
1264
1265       Returns true if the IMAP server to which the IMAPClient object is
1266       connected has the IMAP4REV1 capability.  If the server does not have
1267       the capability then the empty string "" is returned, if the underlying
1268       "capability" calls fails then undef is returned.
1269
1270   internaldate
1271       Example:
1272
1273         my $msg_internal_date = $imap->internaldate($msgid)
1274           or die "internaldate failed: $@\n";
1275
1276       internaldate accepts one argument, a message id (or UID if the "Uid"
1277       parameter is true), and returns that message's internal date or undef
1278       if the call fails or internal date is not returned.
1279
1280   get_bodystructure
1281       Example:
1282
1283         my $bodyStructObject = $imap->get_bodystructure($msgid)
1284           or die "Could not get_bodystructure: $@\n";
1285
1286       The get_bodystructure method accepts one argument, a message sequence
1287       number or, if "Uid" is true, a message UID.  It obtains the message's
1288       body structure and returns a parsed Mail::IMAPClient::BodyStructure
1289       object for the message.
1290
1291   get_envelope
1292       Example:
1293
1294         my $envObject = $imap->get_envelope(@args)
1295           or die "Could not get_envelope: $@\n";
1296
1297       The get_envelope method accepts one argument, a message sequence number
1298       or, if "Uid" is true, a message UID.  It obtains the message's envelope
1299       and returns a Mail::IMAPClient::BodyStructure::Envelope object for the
1300       envelope, which is just a version of the envelope that's been parsed
1301       into a Perl object.
1302
1303       For more information on how to use this object once you've gotten it,
1304       see the Mail::IMAPClient::BodyStructure documentation.  (As of this
1305       writing there is no separate pod document for
1306       Mail::IMAPClient::BodyStructure::Envelope.)
1307
1308   getacl
1309       Example:
1310
1311         my $hash = $imap->getacl($folder)
1312           or die "Could not getacl for $folder: $@\n";
1313
1314       getacl accepts one argument, the name of a folder.  If no argument is
1315       provided then the currently selected folder is used as the default.  It
1316       returns a reference to a hash.  The keys of the hash are userids that
1317       have access to the folder, and the value of each element are the
1318       permissions for that user.  The permissions are listed in a string in
1319       the order returned from the server with no white space or punctuation
1320       between them.
1321
1322   get_header
1323       Example:
1324
1325         my $messageId = $imap->get_header( $msg, "Message-Id" );
1326
1327       The get_header method accepts two arguments, a message sequence number
1328       or UID and the name of an RFC822 header (without the trailing colon).
1329       It returns the value for that header in the message whose sequence
1330       number or UID was passed as the first argument.  If no value can be
1331       found it returns "undef"; if multiple values are found it returns the
1332       first one.  Its return value is always a scalar.  get_header uses case
1333       insensitive matching to get the value, so you do not have to worry
1334       about the case of your second argument.
1335
1336       The get_header method is a short-cut for:
1337
1338         my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
1339
1340   getquotaroot
1341       Example:
1342
1343         my $results = $imap->getquotaroot($mailboxname)
1344           or die "Could not getquotaroot for $mailboxname: $@\n";
1345
1346       The getquotaroot method implements the RFC2087 GETQUOTAROOT command.
1347       The "$mailboxname" defaults to "INBOX" if no argument is provided.
1348
1349       On error "undef" is returned, otherwise "Results" are returned.  The
1350       results should have the untagged QUOTAROOT response from the server
1351       along with the QUOTAROOT's resource usage and limits in an untagged
1352       QUOTA response.
1353
1354       See also RFC2087, "getquota", "setquota", "quota" and "quota_usage".
1355
1356   getquota
1357       Example:
1358
1359         my $results = $imap->getquota($quotaroot)
1360           or die "Could not getquota for $quotaroot: $@\n";
1361
1362       The getquota method implements the RFC2087 GETQUOTA command.  The
1363       "$quotaroot" defaults to "user/User" if no argument is provided.
1364
1365       On error "undef" is returned, otherwise "Results" are returned.  The
1366       results from the server should have the untagged QUOTA response from
1367       the server.
1368
1369       See also RFC2087, "getquotaroot", "quota" and "quota_usage".
1370
1371   quota
1372       Example:
1373
1374         my $limit = $imap->quota($quotaroot)
1375           or die "Could not get quota limit for $quotaroot: $@\n";
1376
1377       The quota method takes the "Results" from getquota and parses out the
1378       "STORAGE" limit returned by the server.  The "$quotaroot" defaults to
1379       "INBOX" if no argument is provided.
1380
1381       On error "undef" is returned, otherwise the integer "STORAGE" limit
1382       provided by the server is returned.
1383
1384       See also RFC2087, "getquotaroot", "getquota" and "quota_usage".
1385
1386   quota_usage
1387       Example:
1388
1389         my $usage = $imap->quota_usage($quotaroot)
1390           or die "Could not get quota usage for $quotaroot: $@\n";
1391
1392       The quota_usage method takes the "Results" from getquota and parses out
1393       the "STORAGE" usage returned by the server.  The "$quotaroot" defaults
1394       to "INBOX" if no argument is provided.
1395
1396       On error "undef" is returned, otherwise the integer "STORAGE" usage
1397       provided by the server is returned.
1398
1399       See also RFC2087, "getquotaroot", "getquota" and "quota".
1400
1401   setquota
1402       Example:
1403
1404         my $results = $imap->setquota( $quotaroot, $resource, $limit )
1405           or die "Could not setquota for $quotaroot: $@\n";
1406
1407       The setquota method implements the RFC2087 SETQUOTA command.  It
1408       accepts multiple pairs of $resource and $limit arguments.  The
1409       "$quotaroot" defaults to "user/User" if not defined.
1410
1411       On error "undef" is returned, otherwise "Results" are returned.
1412
1413       See also RFC2087, "getquotaroot" and "getquota".
1414
1415   is_parent
1416       Example:
1417
1418         my $hasKids = $imap->is_parent($folder);
1419
1420       The is_parent method accepts one argument, the name of a folder. It
1421       returns a value that indicates whether or not the folder has children.
1422       The value it returns is either:
1423
1424       1 (or a positive integer)
1425           The "\HasChildren" attribute is set, indicating that the folder has
1426           children.
1427
1428       0 (zero)
1429           The "\HasNoChildren" attribute is set, indicating that the folder
1430           has no children at this time.
1431
1432       "undef"
1433           The "\NoInferiors" attribute is set, indicating the folder is not
1434           permitted to have children.
1435
1436       Eg:
1437
1438         my $parenthood = $imap->is_parent($folder);
1439         if ( defined($parenthood) ) {
1440             if ($parenthood) {
1441                 print "$folder has children.\n";
1442             }
1443             else {
1444                 print "$folder is permitted children, but has none.\n";
1445             }
1446         }
1447         else {
1448             print "$folder is not permitted to have children.\n";
1449         }
1450
1451   list
1452       Example:
1453
1454         my @raw_output = $imap->list(@args)
1455           or die "Could not list: $@\n";
1456
1457       The list method implements the IMAP LIST client command.  Arguments are
1458       passed to the IMAP server as received, separated from each other by
1459       spaces.  If no arguments are supplied then the default list command
1460       "tag LIST "" '*'" is issued.
1461
1462       The list method returns an array (or an array reference, if called in a
1463       scalar context).  The array is the unadulterated output of the LIST
1464       command.  (If you want your output adulterated then see the "folders"
1465       method, above.)
1466
1467       An "undef" value is returned in case of errors.  Be sure to check for
1468       it.
1469
1470   listrights
1471       Example:
1472
1473         $imap->listrights( $folder, $user )
1474           or die "Could not listrights: $@\n";
1475
1476       The listrights method implements the IMAP LISTRIGHTS client command
1477       (RFC2086).  It accepts two arguments, the foldername and a user id.  It
1478       returns the rights the specified user has for the specified folder.  If
1479       called in a scalar context then the rights are returned a strings, with
1480       no punctuation or white space or any nonsense like that.  If called in
1481       array context then listrights returns an array in which each element is
1482       one right.
1483
1484   login
1485       Example:
1486
1487         $imap->login or die "Could not login: $@\n";
1488
1489       The login method implements the IMAP LOGIN client command to log into
1490       the server.  It automatically calls "authenticate" if the Authmechanism
1491       parameter is set to anything except 'LOGIN' otherwise a clear text
1492       LOGIN is attempted.
1493
1494       The User and Password parameters must be set before the login method
1495       can be invoked.  On success, a Mail::IMAPClient object with the Status
1496       of Authenticated is returned.  On failure, undef is returned and $@ is
1497       set.  The methods "new", "connect", and "Socket" may automatically
1498       invoke login see the documentation of each method for details.
1499
1500       If the "Compress" parameter is set, the "compress" method will
1501       automatically be called after successful authentication.
1502
1503       See also "proxyauth" and "Proxy" for additional information regarding
1504       ways of authenticating with a server via SASL and/or PROXYAUTH.
1505
1506   proxyauth
1507       Example:
1508
1509         $imap->login( "admin", "password" );
1510         $imap->proxyauth("someuser");
1511
1512       The proxyauth method implements the IMAP PROXYAUTH client command.  The
1513       command is used by Sun/iPlanet/Netscape IMAP servers to allow an
1514       administrative user to masquerade as another user.
1515
1516   logout
1517       Example:
1518
1519         $imap->logout or die "Could not logout: $@\n";
1520
1521       The logout method implements the LOGOUT IMAP client command.  This
1522       method causes the server to end the connection and the IMAPClient
1523       client enters the Unconnected state.  This method does not, destroy the
1524       IMAPClient object, thus the "connect" and "login" methods can be used
1525       to establish a new IMAP session.
1526
1527       Note that RFC2683 section 3.1.2 (Severed connections) makes some
1528       recommendations on how IMAP clients should behave.  It is up to the
1529       user of this module to decide on the preferred behavior and code
1530       accordingly.
1531
1532       Version note: documentation (from 2.x through 3.23) claimed that
1533       Mail::IMAPClient would attempt to log out of the server during DESTROY
1534       if the object is in the "Connected" state.  This documentation was
1535       apparently incorrect from at least 2.2.2 and possibly earlier versions
1536       on up.
1537
1538   lsub
1539       Example:
1540
1541         $imap->lsub(@args) or die "Could not lsub: $@\n";
1542
1543       The lsub method implements the IMAP LSUB client command.  Arguments are
1544       passed to the IMAP server as received, separated from each other by
1545       spaces.  If no arguments are supplied then the default lsub command
1546       "tag LSUB "" '*'" is issued.
1547
1548       The lsub method returns an array (or an array reference, if called in a
1549       scalar context).  The array is the unaltered output of the LSUB
1550       command.  If you want an array of subscribed folders then see the
1551       "subscribed" method, below.
1552
1553   mark
1554       Example:
1555
1556         $imap->mark(@msgs) or die "Could not mark: $@\n";
1557
1558       The mark method accepts a list of one or more messages sequence
1559       numbers, or a single reference to an array of one or more message
1560       sequence numbers, as its argument(s).  It then sets the "\Flagged" flag
1561       for those message(s).  Of course, if the "Uid" parameter is set to a
1562       true value then those message sequence numbers had better be unique
1563       message id's.
1564
1565       Note that specifying "$imap->see(@msgs)" is just a shortcut for
1566       specifying "$imap->set_flag("Flagged",@msgs)".
1567
1568   Massage
1569       Example:
1570
1571         $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
1572
1573       WARNING: This method may be deprecated in the future, consider using
1574       "Quote" instead of this method.
1575
1576       The Massage method accepts a value as an argument and, optionally, a
1577       second value that, when true, indicates that the first argument is not
1578       the name of an existing folder.
1579
1580       WARNING: If the first argument has double quotes at the beginning and
1581       end of its value, those double quote will be stripped unless the second
1582       argument does not evaluate to true.
1583
1584       It returns its argument as a correctly quoted string or a literal
1585       string.
1586
1587       Note that you should rarely use this on folder names, since methods
1588       that accept folder names as an argument will call Quote for you.
1589
1590   message_count
1591       Example:
1592
1593         my $msgcount = $imap->message_count($folder);
1594         defined($msgcount) or die "message_count failed: $@\n";
1595
1596       The message_count method accepts the name of a folder as an argument
1597       and returns the number of messages in that folder.  Internally, it
1598       invokes the "status" method (see above) and parses out the results to
1599       obtain the number of messages.  If you don't supply an argument to
1600       message_count then it will return the number of messages in the
1601       currently selected folder (assuming of course that you've used the
1602       "select" or "examine" method to select it instead of trying something
1603       funky).  Note that RFC2683 contains warnings about the use of the IMAP
1604       STATUS command (and thus the "status" method and therefore the
1605       message_count method) against the currently selected folder.  You
1606       should carefully consider this before using message_count on the
1607       currently selected folder.  You may be better off using "search" or one
1608       of its variants (especially "messages"), and then counting the results.
1609       On the other hand, I regularly violate this rule on my server without
1610       suffering any dire consequences.  Your mileage may vary.
1611
1612   message_string
1613       Example:
1614
1615         my $string = $imap->message_string($msgid)
1616           or die "message_string failed: $@\n";
1617
1618       The message_string method accepts a message sequence number (or message
1619       UID if "Uid" is true) as an argument and returns the message as a
1620       string.  The returned value contains the entire message in one scalar
1621       variable, including the message headers.  Note that using this method
1622       will set the message's "\Seen" flag as a side effect, unless Peek is
1623       set to a true value.
1624
1625   message_to_file
1626       Example:
1627
1628         $imap->message_to_file( $file, @msgs )
1629           or die "message_to_file failed: $@\n";
1630
1631       The message_to_file method accepts a filename or file handle and one or
1632       more message sequence numbers (or message UIDs if "Uid" is true) as
1633       arguments and places the message string(s) (including RFC822 headers)
1634       into the file named in the first argument (or prints them to the file
1635       handle, if a file handle is passed).  The returned value is true on
1636       success and "undef" on failure.
1637
1638       If the first argument is a reference, it is assumed to be an open file
1639       handle and will not be closed when the method completes, If it is a
1640       file, it is opened in append mode, written to, then closed.
1641
1642       Note that using this method will set the message's "\Seen" flag as a
1643       side effect.  But you can use the "deny_seeing" method to set it back,
1644       or set the "Peek" parameter to a true value to prevent setting the
1645       "\Seen" flag at all.
1646
1647       This method currently works by making some basic assumptions about the
1648       server's behavior, notably that the message text will be returned as a
1649       literal string but that nothing else will be.  If you have a better
1650       idea then I'd like to hear it.
1651
1652   message_uid
1653       Example:
1654
1655         my $msg_uid = $imap->message_uid($msg_seq_no)
1656           or die "Could not get uid for $msg_seq_no: $@\n";
1657
1658       The message_uid method accepts a message sequence number (or message
1659       UID if "Uid" is true) as an argument and returns the message's UID.
1660       Yes, if "Uid" is true then it will use the IMAP UID FETCH UID client
1661       command to obtain and return the very same argument you supplied.  This
1662       is an IMAP feature so don't complain to me about it.
1663
1664   messages
1665       Example:
1666
1667         # Get a list of messages in the current folder:
1668         my @msgs = $imap->messages or warn "Could not list messages\n";
1669         # Get a reference to an array of messages in the current folder:
1670         my $msgs = $imap->messages or die "Get messages failed: $@\n";
1671
1672       If called in list context, the messages method returns a list of all
1673       the messages in the currently selected folder.  If called in scalar
1674       context, it returns a reference to an array containing all the messages
1675       in the folder.  This is the same as specifying
1676       "$imap->"search"("ALL")".
1677
1678       An empty list is returned when no messages are found.  On failure
1679       <undef> is returned and "LastError" is set.
1680
1681   migrate
1682       Example:
1683
1684         $imap_src->migrate( $imap_dest, "ALL", $targetFolder )
1685           or die "Could not migrate: ", $imap_src->LastError;
1686
1687       The migrate method copies the indicated message(s) from the currently
1688       selected folder to another Mail::IMAPClient object's session.  It
1689       requires these arguments:
1690
1691       1.  a reference to the target Mail::IMAPClient object (not the calling
1692           object, which is connected to the source account);
1693
1694       2.  the message(s) to be copied, specified as either a) the message
1695           sequence number (or message UID if the UID parameter is true) of a
1696           single message, b) a reference to an array of message sequence
1697           numbers (or message UID's if the UID parameter is true) or c) the
1698           special string "ALL", which is a shortcut for the results of
1699           ""search"("ALL")".
1700
1701       3.  the name of the destination folder on the target mailbox to receive
1702           the message(s).  If this argument is not supplied or is undef then
1703           the currently selected folder on the calling object will be used.
1704           The destination folder will be automatically created if necessary.
1705
1706       The target ($imap_dest) Mail::IMAPClient object must not be the same
1707       object as the source ($imap_src).
1708
1709       This method does not attempt to minimize memory usage.  In the future
1710       it could be enhanced to (optionally) write message data to a temporary
1711       file to avoid storing the entire message in memory.
1712
1713       To work around potential network timeouts on large messages, consider
1714       setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
1715
1716       See also "Supportedflags".
1717
1718   move
1719       Example:
1720
1721         my $newUid = $imap->move( $newFolder, $oldUid )
1722           or die "Could not move: $@\n";
1723         $imap->expunge;
1724
1725       The move method moves messages from the currently selected folder to
1726       the folder specified in the first argument to move.  If the "Uid"
1727       parameter is not true, then the rest of the arguments should be either:
1728
1729       a)  a message sequence number,
1730
1731       b)  a comma-separated list of message sequence numbers, or
1732
1733       c)  a reference to an array of message sequence numbers.
1734
1735       If the "Uid" parameter is true, then the arguments should be:
1736
1737       a)  a message UID,
1738
1739       b)  a comma-separated list of message UID's, or
1740
1741       c)  a reference to an array of message UID's.
1742
1743       If the target folder does not exist then it will be created.
1744
1745       If move is successful, then it returns a true value.  Furthermore, if
1746       the Mail::IMAPClient object is connected to a server that has the
1747       UIDPLUS capability, then the true value will be the comma-separated
1748       list of UID's for the newly copied messages.  The list will be in the
1749       order in which the messages were moved which should correspond to the
1750       order of the message UID provided by the caller.
1751
1752       If the move is not successful then move returns "undef".
1753
1754       Note that a move really just involves copying the message to the new
1755       folder and then setting the \Deleted flag.  To actually delete the
1756       original message you will need to run "expunge" (or "close").
1757
1758   namespace
1759       Example:
1760
1761         my $refs = $imap->namespace
1762           or die "namespace failed: $@\n";
1763
1764       The namespace method runs the NAMESPACE IMAP command (as defined in RFC
1765       2342).  When called in a list context, it returns a list of three
1766       references.  Each reference looks like this:
1767
1768         [
1769           [ $prefix_1, $separator_1 ],
1770           [ $prefix_2, $separator_2 ],
1771           [ $prefix_n, $separator_n ],
1772         ]
1773
1774       The first reference provides a list of prefixes and separator
1775       characters for the available personal namespaces.  The second reference
1776       provides a list of prefixes and separator characters for the available
1777       shared namespaces.  The third reference provides a list of prefixes and
1778       separator characters for the available public namespaces.
1779
1780       If any of the three namespaces are unavailable on the current server
1781       then an 'undef' is returned instead of a reference.  So for example if
1782       shared folders were not supported on the server but personal and public
1783       namespaces were both available (with one namespace each), the returned
1784       value might resemble this:
1785
1786         [ [ "", "/" ] , undef, [ "#news", "." ] ];
1787
1788       If the namespace method is called in scalar context, it returns a
1789       reference to the above-mentioned list of three references, thus
1790       creating a single structure that would pretty-print something like
1791       this:
1792
1793         $VAR1 = [
1794             [
1795                 [ $user_prefix_1, $user_separator_1 ],
1796                 [ $user_prefix_2, $user_separator_2 ],
1797                 [ $user_prefix_n, $user_separator_n ],
1798             ],                    # or undef
1799             [
1800                 [ $shared_prefix_1, $shared_separator_1 ],
1801                 [ $shared_prefix_2, $shared_separator_2 ],
1802                 [ $shared_prefix_n, $shared_separator_n ],
1803             ],                    # or undef
1804             [
1805                 [ $public_prefix_1, $public_separator_1 ],
1806                 [ $public_prefix_2, $public_separator_2 ],
1807                 [ $public_prefix_n, $public_separator_n ],
1808             ],                    # or undef
1809         ];
1810
1811   on
1812       Example:
1813
1814         my @msgs = $imap->on($Rfc3501_date)
1815           or warn "Could not find messages sent on $Rfc3501_date: $@\n";
1816
1817       The on method works just like the "since" method, below, except it
1818       returns a list of messages whose internal system dates are the same as
1819       the date supplied as the argument.
1820
1821   parse_headers
1822       Example:
1823
1824         my $hashref = $imap->parse_headers( $msg || \@msgs, "Date", "Subject" )
1825           or die "Could not parse_headers: $@\n";
1826
1827       The parse_headers method accepts as arguments a message sequence number
1828       and a list of header fields.  It returns a hash reference in which the
1829       keys are the header field names (without the colon) and the values are
1830       references to arrays of values.  On failure <undef> is returned and
1831       "LastError" is set.
1832
1833       A picture would look something like this:
1834
1835         $hashref = $imap->parse_headers( 1, "Date", "Received", "Subject", "To");
1836         $hashref = {
1837             "Date"     => [ "Thu, 09 Sep 1999 09:49:04 -0400" ]  ,
1838             "Received" => [ q/
1839               from mailhub ([111.11.111.111]) by mailhost.bigco.com
1840               (Netscape Messaging Server 3.6)  with ESMTP id AAA527D for
1841               <bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
1842               /, q/
1843               from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
1844               id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
1845               (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
1846               /, q/
1847               from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
1848               with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
1849               18 Jun 1999 16:29:05 +0000 (GMT)
1850               /] ,
1851             "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
1852             "To"      => [ "Big Shot <big.shot@bigco.com> ] ,
1853         };
1854
1855       The text in the example for the "Received" array has been formatted to
1856       make reading the example easier.  The actual values returned are just
1857       strings of words separated by spaces and with newlines and carriage
1858       returns stripped off.  The Received header is probably the main reason
1859       that the parse_headers method creates a hash of lists rather than a
1860       hash of values.
1861
1862       If the second argument to parse_headers is 'ALL' or if it is
1863       unspecified then all available headers are included in the returned
1864       hash of lists.
1865
1866       If you're not emotionally prepared to deal with a hash of lists then
1867       you can always call the "fetch" method yourself with the appropriate
1868       parameters and parse the data out any way you want to.  Also, in the
1869       case of headers whose contents are also reflected in the envelope, you
1870       can use the "get_envelope" method as an alternative to "parse_headers".
1871
1872       If the "Uid" parameter is true then the first argument will be treated
1873       as a message UID.  If the first argument is a reference to an array of
1874       message sequence numbers (or UID's if "Uid" is true), then
1875       parse_headers will be run against each message in the array.  In this
1876       case the return value is a hash, in which the key is the message
1877       sequence number (or UID) and the value is a reference to a hash as
1878       described above.
1879
1880       An example of using parse_headers to print the date and subject of
1881       every message in your demo folder could look like this:
1882
1883         use Mail::IMAPClient;
1884         my $imap = Mail::IMAPClient->new(
1885             Server => $imaphost, User => $login, Password => $pass, Uid => 1
1886         );
1887
1888         $imap->select("demo");
1889
1890         my $msgs = $imap->search("ALL");
1891         for my $h (
1892
1893          # get the Subject and Date from every message in folder "demo" the
1894          # first arg is a reference to an array listing all messages in the
1895          # folder (which is what gets returned by the $imap->search("ALL")
1896          # method when called in scalar context) and the remaining arguments
1897          # are the fields to parse out The key is the message number, which
1898          # in this case we don't care about:
1899
1900           values %{ $imap->parse_headers( $msgs , "Subject", "Date") } )
1901         {
1902             # $h is the value of each element in the hash ref returned
1903             # from parse_headers, and $h is also a reference to a hash.
1904             # We'll only print the first occurrence of each field because
1905             # we don't expect more than one Date: or Subject: line per
1906             # message.
1907             print map { "$_:\t$h->{$_}[0]\n"} keys %$h;
1908         }
1909
1910   recent
1911       Example:
1912
1913         my @recent = $imap->recent or warn "No recent msgs: $@\n";
1914
1915       The recent method performs an IMAP SEARCH RECENT search against the
1916       selected folder and returns an array of sequence numbers (or UID's, if
1917       the "Uid" parameter is true) of messages that are recent.
1918
1919   recent_count
1920       Example:
1921
1922         my $count = 0;
1923         defined($count = $imap->recent_count($folder))
1924           or die "recent_count failed: $@\n";
1925
1926       The recent_count method accepts as an argument a folder name.  It
1927       returns the number of recent messages in the folder (as returned by the
1928       IMAP client command "STATUS folder RECENT"), or "undef" in the case of
1929       an error.  The recent_count method was contributed by Rob Deker
1930       (deker@ikimbo.com).
1931
1932   noop
1933       Example:
1934
1935         $imap->noop or die "noop failed: $@\n";
1936
1937       The noop method performs an IMAP NOOP command.  Per RFC3501 this
1938       command does nothing and always succeeds.  However, if a connection
1939       times out or other errors occur while communicating with the server,
1940       this method can still fail.  This command can be used as a periodic
1941       poll to check for (untagged) status updates (new messages, etc.) from
1942       the server and also to reset any inactivity/auto-logout timers the
1943       server may maintain.
1944
1945   reconnect
1946       Example:
1947
1948         $imap->noop or $imap->reconnect or die "noop failed: $@\n";
1949
1950       Attempt to reconnect if the IMAP connection unless $imap is already in
1951       the IsConnected state.  This method calls "connect" and optionally
1952       "select" if a Folder was previously selected.  On success, returns the
1953       (same) $imap object.  On failure <undef> is returned and "LastError" is
1954       set.
1955
1956       Version note: method added in Mail::IMAPClient 3.17
1957
1958   rename
1959       Example:
1960
1961         $imap->rename( $oldname, $nedwname )
1962           or die "rename failed: $@\n";
1963
1964       The rename method accepts two arguments: the name of an existing
1965       folder, and a new name for the folder.  The existing folder will be
1966       renamed to the new name using the RENAME IMAP client command.  rename
1967       will return a true value if successful, or "undef" if unsuccessful.
1968
1969   restore_message
1970       Example:
1971
1972         $imap->restore_message(@msgs) or die "restore_message failed: $@\n";
1973
1974       The restore_message method is used to undo a previous "delete_message"
1975       operation (but not if there has been an intervening "expunge" or
1976       "close").  The IMAPClient object must be in "Selected" status to use
1977       the restore_message method.
1978
1979       The restore_message method accepts a list of arguments.  If the "Uid"
1980       parameter is not set to a true value, then each item in the list should
1981       be either:
1982
1983       >   a message sequence number,
1984
1985       >   a comma-separated list of message sequence numbers,
1986
1987       >   a reference to an array of message sequence numbers, or
1988
1989       If the "Uid" parameter is set to a true value, then each item in the
1990       list should be either:
1991
1992       >   a message UID,
1993
1994       >   a comma-separated list of UID's, or
1995
1996       >   a reference to an array of message UID's.
1997
1998       The messages identified by the sequence numbers or UID's will have
1999       their \Deleted flags cleared, effectively "undeleting" the messages.
2000       restore_message returns the number of messages it was able to restore.
2001
2002       Note that restore_messages is similar to calling
2003       ""unset_flag"("\Deleted",@msgs)", except that restore_messages returns
2004       a (slightly) more meaningful value. Also it's easier to type.
2005
2006   run
2007       Example:
2008
2009         $imap->run(@args) or die "run failed: $@\n";
2010
2011       The run method is provided to make those uncommon things possible...
2012       however, we would like you to contribute the knowledge of missing
2013       features with us.
2014
2015       The run method excepts one or two arguments.  The first argument is a
2016       string containing an IMAP client command, including a tag and all
2017       required arguments.  The optional second argument is a string to look
2018       for that will indicate success.  (The default is "/OK.*/").  The run
2019       method returns an array (or arrayref in scalar context) of output lines
2020       from the command, which you are free to parse as you see fit.
2021
2022       The run method does not do any syntax checking, other than rudimentary
2023       checking for a tag.
2024
2025       When run processes the command, it increments the transaction count and
2026       saves the command and responses in the History buffer in the same way
2027       other commands do.  However, it also creates a special entry in the
2028       History buffer named after the tag supplied in the string passed as the
2029       first argument.  If you supply a numeric value as the tag then you may
2030       risk overwriting a previous transaction's entry in the History buffer.
2031
2032       If you want the control of run but you don't want to worry about tags
2033       then see "tag_and_run", below.
2034
2035   search
2036       Example:
2037
2038         my $msgs1 = $imap->search(@args);
2039         if ($msgs1) {
2040             print "search matches: @$msgs1";
2041         }
2042         else {
2043             warn "Error in search: $@\n" if $@;
2044         }
2045
2046         # or  note: be sure to quote string properly
2047         my $msgs2 = $imap->search( \( $imap->Quote($msgid), "FROM", q{"me"} ) )
2048           or warn "search failed: $@\n";
2049
2050         # or  note: be sure to quote string properly
2051         my $msgs3 = $imap->search('TEXT "string not in mailbox"')
2052           or warn "search failed: $@\n";
2053
2054       The search method implements the SEARCH IMAP client command.  Any
2055       arguments supplied to search are prefixed with a space then appended to
2056       the SEARCH IMAP client command.  The SEARCH IMAP client command allows
2057       for many options and arguments.  See RFC3501 for details.
2058
2059       As of version 3.17 search tries to "DWIM" by automatically quoting
2060       things that likely need quotes when the words do not match any of the
2061       following:
2062
2063           ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED
2064           FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
2065           SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
2066           TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
2067           UNKEYWORD UNSEEN
2068
2069       The following options exist to avoid the automatic quoting (note:
2070       caller is responsible for verifying the data sent in these cases is
2071       properly escaped/quoted):
2072
2073       •   specify a single string/argument in the call to search.
2074
2075       •   specify args as scalar references (SCALAR) and the values of those
2076           SCALAR refs will be passed along as-is.
2077
2078       The search method returns an array containing sequence numbers of
2079       messages that passed the SEARCH IMAP client command's search criteria.
2080       If the "Uid" parameter is true then the array will contain message
2081       UID's.  If search is called in scalar context then a pointer to the
2082       array will be passed, instead of the array itself.  If no messages meet
2083       the criteria then search returns an empty list (when in list context)
2084       or "undef" (in scalar context).
2085
2086       Since a valid, successful search can legitimately return zero matches,
2087       you may wish to distinguish between a search that correctly returns
2088       zero hits and a search that has failed for some other reason (i.e.
2089       invalid search parameters).  Therefore, the $@ variable will always be
2090       cleared before the SEARCH command is issued to the server, and will
2091       thus remain empty unless the server gives a BAD or NO response to the
2092       SEARCH command.
2093
2094   see
2095       Example:
2096
2097         $imap->see(@msgs) or die "see failed: $@\n";
2098
2099       The see method accepts a list of one or more messages sequence numbers,
2100       or a single reference to an array of one or more message sequence
2101       numbers, as its argument(s).  It then sets the \Seen flag for those
2102       message(s).  Of course, if the "Uid" parameter is set to a true value
2103       then those message sequence numbers had better be unique message id's,
2104       but then you already knew that, didn't you?
2105
2106       Note that specifying "$imap->see(@msgs)" is just a shortcut for
2107       specifying "$imap->"set_flag"("Seen",@msgs)".
2108
2109   seen
2110       Example:
2111
2112         my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
2113
2114       The seen method performs an IMAP SEARCH SEEN search against the
2115       selected folder and returns an array of sequence numbers of messages
2116       that have already been seen (ie their \Seen flag is set).  If the "Uid"
2117       parameter is true then an array of message UID's will be returned
2118       instead.  If called in scalar context than a reference to the array
2119       (rather than the array itself) will be returned.
2120
2121   select
2122       Example:
2123
2124         $imap->select($folder) or die "select failed: $@\n";
2125
2126       The select method selects a folder and changes the object's state to
2127       Selected.  It accepts one argument, which is the name of the folder to
2128       select.
2129
2130   selectable
2131       Example:
2132
2133         foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
2134             $imap->select($f);
2135         }
2136
2137       The selectable method accepts one value, a folder name, and returns
2138       true if the folder is selectable or false if it is not selectable.
2139
2140   sentbefore
2141       Example:
2142
2143         my @msgs = $imap->sentbefore($Rfc3501_date)
2144           or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
2145
2146       The sentbefore method works just like "sentsince", below, except it
2147       searches for messages that were sent before the date supplied as an
2148       argument to the method.
2149
2150   senton
2151       Example:
2152
2153         my @msgs = $imap->senton($Rfc3501_date)
2154           or warn "Could not find any messages sent on $Rfc3501_date: $@\n";
2155
2156       The senton method works just like "sentsince", below, except it
2157       searches for messages that were sent on the exact date supplied as an
2158       argument to the method.
2159
2160   sentsince
2161       Example:
2162
2163         my @msgs = $imap->sentsince($Rfc3501_date)
2164           or warn "Could not find any messages sent since $Rfc3501_date: $@\n";
2165
2166       The sentsince method accepts one argument, a date in either epoch time
2167       format (seconds since 1/1/1970, or as output by time and as accepted by
2168       localtime) or in the date_text format as defined in RFC3501 (dd-Mon-
2169       yyyy, where Mon is the English-language three-letter abbreviation for
2170       the month).
2171
2172       It searches for items in the currently selected folder for messages
2173       sent since the day whose date is provided as the argument.  It uses the
2174       RFC822 Date: header to determine the sentsince date.  (Actually, it the
2175       server that uses the Date: header; this documentation just assumes that
2176       the date is coming from the Date: header because that's what RFC3501
2177       dictates.)
2178
2179       In the case of arguments supplied as a number of seconds, the returned
2180       result list will include items sent on or after that day, regardless of
2181       whether they arrived before the specified time on that day.  The IMAP
2182       protocol does not support searches at a granularity finer than a day,
2183       so neither do I.  On the other hand, the only thing I check for in a
2184       date_text argument is that it matches the pattern
2185       "/\d\d-\D\D\D-\d\d\d\d/" (notice the lack of anchors), so if your
2186       server lets you add something extra to a date_text string then so will
2187       Mail::IMAPClient.
2188
2189       If you'd like, you can use the "Rfc3501_date" method to convert from
2190       epoch time (as returned by time) into an RFC3501 date specification.
2191
2192   separator
2193       Example:
2194
2195         my $sepChar = $imap->separator(@args)
2196           or die "Could not get separator: $@\n";
2197
2198       The separator method returns the character used as a separator
2199       character in folder hierarchies.  On UNIX-based servers, this is often
2200       but not necessarily a forward slash (/).  It accepts one argument, the
2201       name of a folder whose hierarchy's separator should be returned.  If no
2202       folder name is supplied then the separator for the INBOX is returned,
2203       which probably is good enough.
2204
2205       If you want your programs to be portable from IMAP server brand X to
2206       IMAP server brand Y, then you should never use hard-coded separator
2207       characters to specify subfolders.  (In fact, it's even more complicated
2208       than that, since some server don't allow any subfolders at all, some
2209       only allow subfolders under the "INBOX" folder, and some forbid
2210       subfolders in the inbox but allow them "next" to the inbox.
2211       Furthermore, some server implementations do not allow folders to
2212       contain both subfolders and mail messages; other servers allow this.)
2213
2214   set_flag
2215       Example:
2216
2217         $imap->set_flag( "Seen", @msgs )
2218           or die "Could not set flag: $@\n";
2219
2220       The set_flag method accepts the name of a flag as its first argument
2221       and a list of one or more messages sequence numbers, or a single
2222       reference to an array of one or more message sequence numbers, as its
2223       next argument(s).  It then sets the flag specified for those
2224       message(s).  Of course, if the "Uid" parameter is set to a true value
2225       then those message sequence numbers had better be unique message id's,
2226       just as you'd expect.
2227
2228       Note that when specifying the flag in question, the preceding backslash
2229       (\) is entirely optional.  (For you, that is.  Mail::IMAPClient still
2230       has remember to stick it in there before passing the command to the
2231       server if the flag is one of the reserved flags specified in RFC3501.
2232       This is in fact so important that the method checks its argument and
2233       adds the backslash when necessary, which is why you don't have to worry
2234       about it overly much.)
2235
2236   setacl
2237       Example:
2238
2239         $imap->setacl( $folder, $userid, $aclstring )
2240           or die "Could not set acl: $@\n";
2241
2242       The setacl method accepts three input arguments, a folder name, a user
2243       id (or authentication identifier, to use the terminology of RFC2086),
2244       and an access rights modification string.  See RFC2086 for more
2245       information.  (This is somewhat experimental and its implementation may
2246       change.)
2247
2248   since
2249       Example:
2250
2251         my @msgs = $imap->since($date)
2252           or warn "Could not find any messages since $date: $@\n";
2253
2254       The since method accepts a date in either epoch format (seconds since
2255       1/1/1970, or as output by "time" in perlfunc and as accepted by
2256       "localtime" in perlfunc) or in the date_text format as defined in
2257       RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter
2258       abbreviation for the month).  It searches for items in the currently
2259       selected folder for messages whose internal dates are on or after the
2260       day whose date is provided as the argument.  It uses the internal
2261       system date for a message to determine if that message was sent since
2262       the given date.
2263
2264       In the case of arguments supplied as a number of seconds, the returned
2265       result list will include items whose internal date is on or after that
2266       day, regardless of whether they arrived before the specified time on
2267       that day.
2268
2269       If since is called in a list context then it will return a list of
2270       messages meeting the SEARCH SINCE criterion, or an empty list if no
2271       messages meet the criterion.
2272
2273       If since is called in a scalar context then it will return a reference
2274       to an array of messages meeting the SEARCH SINCE criterion, or "undef"
2275       if no messages meet the criterion.
2276
2277       Since since is a front-end to "search", some of the same rules apply.
2278       For example, the $@ variable will always be cleared before the SEARCH
2279       command is issued to the server, and will thus remain empty unless the
2280       server gives a BAD or NO response to the SEARCH command.
2281
2282   size
2283       Example:
2284
2285         my $size = $imap->size($msgId)
2286           or die "Could not find size of message $msgId: $@\n";
2287
2288       The size method accepts one input argument, a sequence number (or
2289       message UID if the "Uid" parameter is true).  It returns the size of
2290       the message in the currently selected folder with the supplied sequence
2291       number (or UID).  The IMAPClient object must be in a Selected state in
2292       order to use this method.
2293
2294   sort
2295       Example:
2296
2297         my @msgs = $imap->sort(@args);
2298         warn "Error in sort: $@\n" if $@;
2299
2300       The sort method is just like the "search" method, only different.  It
2301       implements the SORT extension as described in
2302       https://tools.ietf.org/html/rfc5256.  It would be wise to use the
2303       "has_capability" method to verify that the SORT capability is available
2304       on your server before trying to use the sort method.  If you forget to
2305       check and you're connecting to a server that doesn't have the SORT
2306       capability then sort will return undef.  "LastError" will then say you
2307       are "BAD".  If your server doesn't support the SORT capability then
2308       you'll have to use "search" and then sort the results yourself.
2309
2310       The first argument to sort is a space-delimited list of sorting
2311       criteria.  The Internet Draft that describes SORT requires that this
2312       list be wrapped in parentheses, even if there is only one sort
2313       criterion.  If you forget the parentheses then the sort method will add
2314       them.  But you have to forget both of them, or none.  This isn't CMS
2315       running under VM!
2316
2317       The second argument is a character set to use for sorting.  Different
2318       character sets use different sorting orders, so this argument is
2319       important.  Since all servers must support UTF-8 and US-ASCII if they
2320       support the SORT capability at all, you can use one of those if you
2321       don't have some other preferred character set in mind.
2322
2323       The rest of the arguments are searching criteria, just as you would
2324       supply to the "search" method.  These are all documented in RFC3501.
2325       If you just want all of the messages in the currently selected folder
2326       returned to you in sorted order, use ALL as your only search criterion.
2327
2328       The sort method returns an array containing sequence numbers of
2329       messages that passed the SORT IMAP client command's search criteria.
2330       If the "Uid" parameter is true then the array will contain message
2331       UID's.  If sort is called in scalar context then a pointer to the array
2332       will be passed, instead of the array itself.  The message sequence
2333       numbers or unique identifiers are ordered according to the sort
2334       criteria specified.  The sort criteria are nested in the order
2335       specified; that is, items are sorted first by the first criterion, and
2336       within the first criterion they are sorted by the second criterion, and
2337       so on.
2338
2339       The sort method will clear $@ before attempting the SORT operation just
2340       as the "search" method does.
2341
2342   starttls
2343       Example:
2344
2345         $imap->starttls() or die "starttls failed: $@\n";
2346
2347       The starttls method accepts no arguments.  This method is used to
2348       upgrade an exiting connection which is not authenticated to a TLS/SSL
2349       connection by using the IMAP STARTTLS command followed by using the
2350       start_SSL class method from IO::Socket::SSL to do the necessary TLS
2351       negotiation.  The negotiation is done in a blocking fashion with a
2352       default Timeout of 30 seconds.  The arguments used in the call to
2353       start_SSL can be controlled by setting the Mail::IMAPClient "Starttls"
2354       attribute to an ARRAY reference containing the desired arguments.
2355
2356       Version note: method added in Mail::IMAPClient 3.22
2357
2358   status
2359       Example:
2360
2361         my @rawdata = $imap->status( $folder, qw/(Messages)/ )
2362           or die "Error obtaining status: $@\n";
2363
2364       The status method accepts one argument, the name of a folder (or
2365       mailbox, to use RFC3501's terminology), and returns an array containing
2366       the results of running the IMAP STATUS client command against that
2367       folder.  If additional arguments are supplied then they are appended to
2368       the IMAP STATUS client command string, separated from the rest of the
2369       string and each other with spaces.
2370
2371       If status is not called in an array context then it returns a reference
2372       to an array rather than the array itself.
2373
2374       The status method should not be confused with the Status method (with
2375       an uppercase 'S'), which returns information about the IMAPClient
2376       object.  (See the section labeled "Status Methods", below).
2377
2378   store
2379       Example:
2380
2381         $imap->store(@args) or die "Could not store: $@\n";
2382
2383       The store method accepts a message sequence number or comma-separated
2384       list of message sequence numbers as a first argument, a message data
2385       item name, and a value for the message data item.  Currently, data
2386       items are the word "FLAGS" followed by a space and a list of flags (in
2387       parens).  The word "FLAGS" can be modified by prefixing it with either
2388       a "+" or a "-" (to indicate "add these flags" or "remove these flags")
2389       and by suffixing it with ".SILENT" (which reduces the amount of output
2390       from the server; very useful with large message sets).  Normally you
2391       won't need to call store because there are oodles of methods that will
2392       invoke store for you with the correct arguments.  Furthermore, these
2393       methods are friendlier and more flexible with regards to how you
2394       specify your arguments.  See for example "see", "deny_seeing",
2395       "delete_message", and "restore_message".  Or "mark", "unmark",
2396       "set_flag", and "unset_flag".
2397
2398   subject
2399       Example:
2400
2401         my $subject = $imap->subject($msg);
2402
2403       The subject method accepts one argument, a message sequence number (or
2404       a message UID, if the Uid parameter is true).  The text in the
2405       "Subject" header of that message is returned (without the "Subject: "
2406       prefix).  This method is a short-cut for:
2407
2408         my $subject = $imap->get_header($msg, "Subject");
2409
2410   subscribed
2411       Example:
2412
2413         my @subscribedFolders = $imap->subscribed
2414           or warn "Could not find subscribed folders: $@\n";
2415
2416       The subscribed method works like the folders method, above, except that
2417       the returned list (or array reference, if called in scalar context)
2418       contains only the subscribed folders.
2419
2420       Like "folders", you can optionally provide a prefix argument to the
2421       subscribed method.
2422
2423   tag_and_run
2424       Example:
2425
2426         my $output = $imap->tag_and_run(@args)
2427           or die "Could not tag_and_run: $@\n";
2428
2429       The tag_and_run method accepts one or two arguments.  The first
2430       argument is a string containing an IMAP client command, without a tag
2431       but with all required arguments.  The optional second argument is a
2432       string to look for that will indicate success (without pattern
2433       delimiters).  The default is "OK.*".
2434
2435       The tag_and_run method will prefix your string (from the first
2436       argument) with the next transaction number and run the command.  It
2437       returns an array of output lines from the command, which you are free
2438       to parse as you see fit.  Using this method instead of run (above) will
2439       free you from having to worry about handling the tags (and from
2440       worrying about the side affects of naming your own tags).
2441
2442   uidexpunge
2443       Example:
2444
2445         $imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";
2446
2447       The uidexpunge method implements the UID EXPUNGE IMAP (RFC4315 UIDPLUS
2448       ext) client command to permanently remove all messages that have the
2449       \Deleted flag set and have a UID that is included in the list of UIDs.
2450
2451       uidexpunge returns an array or arrayref (scalar context) of output
2452       lines returned from the UID EXPUNGE command.
2453
2454       uidexpunge returns undef on failure.
2455
2456       If the server does not support the UIDPLUS extension, this method
2457       returns undef.
2458
2459   uidnext
2460       Example:
2461
2462         my $nextUid = $imap->uidnext($folder) or die "uidnext failed: $@\n";
2463
2464       The uidnext method accepts one argument, the name of a folder, and
2465       returns the numeric string that is the next available message UID for
2466       that folder.
2467
2468   thread
2469       Example:
2470
2471         my $thread = $imap->thread( $algorithm, $charset, @search_args );
2472
2473       The thread method accepts zero to three arguments.  The first argument
2474       is the threading algorithm to use, generally either ORDEREDSUBJECT or
2475       REFERENCES.  The second argument is the character set to use, and the
2476       third argument is the set of search arguments to use.
2477
2478       If the algorithm is not supplied, it defaults to REFERENCES if
2479       available, or ORDEREDSUBJECT if available.  If neither of these is
2480       available then the thread method returns undef.
2481
2482       If the character set is not specified it will default to UTF-8.
2483
2484       If the search arguments are not specified, the default is ALL.
2485
2486       If thread is called for an object connected to a server that does not
2487       support the THREADS extension then the thread method will return
2488       "undef".
2489
2490       The threads method will issue the THREAD command as defined in
2491       https://tools.ietf.org/html/rfc5256.  It returns an array of threads.
2492       Each element in the array is either a message id or a reference to
2493       another array of (sub)threads.
2494
2495       If the "Uid" parameter is set to a true value then the message id's
2496       returned in the thread structure will be message UID's.  Otherwise they
2497       will be message sequence numbers.
2498
2499   uidvalidity
2500       Example:
2501
2502         my $validity = $imap->uidvalidity($folder)
2503           or die "uidvalidity failed: $@\n";
2504
2505       The uidvalidity method accepts one argument, the name of a folder, and
2506       returns the numeric string that is the unique identifier validity value
2507       for the folder.
2508
2509   unmark
2510       Example:
2511
2512         $imap->unmark(@msgs) or die "Could not unmark: $@\n";
2513
2514       The unmark method accepts a list of one or more messages sequence
2515       numbers, or a single reference to an array of one or more message
2516       sequence numbers, as its argument(s).  It then unsets the \Flagged flag
2517       for those message(s).  Of course, if the "Uid" parameter is set to a
2518       true value then those message sequence numbers should really be unique
2519       message id's.
2520
2521       Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
2522       specifying "$imap->unset_flag("Flagged",@msgs)".
2523
2524       Note also that the \Flagged flag is just one of many possible flags.
2525       This is a little confusing, but you'll have to get used to the idea
2526       that among the reserved flags specified in RFC3501 is one name
2527       \Flagged.  There is no specific meaning for this flag; it means
2528       whatever the mailbox owner (or delegate) wants it to mean when it is
2529       turned on.
2530
2531   unseen
2532       Example:
2533
2534         my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
2535
2536       The unseen method performs an IMAP SEARCH UNSEEN search against the
2537       selected folder and returns an array of sequence numbers of messages
2538       that have not yet been seen (ie their \Seen flag is not set).  If the
2539       "Uid" parameter is true then an array of message UID's will be returned
2540       instead.  If called in scalar context than a pointer to the array
2541       (rather than the array itself) will be returned.
2542
2543   unseen_count
2544       Example:
2545
2546         foreach my $f ($imap->folders) {
2547             print "The $f folder has ",
2548               $imap->unseen_count($f)||0, " unseen messages.\n";
2549         }
2550
2551       The unseen_count method accepts the name of a folder as an argument and
2552       returns the number of unseen messages in that folder.  If no folder
2553       argument is provided then it returns the number of unseen messages in
2554       the currently selected Folder.
2555
2556   unset_flag
2557       Example:
2558
2559         $imap->unset_flag( "\Seen", @msgs )
2560           or die "unset_flag failed: $@\n";
2561
2562       The unset_flag method accepts the name of a flag as its first argument
2563       and a list of one or more messages sequence numbers, or a single
2564       reference to an array of one or more message sequence numbers, as its
2565       next argument(s).  It then unsets the flag specified for those
2566       message(s).  Of course, if the "Uid" parameter is set to a true value
2567       then those message sequence numbers had better be unique message id's,
2568       just as you'd expect.
2569

Other IMAP Client Commands

2571       Until release 2.99, when you called a method which did not exist, they
2572       where automatically translated into an IMAP call with the same name via
2573       an AUTOLOAD hack.  This "feature" was removed for various reasons:
2574       people made typos in the capitalization of method names, and the
2575       program still seemed to work correctly.  Besides, it blocked further
2576       development of this module, because people did not contribute their
2577       private extensions to the protocol implementation.
2578
2579   copy($msg, $folder)
2580       Copy a message from the currently selected folder in the folder whose
2581       name is in $folder
2582
2583   subscribe($folder)
2584       Subscribe to a folder
2585
2586       CAUTION: Once again, remember to quote your quotes (or use the "Quote"
2587       method) if you want quotes to be part of the IMAP command string.
2588
2589       You can also use the default method to override the behavior of
2590       implemented IMAP methods by changing the case of the method name,
2591       preferably to all-uppercase so as not to conflict with the Class method
2592       and accessor method namespace.  For example, if you don't want the
2593       "search" method's behavior (which returns a list of message numbers)
2594       but would rather have an array of raw data returned from your "search"
2595       operation, you can issue the following snippet:
2596
2597         my @raw = $imap->SEARCH("SUBJECT","Whatever...");
2598
2599       which is slightly more efficient than the equivalent:
2600
2601         $imap->search("SUBJECT","Whatever...");
2602         my @raw = $imap->Results;
2603
2604       Of course you probably want the search results tucked nicely into a
2605       list for you anyway, in which case you might as well use the "search"
2606       method.
2607

Parameters

2609       There are several parameters that influence the behavior of an
2610       IMAPClient object.  Each is set by specifying a named value pair during
2611       new method invocation as follows:
2612
2613         my $imap = Mail::IMAPClient->new ( parameter  => "value",
2614             parameter2 => "value",
2615             ...
2616         );
2617
2618       Parameters can also be set after an object has been instantiated by
2619       using the parameter's eponymous accessor method like this:
2620
2621         my $imap = Mail::IMAPClient->new;
2622            $imap->parameter( "value");
2623            $imap->parameter2("value");
2624
2625       The eponymous accessor methods can also be used without arguments to
2626       obtain the current value of the parameter as follows:
2627
2628         my $imap = Mail::IMAPClient->new;
2629            $imap->parameter( "value");
2630            $imap->parameter2("value");
2631
2632           ...    # A whole bunch of awesome Perl code, omitted for brevity
2633
2634         my $forgot  = $imap->parameter;
2635         my $forgot2 = $imap->parameter2;
2636
2637       Note that in these examples I'm using 'parameter' and 'parameter2' as
2638       generic parameter names.  The IMAPClient object doesn't actually have
2639       parameters named 'parameter' and 'parameter2'.  On the contrary, the
2640       available parameters are:
2641
2642   Authmechanism
2643       Example:
2644
2645         $imap->Authmechanism("CRAM-MD5");
2646         # or
2647         my $authmech = $imap->Authmechanism();
2648
2649       If specified, the Authmechanism causes the specified authentication
2650       mechanism to be used whenever Mail::IMAPClient would otherwise invoke
2651       login.  If the value specified for the Authmechanism parameter is not a
2652       valid authentication mechanism for your server then you will never ever
2653       be able to log in again for the rest of your Perl script, probably.  So
2654       you might want to check, like this:
2655
2656         my $authmech = "CRAM-MD5";
2657         $imap->has_capability($authmech) and $imap->Authmechanism($authmech);
2658
2659       Of course if you know your server supports your favorite authentication
2660       mechanism then you know, so you can then include your Authmechanism
2661       with your new call, as in:
2662
2663         my $imap = Mail::IMAPClient->new(
2664             User    => $user,
2665             Passord => $passord,
2666             Server  => $server,
2667             Authmechanism  => $authmech,
2668             %etc
2669         );
2670
2671       If Authmechanism is supplied but Authcallback is not then you had
2672       better be supporting one of the authentication mechanisms that
2673       Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2674
2675   Authcallback
2676       Example:
2677
2678         $imap->Authcallback( \&callback );
2679
2680       This specifies a default callback to the default authentication
2681       mechanism (see "Authmechanism", above).  Together, these two methods
2682       replace automatic calls to login with automatic calls that look like
2683       this (sort of):
2684
2685         $imap->authenticate($imap->Authmechanism,$imap->Authcallback);
2686
2687       If Authmechanism is supplied but Authcallback is not then you had
2688       better be supporting one of the authentication mechanisms that
2689       Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2690
2691   Authuser
2692       The Authuser parameter is used by the DIGEST-MD5 "Authmechanism".
2693
2694       Typically when you authenticate the username specified in the User
2695       parameter is used.  However, when using the DIGEST-MD5 Authmechanism
2696       the Authuser can be used to specify a different username for the login.
2697
2698       This can be useful to mark messages as seen for the Authuser if you
2699       don't know the password of the user as the seen state is often a per-
2700       user state.
2701
2702   Buffer
2703       Example:
2704
2705         $Buffer = $imap->Buffer();
2706         # or:
2707         $imap->Buffer($new_value);
2708
2709       The Buffer parameter sets the size of a block of I/O.  It is ignored
2710       unless "Fast_io", below, is set to a true value (the default), or
2711       unless you are using the "migrate" method.  It's value should be the
2712       number of bytes to attempt to read in one I/O operation.  The default
2713       value is 4096.
2714
2715       When using the "migrate" method, you can often achieve dramatic
2716       improvements in throughput by adjusting this number upward.  However,
2717       doing so also entails a memory cost, so if set too high you risk losing
2718       all the benefits of the "migrate" method's chunking algorithm.  Your
2719       program can thus terminate with an "out of memory" error and you'll
2720       have no one but yourself to blame.
2721
2722       Note that, as hinted above, the Buffer parameter affects the behavior
2723       of the "migrate" method regardless of whether you have "Fast_io" turned
2724       on.  Believe me, you don't want to go around migrating tons of mail
2725       without using buffered I/O!
2726
2727   Clear
2728       Example:
2729
2730         $Clear = $imap->Clear();
2731         # or:
2732         $imap->Clear($integer);
2733
2734       The name of this parameter, for historical reasons, is somewhat
2735       misleading.  It should be named Wrap, because it specifies how many
2736       transactions are stored in the wrapped history buffer.  But it didn't
2737       always work that way; the buffer used to actually get cleared.  The
2738       name though remains the same in the interests of backwards
2739       compatibility.
2740
2741       Clear specifies that the object's history buffer should be wrapped
2742       after every n transactions, where n is the value specified for the
2743       Clear parameter.  Calling the eponymous Clear method without an
2744       argument will return the current value of the Clear parameter but will
2745       not cause clear the history buffer to wrap.
2746
2747       Setting Clear to 0 turns off automatic history buffer wrapping, and
2748       setting it to 1 turns off the history buffer facility (except for the
2749       last transaction, which cannot be disabled without breaking the
2750       IMAPClient module).  Setting Clear to 0 will not cause an immediate
2751       clearing of the history buffer; setting it to 1 (or any other number)
2752       will (except of course for that inevitable last transaction).
2753
2754       The default Clear value is set to five (5) in order to conserve memory.
2755
2756   Compress
2757       If set, Mail::IMAPClient attempts to enable use of the RFC4978 COMPRESS
2758       DEFLATE extension.  This requires that the server supports this
2759       CAPABILITY.  This attribute can be set to a true value to enable or an
2760       ARRAYREF to control the arguments used in the call to
2761       Compress::Zlib::deflateInit().
2762
2763       Mail::IMAPClient will automatically use Compress::Zlib to
2764       deflate/inflate the data to/from the server.  This attribute is used in
2765       the "login" method.
2766
2767       See also "compress" and "capability".
2768
2769       Version note: attribute added in Mail::IMAPClient 3.30
2770
2771   Debug
2772       Example:
2773
2774         $Debug = $imap->Debug();
2775         # or:
2776         $imap->Debug($true_or_false);
2777
2778       Sets the debugging flag to either a true or false value.  Can be
2779       supplied with the "new" method call or separately by calling the Debug
2780       object method.  Use of this parameter is strongly recommended when
2781       debugging scripts and required when reporting bugs.
2782
2783   Debug_fh
2784       Example:
2785
2786         $Debug_fh = $imap->Debug_fh();
2787         # or:
2788         $imap->Debug_fh($fileHandle);
2789
2790       Specifies the file handle to which debugging information should be
2791       printed.  It can either a file handle object reference or a file handle
2792       glob.  The default is to print debugging info to STDERR.
2793
2794       For example, you can:
2795
2796         use Mail::IMAPClient;
2797         use IO::File;
2798         # set $user, $pass, and $server here
2799         my $dh = IO::File->new(">debugging.output")
2800           or die "Can't open debugging.output: $!\n";
2801         my $imap = Mail::IMAPClient->new(
2802             User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh
2803         );
2804
2805       which is the same as:
2806
2807         use Mail::IMAPClient;
2808         use IO::File;
2809         # set $user, $pass, and $server here
2810         my $imap = Mail::IMAPClient->new(
2811             User     => $user,
2812             Password => $pass,
2813             Server   => $server,
2814             Debug    => "yes, please",
2815             Debug_fh => IO::File->new(">debugging.output")
2816               || die "Can't open debugging.output: $!\n"
2817         );
2818
2819       You can also:
2820
2821         use Mail::IMAPClient;
2822         # set $user, $pass, and $server here
2823         open(DBG,">debugging.output")
2824           or die "Can't open debugging.output: $!\n";
2825         my $imap = Mail::IMAPClient->new(
2826           User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG
2827         );
2828
2829       Specifying this parameter is not very useful unless "Debug" is set to a
2830       true value.
2831
2832   Domain
2833       The Domain parameter is used by the NTLM "Authmechanism".  The domain
2834       is an optional parameter for NTLM authentication.
2835
2836   EnableServerResponseInLiteral
2837       Removed in 2.99_01 (now autodetect)
2838
2839   Fast_io
2840       Example:
2841
2842         $Fast_io = $imap->Fast_io();
2843         # or:
2844         $imap->Fast_io($true_or_false);
2845
2846       The Fast_io parameter controls whether or not the Mail::IMAPClient
2847       object will attempt to use non-blocking I/O on the IMAP socket.  It is
2848       turned on by default (unless the caller provides the socket to be
2849       used).
2850
2851       See also "Buffer".
2852
2853   Folder
2854       Example:
2855
2856         $Folder = $imap->Folder();
2857         # or:
2858         $imap->Folder($new_value);
2859
2860       The Folder parameter returns the name of the currently-selected folder
2861       (in case you forgot).  It can also be used to set the name of the
2862       currently selected folder, which is completely unnecessary if you used
2863       the "select" method (or "select"'s read-only equivalent, the "examine"
2864       method) to select it.
2865
2866       Note that setting the Folder parameter does not automatically select a
2867       new folder; you use the "select" or "examine" object methods for that.
2868       Generally, the Folder parameter should only be queried (by using the
2869       no-argument form of the Folder method).  You will only need to set the
2870       Folder parameter if you use some mysterious technique of your own for
2871       selecting a folder, which you probably won't do.
2872
2873   Ignoresizeerrors
2874       Certain (caching) servers, like Exchange 2007, often report the wrong
2875       message size.  Instead of chopping the message into a size that it fits
2876       the specified size, the reported size will be simply ignored when this
2877       parameter is set to 1.
2878
2879   Keepalive
2880       Some firewalls and network gear like to timeout connections prematurely
2881       if the connection sits idle.  The Keepalive parameter, when set to a
2882       true value, affects the behavior of "new" and "Socket" by enabling
2883       SO_KEEPALIVE on the socket.
2884
2885       Version note: attribute added in Mail::IMAPClient 3.17
2886
2887   Maxcommandlength
2888       The Maxcommandlength attribute is used by fetch() to limit length of
2889       commands sent to a server.  The default is 1000 chars, following the
2890       recommendation of RFC2683 section 3.2.1.5.
2891
2892       Note: this attribute should also be used for several other methods but
2893       this has not yet been implemented please feel free to file bugs for
2894       methods where you run into problems with this.
2895
2896       This attribute should remove the need for utilities like imapsync to
2897       create their own split() functions and instead allows Mail::IMAPClient
2898       to DWIM.
2899
2900       In practice, this parameter has proven to be useful to overcome a limit
2901       of 8000 octets for UW-IMAPD and 16384 octets for Courier/Cyrus IMAP
2902       servers.
2903
2904       Version note: attribute added in Mail::IMAPClient 3.17
2905
2906   Maxtemperrors
2907       Example:
2908
2909         $Maxtemperrors = $imap->Maxtemperrors();
2910         # or:
2911         $imap->Maxtemperrors($number);
2912
2913       The Maxtemperrors parameter specifies the number of times a read or
2914       write operation is allowed to fail on a "Resource Temporarily
2915       Available" (e.g. EAGAIN) error.  The default setting is undef which
2916       means there is no limit.
2917
2918       Setting this parameter to the string "unlimited" (instead of undef) to
2919       ignore "Resource Temporarily Unavailable" errors is deprecated.
2920
2921       Note: This setting should be used with caution and may be removed in a
2922       future release.  Setting this can cause methods to return to the caller
2923       before data is received (and then handled) properly thereby possibly
2924       then leaving the module in a bad state.  In the future, this behavior
2925       may be changed in an attempt to avoid this situation.
2926
2927   Password
2928       Example:
2929
2930         $Password = $imap->Password();
2931         # or:
2932         $imap->Password($new_value);
2933
2934       Specifies the password to use when logging into the IMAP service on the
2935       host specified in the Server parameter as the user specified in the
2936       User parameter.  Can be supplied with the new method call or separately
2937       by calling the Password object method.
2938
2939       If Server, User, and Password are all provided to the "new" method,
2940       then the newly instantiated object will be connected to the host
2941       specified in Server (at either the port specified in Port or the
2942       default port 143) and then logged on as the user specified in the User
2943       parameter (using the password provided in the Password parameter).  See
2944       the discussion of the "new" method, below.
2945
2946   Peek
2947       Example:
2948
2949         $Peek = $imap->Peek();
2950         # or:
2951         $imap->Peek($true_or_false);
2952
2953       Setting Peek to a true value will prevent the "body_string",
2954       "message_string" and "message_to_file" methods from automatically
2955       setting the \Seen flag.  Setting "Peek" to 0 (zero) will force
2956       "body_string", "message_string", "message_to_file", and "parse_headers"
2957       to always set the \Seen flag.
2958
2959       The default is to set the seen flag whenever you fetch the body of a
2960       message but not when you just fetch the headers.  Passing undef to the
2961       eponymous Peek method will reset the Peek parameter to its pristine,
2962       default state.
2963
2964   Port
2965       Example:
2966
2967         $Port = $imap->Port();
2968         # or:
2969         $imap->Port($new_value);
2970
2971       Specifies the port on which the IMAP server is listening.  A default
2972       value of 993 (if "Ssl" is true) or 143 is set during a call to
2973       "connect" if no value is provided by the caller.  This argument can be
2974       supplied with the "new" method call or separately by calling the "Port"
2975       object method.
2976
2977   Prewritemethod
2978       Prewritemethod parameter should contain a reference to a subroutine
2979       that will do "special things" to data before it is sent to the IMAP
2980       server (such as encryption or signing).
2981
2982       This method will be called immediately prior to sending an IMAP client
2983       command to the server.  Its first argument is a reference to the
2984       Mail::IMAPClient object and the second argument is a string containing
2985       the command that will be sent to the server.  Your Prewritemethod
2986       should return a string that has been signed or encrypted or whatever;
2987       this returned string is what will actually be sent to the server.
2988
2989       Your Prewritemethod will probably need to know more than this to do
2990       whatever it does.  It is recommended that you tuck all other pertinent
2991       information into a hash, and store a reference to this hash somewhere
2992       where your method can get to it, possibly in the Mail::IMAPClient
2993       object itself.
2994
2995       Note that this method should not actually send anything over the socket
2996       connection to the server; it merely converts data prior to sending.
2997
2998       See also "Readmethod".
2999
3000   Ranges
3001       Example:
3002
3003         $imap->Ranges(1);
3004         # or:
3005         my $search = $imap->search(@search_args);
3006         if ( $imap->Ranges) { # $search is a MessageSet object
3007             print "This is my condensed search result: $search\n";
3008             print "This is every message in the search result: ",
3009               join(",",@$search),"\n;
3010         }
3011
3012       If set to a true value, then the "search" method will return a
3013       Mail::IMAPClient::MessageSet object if called in a scalar context,
3014       instead of the array reference that fetch normally returns when called
3015       in a scalar context.  If set to zero or if undefined, then search will
3016       continue to return an array reference when called in scalar context.
3017
3018       This parameter has no affect on the search method when search is called
3019       in a list context.
3020
3021   RawSocket
3022       Example:
3023               $socket = $imap->RawSocket;
3024               # or:
3025               $imap->RawSocket($socketh);
3026
3027       The RawSocket method can be used to obtain the socket handle of the
3028       current connection (say, to do I/O on the connection that is not
3029       otherwise supported by Mail::IMAPClient) or to replace the current
3030       socket with a new handle (for instance an SSL handle, see
3031       IO::Socket::SSL, but be sure to see the "Socket" method as well).
3032
3033       If you supply a socket handle yourself, either by doing something like:
3034
3035               $imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
3036
3037       or by doing something like:
3038
3039               $imap = Mail::IMAPClient->new(User => $user,
3040                           Password => $pass, Server => $host);
3041               # blah blah blah
3042               $imap->RawSocket($ssl);
3043
3044       then it will be up to you to establish the connection AND to
3045       authenticate, either via the "login" method, or the fancier
3046       "authenticate", or, since you know so much anyway, by just doing raw
3047       I/O against the socket until you're logged in.  If you do any of this
3048       then you should also set the "State" parameter yourself to reflect the
3049       current state of the object (i.e. Connected, Authenticated, etc).
3050
3051       Note that no operation will be attempted on the socket when this method
3052       is called.  In particular, after the TCP connections towards the IMAP
3053       server is established, the protocol mandates the server to send an
3054       initial greeting message, and you will have to explicitly cope with
3055       this message before doing any other operation, e.g. trying to call
3056       "login". Caveat emptor.
3057
3058       For a more DWIM approach to setting the socket see "Socket".
3059
3060   Readmethod
3061       Example:
3062
3063         $imap->Readmethod(   # IMAP, HANDLE, BUFFER, LENGTH, OFFSET
3064             sub {
3065                 my ( $self, $handle, $buffer, $count, $offset ) = @_;
3066                 my $rc = sysread( $handle, $$buffer, $count, $offset );
3067                 # do something useful here...
3068             }
3069         );
3070
3071       Readmethod should contain a reference to a subroutine that will replace
3072       sysread.  The subroutine will be passed the following arguments: first
3073       the used Mail::IMAPClient object.  Second, a reference to a socket.
3074       Third, a reference to a scalar variable into which data is read
3075       (BUFFER). The data placed here should be "finished data", so if you are
3076       decrypting or removing signatures then be sure to do that before you
3077       place data into this buffer.  Fourth, the number of bytes requested to
3078       be read; the LENGTH of the request.  Lastly, the OFFSET into the BUFFER
3079       where the data should be read.  If not supplied it should default to
3080       zero.
3081
3082       Note that this method completely replaces reads from the connection to
3083       the server, so if you define one of these then your subroutine will
3084       have to actually do the read.  It is for things like this that we have
3085       the "Socket" parameter and eponymous accessor method.
3086
3087       Your Readmethod will probably need to know more than this to do
3088       whatever it does.  It is recommended that you tuck all other pertinent
3089       information into a hash, and store a reference to this hash somewhere
3090       where your method can get to it, possibly in the Mail::IMAPClient
3091       object itself.
3092
3093       See also "Prewritemethod".
3094
3095   Readmoremethod
3096       Readmoremethod should contain a reference to a subroutine that will
3097       replace/enhance the behavior of the internal _read_more() method.  The
3098       subroutine will be passed the following arguments: first the used
3099       Mail::IMAPClient object.  Second, a reference to a socket.  Third, a
3100       timeout value which is used as the timeout value for CORE::select() by
3101       default.  Depending upon changes/features introduced by Readmethod
3102       changes may be required here.
3103
3104       Version note: attribute added in Mail::IMAPClient 3.30
3105
3106   Reconnectretry
3107       If an IMAP connection sits idle too long, the connection may be closed
3108       by the server or firewall, etc.  The Reconnectretry parameter, when
3109       given a positive integer value, will cause Mail::IMAPClient to retrying
3110       IMAP commands up to X times when an EPIPE or ECONNRESET error occurs.
3111       This is disabled (0) by default.
3112
3113       See also "Keepalive"
3114
3115       Version note: attribute added in Mail::IMAPClient 3.17
3116
3117   Server
3118       Example:
3119
3120         $Server = $imap->Server();
3121         # or:
3122         $imap->Server($hostname);
3123
3124       Specifies the hostname or IP address of the host running the IMAP
3125       server.  If provided as part of the "new" method call, then the new
3126       IMAP object will automatically be connected at the time of
3127       instantiation.  (See the "new" method, below.) Can be supplied with the
3128       "new" method call or separately by calling the Server object method.
3129
3130   Showcredentials
3131       Normally debugging output will mask the login credentials when the
3132       plain text login mechanism is used.  Setting Showcredentials to a true
3133       value will suppress this, so that you can see the string being passed
3134       back and forth during plain text login.  Only set this to true when you
3135       are debugging problems with the IMAP LOGIN command, and then turn it
3136       off right away when you're finished working on that problem.
3137
3138       Example:
3139
3140         print "This is very risky!\n" if $imap->Showcredentials();
3141         # or:
3142         $imap->Showcredentials(0);    # mask credentials again
3143
3144   Socket
3145       PLEASE NOTE The semantics of this method has changed as of version
3146       2.99_04 of this module.  If you need the old semantics use "RawSocket".
3147
3148       Example:
3149
3150         $Socket = $imap->Socket();
3151         # or:
3152         $imap->Socket($socket_fh);
3153
3154       The Socket method can be used to obtain the socket handle of the
3155       current connection.  This may be necessary to do I/O on the connection
3156       that is not otherwise supported by Mail::IMAPClient) or to replace the
3157       current socket with a new handle (for instance an SSL handle, see
3158       IO::Socket::SSL).
3159
3160       If you supply a socket handle yourself, either by doing something like:
3161
3162         $imap = Mail::IMAPClient->new( Socket => $sock, User => ... );
3163
3164       or by doing something like:
3165
3166         $imap = Mail::IMAPClient->new(
3167           User => $user, Password => $pass, Server => $host
3168         );
3169         $imap->Socket($ssl);
3170
3171       then you are responsible for establishing the connection, i.e. make
3172       sure that $ssl in the example is a valid and connected socket.
3173
3174       This method is primarily used to provide a drop-in replacement for
3175       IO::Socket::(INET|IP), used by "connect" by default.  In fact, this
3176       method is called by "connect" itself after having established a
3177       suitable IO::Socket::(INET|IP) socket connection towards the target
3178       server; for this reason, this method also carries the normal operations
3179       associated with "connect", namely:
3180
3181       •   read the initial greeting message from the server;
3182
3183       •   call "login" if the conditions apply (see "connect" for details);
3184
3185       •   leave the Mail::IMAPClient object in a suitable state.
3186
3187       For these reasons, the following example will work "out of the box":
3188
3189          use IO::Socket::SSL;
3190          my $imap = Mail::IMAPClient->new
3191           ( User     => 'your-username',
3192             Password => 'your-password',
3193             Socket   => IO::Socket::SSL->new
3194             (  Proto    => 'tcp',
3195                PeerAddr => 'some.imap.server',
3196                PeerPort => 993, # IMAP over SSL standard port
3197             ),
3198          );
3199
3200       If you need more control over the socket, e.g. you have to implement a
3201       fancier authentication method, see "RawSocket".
3202
3203   Starttls
3204       If an IMAP connection must start TLS/SSL after connecting to a server
3205       then set this attribute.  If the value is set to an arrayref then they
3206       will be used as arguments to IO::Socket::SSL->start_SSL.  By default
3207       this connection is set to blocking while establishing the connection
3208       with a timeout of 30 seconds.  The socket will be reset to the original
3209       blocking/non-blocking value after a successful TLS negotiation has
3210       occurred.  The arguments used in the call to start_SSL can be
3211       controlled by setting this attribute to an ARRAY reference containing
3212       the desired arguments.
3213
3214       Version note: attribute added in Mail::IMAPClient 3.22
3215
3216   Socketargs
3217       The arguments used in the call to IO::Socket::{UNIX|INET|IP|SSL}->new
3218       can be controlled by setting this attribute to an ARRAY reference
3219       containing the desired arguments.
3220
3221       For example, to always pass MultiHomed => 1 to IO::Socket::...->new the
3222       following can be used:
3223
3224         $imap = Mail::IMAPClient->new(
3225           ..., Socketargs => [ MultiHomed => 1 ], ...
3226         );
3227
3228       See also "Ssl" for specific control of the args to IO::Socket::SSL.
3229
3230       Version note: attribute added in Mail::IMAPClient 3.34
3231
3232   Ssl
3233       If an IMAP connection requires SSL you can set the Ssl attribute to '1'
3234       and Mail::IMAPClient will automatically use IO::Socket::SSL instead of
3235       IO::Socket::(INET|IP) to connect to the server.  This attribute is used
3236       in the "connect" method.  The arguments used in the call to
3237       IO::Socket::SSL->new can be controlled by setting this attribute to an
3238       ARRAY reference containing the desired arguments.
3239
3240       See also "connect" for details on connection initiation and "Socket"
3241       and "Rawsocket" if you need to take more control of connection
3242       management.
3243
3244       Version note: attribute added in Mail::IMAPClient 3.18
3245
3246   Supportedflags
3247       Especially when "migrate()" is used, the receiving peer may need to be
3248       configured explicitly with the list of supported flags; that may be
3249       different from the source IMAP server.
3250
3251       The names are to be specified as an ARRAY.  Black-slashes and casing
3252       will be ignored.
3253
3254       You may also specify a CODE reference, which will be called for each of
3255       the flags separately.  In this case, the flags are not (yet)
3256       normalized.  The returned lists of the CODE calls are shape the
3257       resulting flag list.
3258
3259   Timeout
3260       Example:
3261
3262         $Timeout = $imap->Timeout();
3263         # or:
3264         $imap->Timeout($seconds);
3265
3266       Specifies the timeout value in seconds for reads (default is 600).
3267       Specifying a Timeout will prevent Mail::IMAPClient from blocking in a
3268       read.
3269
3270       Since timeouts are implemented via the Perl select operator, the
3271       Timeout parameter may be set to a fractional number of seconds.
3272       Setting Timeout to 0 (zero) disables the timeout feature.
3273
3274   Uid
3275       Example:
3276
3277         $Uid = $imap->Uid();
3278         # or:
3279         $imap->Uid($true_or_false);
3280
3281       If "Uid" is set to a true value (i.e. 1) then the behavior of the
3282       "fetch", "search", "copy", and "store" methods (and their derivatives)
3283       is changed so that arguments that would otherwise be message sequence
3284       numbers are treated as message UID's and so that return values (in the
3285       case of the "search" method and its derivatives) that would normally be
3286       message sequence numbers are instead message UID's.
3287
3288       Internally this is implemented as a switch that, if turned on, causes
3289       methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or
3290       COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH,
3291       or UID COPY, respectively.  The main difference between message
3292       sequence numbers and message UID's is that, according to RFC3501, UID's
3293       must not change during a session and should not change between
3294       sessions, and must never be reused.  Sequence numbers do not have that
3295       same guarantee and in fact may be reused right away.
3296
3297       Since folder names also have a unique identifier (UIDVALIDITY), which
3298       is provided when the folder is "select"ed or "examine"d or by doing
3299       something like "$imap->status($folder,"UIDVALIDITY"), it is possible to
3300       uniquely identify every message on the server, although normally you
3301       won't need to bother.
3302
3303       The methods currently affected by turning on the "Uid" flag are:
3304
3305         copy            fetch
3306         search          store
3307         message_string  message_uid
3308         body_string     flags
3309         move            size
3310         parse_headers   thread
3311
3312       Note that if for some reason you only want the "Uid" parameter turned
3313       on for one command, then you can choose between the following two
3314       snippets, which are equivalent:
3315
3316       Example 1:
3317
3318         $imap->Uid(1);
3319         my @uids = $imap->search('SUBJECT',"Just a silly test"); #
3320         $imap->Uid(0);
3321
3322       Example 2:
3323
3324         my @uids;
3325         foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
3326             chomp $r;
3327             $r =~ s/\r$//;
3328             $r =~ s/^\*\s+SEARCH\s+// or next;
3329             push @uids, grep(/\d/,(split(/\s+/,$r)));
3330         }
3331
3332       In the second example, we used the default method to issue the UID IMAP
3333       client command, being careful to use an all-uppercase method name so as
3334       not to inadvertently call the "Uid" accessor method.  Then we parsed
3335       out the message UIDs manually, since we don't have the benefit of the
3336       built-in "search" method doing it for us.
3337
3338       Please be very careful when turning the "Uid" parameter on and off
3339       throughout a script.  If you loose track of whether you've got the
3340       "Uid" parameter turned on you might do something sad, like deleting the
3341       wrong message.  Remember, like all eponymous accessor methods, the Uid
3342       method without arguments will return the current value for the "Uid"
3343       parameter, so do yourself a favor and check.  The safest approach is
3344       probably to turn it on at the beginning (or just let it default to
3345       being on) and then leave it on.  (Remember that leaving it turned off
3346       can lead to problems if changes to a folder's contents cause
3347       resequencing.)
3348
3349       By default, the "Uid" parameter is turned on.
3350
3351   User
3352       Example:
3353
3354         $User = $imap->User();
3355         # or:
3356         $imap->User($userid);
3357
3358       Specifies the userid to use when logging into the IMAP service.  Can be
3359       supplied with the "new" method call or separately by calling the User
3360       object method.
3361
3362       Parameters can be set during "new" method invocation by passing named
3363       parameter/value pairs to the method, or later by calling the
3364       parameter's eponymous object method.
3365

Status Methods

3367       There are several object methods that return the status of the object.
3368       They can be used at any time to check the status of an IMAPClient
3369       object, but are particularly useful for determining the cause of
3370       failure when a connection and login are attempted as part of a single
3371       "new" method invocation.  The status methods are:
3372
3373   Escaped_history
3374       Example:
3375
3376         my @history = $imap->Escaped_history;
3377
3378       The Escaped_history method is almost identical to the History method.
3379       Unlike the History method, however, server output transmitted literally
3380       will be wrapped in double quotes, with all double quotes, backslashes
3381       escaped.  If called in a scalar context, Escaped_history returns an
3382       array reference rather than an array.
3383
3384       Escaped_history is useful if you are retrieving output and processing
3385       it manually, and you are depending on the above special characters to
3386       delimit the data.  It is not useful when retrieving message contents;
3387       use message_string or body_string for that.
3388
3389   Escaped_results
3390       Example:
3391
3392         my @results = $imap->Escaped_results;
3393
3394       The Escaped_results method is almost identical to the Results method.
3395       Unlike the Results method, however, server output transmitted literally
3396       will be wrapped in double quotes, with all double quotes, backslashes
3397       escaped.  If called in a scalar context, Escaped_results returns an
3398       array reference rather than an array.
3399
3400       Escaped_results is useful if you are retrieving output and processing
3401       it manually, and you are depending on the above special characters to
3402       delimit the data.  It is not useful when retrieving message contents;
3403       use message_string or body_string for that.
3404
3405   History
3406       Example:
3407
3408         my @history = $imap->History;
3409
3410       The History method is almost identical to the "Results" method.  Unlike
3411       the "Results" method, however, the IMAP command that was issued to
3412       create the results being returned is not included in the returned
3413       results.  If called in a scalar context, History returns an array
3414       reference rather than an array.
3415
3416   IsUnconnected
3417       returns a true value if the object is currently in an "Unconnected"
3418       state.
3419
3420   IsConnected
3421       returns a true value if the object is currently in either a
3422       "Connected", "Authenticated", or "Selected" state.
3423
3424   IsAuthenticated
3425       returns a true value if the object is currently in either an
3426       "Authenticated" or "Selected" state.
3427
3428   IsSelected
3429       returns a true value if the object is currently in a "Selected" state.
3430
3431   LastError
3432       Internally LastError is implemented just like a parameter (as described
3433       in "Parameters", above).  There is a LastError attribute and an
3434       eponymous accessor method which returns the LastError text string
3435       describing the last error condition encountered by the server.
3436
3437       Note that some errors are more serious than others, so LastError's
3438       value is only meaningful if you encounter an error condition that you
3439       don't like.  For example, if you use the "exists" method to see if a
3440       folder exists and the folder does not exist, then an error message will
3441       be recorded in LastError even though this is not a particularly serious
3442       error.  On the other hand, if you didn't use "exists" and just tried to
3443       "select" a non-existing folder, then "select" would return "undef"
3444       after setting LastError to something like "NO SELECT failed: Can't open
3445       mailbox "mailbox": no such mailbox".  At this point it would be useful
3446       to print out the contents of LastError as you die.
3447
3448   LastIMAPCommand
3449       New in version 2.0.4, LastIMAPCommand returns the exact IMAP command
3450       string to be sent to the server.  Useful mainly in constructing error
3451       messages when "LastError" just isn't enough.
3452
3453   Report
3454       The Report method returns an array containing a history of the IMAP
3455       session up to the point that Report was called.  It is primarily meant
3456       to assist in debugging but can also be used to retrieve raw output for
3457       manual parsing.  The value of the "Clear" parameter controls how many
3458       transactions are in the report.
3459
3460   Results
3461       The Results method returns an array containing the results of one IMAP
3462       client command.  It accepts one argument, the transaction number of the
3463       command whose results are to be returned.  If transaction number is
3464       unspecified then Results returns the results of the last IMAP client
3465       command issued.  If called in a scalar context, Results returns an
3466       array reference rather than an array.
3467
3468   State
3469       The State method returns a numerical value that indicates the current
3470       status of the IMAPClient object.  If invoked with an argument, it will
3471       set the object's state to that value.  If invoked without an argument,
3472       it behaves just like "Status", below.
3473
3474       Normally you will not have to invoke this function.  An exception is if
3475       you are bypassing the Mail::IMAPClient module's "connect" and/or
3476       "login" modules to set up your own connection (say, for example, over a
3477       secure socket), in which case you must manually do what the "connect"
3478       and "login" methods would otherwise do for you.
3479
3480   Status
3481       The Status method returns a numerical value that indicates the current
3482       status of the IMAPClient object.  (Not to be confused with the "status"
3483       method, all lower-case, which is the implementation of the STATUS IMAP
3484       client command.)
3485
3486   Transaction
3487       The Transaction method returns the tag value (or transaction number) of
3488       the last IMAP client command.
3489

Custom Authentication Mechanisms

3491       If you just want to use plain text authentication or any of the
3492       supported "Advanced Authentication Mechanisms" then there is no need to
3493       read this section.
3494
3495       There are a number of methods and parameters that you can use to build
3496       your own authentication mechanism.  All of the methods and parameters
3497       discussed in this section are described in more detail elsewhere in
3498       this document.  This section provides a starting point for building
3499       your own authentication mechanism.
3500
3501       There are many authentication mechanisms out there, if your preferred
3502       mechanism is not currently supported but you manage to get it working
3503       please consider donating them to this module.  Patches and suggestions
3504       are always welcome.
3505
3506       Support for add-on authentication mechanisms in Mail::IMAPClient is
3507       pretty straight forward.  You create a callback to be used to provide
3508       the response to the server's challenge.  The "Authcallback" parameter
3509       contains a reference to the callback, which can be an anonymous
3510       subroutine or a named subroutine.  Then, you identify your
3511       authentication mechanism, either via the "Authmechanism" parameter or
3512       as an argument to "authenticate".
3513
3514       You may also need to provide a subroutine to encrypt (or whatever) data
3515       before it is sent to the server.  The "Prewritemethod" parameter must
3516       contain a reference to this subroutine.  And, you will need to decrypt
3517       data from the server; a reference to the subroutine that does this must
3518       be stored in the "Readmethod" parameter.
3519
3520       This framework is based on the assumptions that a) the mechanism you
3521       are using requires a challenge-response exchange, and b) the mechanism
3522       does not fundamentally alter the exchange between client and server but
3523       merely wraps the exchange in a layer of encryption.  It also assumes
3524       that the line-oriented nature of the IMAP conversation is preserved;
3525       authentication mechanisms that break up messages into blocks of a
3526       predetermined size may still be possible but will certainly be more
3527       difficult to implement.
3528
3529       Alternatively, if you have access to imtest, a utility included in the
3530       Cyrus IMAP distribution, you can use that utility to broker your
3531       communications with the IMAP server.  This is quite easy to implement.
3532       An example, examples/imtestExample.pl, can be found in the "examples"
3533       subdirectory of the source distribution.
3534
3535       The following list summarizes the methods and parameters that you may
3536       find useful in implementing advanced authentication:
3537
3538       The authenticate method
3539           The "authenticate" method uses the "Authmechanism" parameter to
3540           determine how to authenticate with the server see the method
3541           documentation for details.
3542
3543       Socket and RawSocket
3544           The "Socket" and "RawSocket" methods provide access to the socket
3545           connection.  The socket is typically automatically created by the
3546           "connect" method, but if you are implementing an advanced
3547           authentication technique you may choose to set up your own socket
3548           connection and then set this parameter manually, bypassing the
3549           connect method completely.  This is also useful if you want to use
3550           IO::Socket::(INET|IP) alternatives like IO::Socket::SSL and need
3551           full control.
3552
3553           "RawSocket" simply gets/sets the socket without attempting any
3554           interaction on it.  In this case, you have to be sure to handle all
3555           the preliminary operations and manually set the Mail::IMAPClient
3556           object in sync with its actual status with respect to this socket
3557           (see below for additional parameters regarding this, especially the
3558           "State" parameter).
3559
3560           Unlike "RawSocket", "Socket" attempts to carry on preliminary
3561           connection phases if the conditions apply.  If both parameters are
3562           present, this takes the precedence over "RawSocket".  If "Starttls"
3563           is set, then the "starttls" method will be called by "Socket".
3564
3565           PLEASE NOTE As of version 2.99_04 of this module, semantics for
3566           "Socket" have changed to make it more "DWIM".  "RawSocket" was
3567           introduced as a replacement for the "Socket" parameter in older
3568           version.
3569
3570       State, Server, User, Password, Proxy and Domain Parameters
3571           If you need to make your own connection to the server and perform
3572           your authentication manually, then you can set these parameters to
3573           keep your Mail::IMAPClient object in sync with its actual status.
3574           Of these, only the "State" parameter is always necessary.  The
3575           others need to be set only if you think your program will need them
3576           later.
3577
3578       Authmechanism
3579           Set this to the value that AUTHENTICATE should send to the server
3580           as the authentication mechanism.  If you are brokering your own
3581           authentication then this parameter may be less useful.  It exists
3582           primarily so that you can set it when you call "new" to instantiate
3583           your object.  The "new" method will call "connect", which will call
3584           "login".  If "login" sees that you have set an Authmechanism then
3585           it will call authenticate, using your Authmechanism and
3586           Authcallback parameters as arguments.
3587
3588       Authcallback
3589           The "Authcallback", if set, holds a pointer to a subroutine
3590           (CODEREF).  The "login" method will use this as the callback
3591           argument to the authenticate method if the Authmechanism and
3592           Authcallback parameters are both set.  If you set Authmechanism but
3593           not Authcallback then the default callback for your mechanism will
3594           be used.  All supported authentication mechanisms have a default
3595           callback; in every other case not supplying the callback results in
3596           an error.
3597
3598           Most advanced authentication mechanisms require a challenge-
3599           response exchange.  After the "authenticate" method sends "<tag>
3600           AUTHENTICATE <Authmechanism>\015\012" to the IMAP server, the
3601           server replies with a challenge.  The "authenticate" method then
3602           invokes the code whose reference is stored in the Authcallback
3603           parameter as follows:
3604
3605             $Authcallback->( $challenge, $imap )
3606
3607           where $Authcallback is the code reference stored in the
3608           Authcallback parameter, $challenge is the challenge received from
3609           the IMAP server, and $imap is a pointer to the Mail::IMAPClient
3610           object.  The return value from the Authcallback routine should be
3611           the response to the challenge, and that return value will be sent
3612           by the "authenticate" method to the server.
3613
3614       Prewritemethod/Readmethod
3615           The Prewritemethod can hold a subroutine that will do whatever
3616           encryption is necessary and then return the result to the caller so
3617           it in turn can be sent to the server.
3618
3619           The Readmethod can hold a subroutine to be used to replace sysread
3620           usually performed by Mail::IMAPClient.
3621
3622           See "Prewritemethod" and "Readmethod" for details.
3623

REPORTING BUGS

3625       Please file bug reports via
3626       https://github.com/plobbes/mail-imapclient/issues
3627
3629         Copyright (C) 1999-2003 The Kernen Group, Inc.
3630         Copyright (C) 2007-2009 Mark Overmeer
3631         Copyright (C) 2010-2021 Phil Pearl (Lobbes)
3632         All rights reserved.
3633
3634       This library is free software; you can redistribute it and/or modify it
3635       under the same terms as Perl itself, either Perl version 5.8.0 or, at
3636       your option, any later version of Perl 5 you may have available.
3637
3638       This program is distributed in the hope that it will be useful, but
3639       WITHOUT ANY WARRANTY; without even the implied warranty of
3640       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
3641       GNU General Public License or the Artistic License for more details.
3642
3643
3644
3645perl v5.34.0                      2021-07-22               Mail::IMAPClient(3)
Impressum