1Mail::IMAPClient(3) User Contributed Perl Documentation Mail::IMAPClient(3)
2
6 Mail::IMAPClient - An IMAP Client API
7
9 use Mail::IMAPClient;
10 my $imap = Mail::IMAPClient->new(
12 Server => 'localhost',
13 User => 'username',
14 Password => 'password',
15 Ssl => 1,
16 Uid => 1,
17 );
18 my $folders = $imap->folders
20 or die "List folders error: ", $imap->LastError, "\n";
21 print "Folders: @$folders\n";
22 $imap->select( $Opt{folder} )
24 or die "Select '$Opt{folder}' error: ", $imap->LastError, "\n";
25 $imap->fetch_hash("FLAGS", "INTERNALDATE", "RFC822.SIZE")
27 or die "Fetch hash '$Opt{folder}' error: ", $imap->LastError, "\n";
28 $imap->logout
30 or die "Logout error: ", $imap->LastError, "\n";
31
33 This module provides methods implementing the IMAP protocol to support
34 interacting with IMAP message stores.
35 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 This documentation is not meant to be a replacement for RFC3501 nor any
44 other IMAP related RFCs.
45 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 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 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 Advanced Authentication Mechanisms
66 RFC3501 defines two commands for authenticating to an IMAP server:
67 LOGIN
69 LOGIN is for plain text authentication.
70 AUTHENTICATE
72 AUTHENTICATE for more advanced and/or secure authentication
73 mechanisms.
74 Mail::IMAPClient supports the following AUTHENTICATE mechanisms:
76 DIGEST-MD5
78 DIGEST-MD5 authentication requires the Authen::SASL and Digest::MD5
79 modules. See also "Authuser".
80 CRAM-MD5
82 CRAM-MD5 requires the Digest::HMAC_MD5 module.
83 PLAIN (SASL)
85 PLAIN (SASL) authentication allows the optional use of the "Proxy"
86 parameter. RFC 4616 documents this syntax for SASL PLAIN:
87 message = [authzid] UTF8NUL authcid UTF8NUL passwd
89 When "Proxy" is defined, "User" is used as 'authzid' and "Proxy" is
91 used as 'authcid'. Otherwise, "User" is used as 'authcid'.
92 NTLM
94 NTLM authentication requires the Authen::NTLM module. See also
95 "Domain".
96 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 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 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 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 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 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 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 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 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
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 new
160 Example:
161 my $imap = Mail::IMAPClient->new(%args)
163 or die "new failed: $@\n";
164 The "new" method creates a new instance of an IMAPClient object.
166 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 If the "Server" parameter is not supplied then the IMAPClient object is
174 created in the Unconnected state.
175 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 Here are some examples:
181 use Mail::IMAPClient;
183 # 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 See also "Parameters", "connect" and "login" for more information on
198 how to manually connect and login after new.
199 Quote
201 Example:
202 $imap->search( HEADER => 'Message-id' => \$imap->Quote($msg_id) );
204 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 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 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 ( argument )
223 and the argument is (or might be) "pennies (from heaven)", then one
225 could use:
226 $argument = "(" . $imap->Quote($argument) . ")"
228 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 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 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 Range
243 Example:
244 my $parsed = $imap->parse_headers(
246 $imap->Range( $imap->messages ), "Date", "Subject"
247 );
248 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 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 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 This method provides an easy way to add or remove messages from a
267 message set.
268 For more information see Mail::IMAPClient::MessageSet.
270 Rfc3501_date
272 Example:
273 $Rfc3501_date = $imap->Rfc3501_date($seconds);
275 # or:
276 $Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);
277 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 Rfc3501_datetime
284 Example:
285 $date = $imap->Rfc3501_datetime($seconds);
287 # or:
288 $date = Mail::IMAPClient->Rfc3501_datetime($seconds);
289 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 Rfc822_date
298 Example:
299 $Rfc822_date = $imap->Rfc822_date($seconds);
301 # or:
302 $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
303 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 Strip_cr
310 Examples:
311 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 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 NOTE: Strip_cr does not remove new line characters.
331
333 Object methods must be invoked against objects created via the "new"
334 method and cannot be invoked as class methods.
335 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 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 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 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 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
371 append
372 Example:
373 my $uid_or_true = $imap->append( $folder, $msgtext )
375 or die "Could not append: ", $imap->LastError;
376 WARNING: This method may be deprecated in the future, consider using
378 "append_string" instead of this method.
379 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 DEPRECATED BEHAVIOR: Additional arguments are added to the message
385 text, separated with <CR><LF>.
386 append_string
388 Example:
389 # 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 Arguments:
395 $folder
397 the name of the folder to append the message to
398 $msgtext
400 the message text (including headers) of the message
401 $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 $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 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 Returns:
416 error: undef
418 On error, undef can be returned regardless of LIST/SCALAR context.
419 Check "LastError" for details.
420 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 To protect against "bare newlines", append will insert a carriage
426 return before any newline that is "bare".
427 append_file
429 Example:
430 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 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 Arguments:
442 $folder
444 the name of the folder to append the message to
445 $file
447 a filename, filehandle or SCALAR reference which holds an
448 RFC822-formatted message
449 undef
451 a deprecated argument used as a place holder for backwards
452 compatibility
453 $flags
455 The optional argument is handled the same as append_string.
456 $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 Returns:
463 error: undef
465 On error, undef can be returned regardless of LIST/SCALAR context.
466 Check "LastError" for details.
467 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 To protect against "bare newlines", append_file will insert a carriage
473 return before any newline that is "bare".
474 The append_file method provides a mechanism for allowing large messages
476 to be appended without holding the whole file in memory.
477 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 authenticate
483 Example:
484 $imap->authenticate( $authentication_mechanism, $coderef )
486 or die "Could not authenticate: ", $imap->LastError;
487 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 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 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 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 See also the "login" method, which is the simplest form of
516 authentication defined by RFC3501.
517 before
519 Example:
520 my @msgs = $imap->before($Rfc3501_date)
522 or warn "No messages found before $Rfc3501_date.\n";
523 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 body_string
529 Example:
530 my $string = $imap->body_string($msgId)
532 or die "body_string failed: ", $imap->LastError;
533 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 bodypart_string
540 Example:
541 my $string = $imap->bodypart_string(
543 $msgid, $part_number, $length, $offset
544 ) or die "Could not get bodypart string: ", $imap->LastError;
545 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 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 If you specify an offset without specifying a length then the offset
559 will be ignored and the entire part will be returned.
560 bodypart_string will return "undef" if it encounters an error.
562 capability
564 Example:
565 my $features = $imap->capability
567 or die "Could not determine capability: ", $imap->LastError;
568 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 See also "has_capability".
577 close
579 Example:
580 $imap->close or die "Could not close: $@\n";
582 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 Note: this closes the currently selected folder, not the IMAP session.
591 See also "delete_message", "expunge", and RFC3501.
593 compress
595 Example:
596 $imap->compress or die "Could not enable RFC4978 compression: $@\n";
598 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 Version note: method added in Mail::IMAPClient 3.30
605 connect
607 Example:
608 $imap->connect or die "Could not connect: $@\n";
610 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 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 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 copy
630 Example:
631 # Here brackets indicate optional arguments:
633 my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
634 or die "Could not copy: $@\n";
635 Or:
637 # Now brackets indicate an array ref!
639 my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
640 or die "Could not copy: $@\n";
641 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 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 create
656 Example:
657 $imap->create($new_folder)
659 or die "Could not create $new_folder: $@\n";
660 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 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 create returns a true value on success and "undef" on failure.
673 date
675 Example:
676 my $date = $imap->date($msg);
678 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 The date method is a short-cut for:
685 my $date = $imap->get_header($msg,"Date");
687 delete
689 Example:
690 $imap->delete($folder) or die "Could not delete $folder: $@\n";
692 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 deleteacl
697 Example:
698 $imap->deleteacl( $folder, $userid )
700 or die "Could not delete acl: $@\n";
701 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 delete_message
708 Example:
709 my @msgs = $imap->seen;
711 scalar(@msgs) and $imap->delete_message(\@msgs)
712 or die "Could not delete_message: $@\n";
713 The above could also be rewritten like this:
715 # scalar context returns array ref
717 my $msgs = scalar($imap->seen);
718 scalar(@$msgs) and $imap->delete_message($msgs)
720 or die "Could not delete_message: $@\n";
721 Or, as a one-liner:
723 $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 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 • a message sequence number,
734 • a comma-separated list of message sequence numbers,
736 • a reference to an array of message sequence numbers, or
738 If the "Uid" parameter is set to a true value, then each item in the
740 list should be either:
741 • a message UID,
743 • a comma-separated list of UID's, or
745 • a reference to an array of message UID's.
747 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 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 Eg:
765 $imap->store( $msg_id, '+FLAGS (\Deleted)' );
767 my @results = $imap->History( $imap->Transaction );
768 ... # code to parse output goes here
769 (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 The IMAPClient object must be in "Selected" status to use the
776 delete_message method.
777 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 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 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 deny_seeing
796 Example:
797 # 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 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 Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
811 specifying "$imap->unset_flag("Seen",@msgs)".
812 disconnect
814 Example:
815 $imap->disconnect or warn "Could not logout: $@\n";
817 This method calls "logout", see "logout" for details.
819 done
821 Example:
822 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 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 If an invalid tag is specified, or the default tag is wrong, then done
836 will hang indefinitely or until a timeout occurs.
837 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 On failure <undef> is returned and "LastError" is set.
842 See also "idle", "idle_data" and "Results".
844 examine
846 Example:
847 $imap->examine($folder) or die "Could not examine: $@\n";
849 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 The examine method accepts one argument, which is the name of the
856 folder to select.
857 exists
859 Example:
860 $imap->exists($folder) or warn "$folder not found: $@\n";
862 Accepts one argument, a folder name. Returns true if the folder exists
864 or false if it does not exist.
865 expunge
867 Example:
868 $imap->expunge($folder) or die "Could not expunge: $@\n";
870 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 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 See also the "close" method, which "deselects" as well as expunges.
881 fetch
883 Usage:
884 $imap->fetch( [$seq_set|ALL], @msg_data_items )
886 Example:
888 my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
890 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 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 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 fetch returns "undef" on failure. Inspect "LastError" or $@ for an
912 explanation of your error.
913 fetch_hash
915 Usage:
916 $imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
918 Examples:
920 my $hashref = $imap->fetch_hash("RFC822.SIZE");
922 OR
924 my $hashref = {};
926 $imap->fetch_hash( "RFC822.SIZE", $hashref );
927 print "Msg #$_ is $hashref->{$_}->{'RFC822.SIZE'} bytes\n" for (keys %$hashref);
928 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 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 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 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 This would result in Data::Dumper output similar to the following:
959 $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 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 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 flags
985 Example:
986 my $flags = $imap->flags($msgid)
988 or die "flags failed: $@\n";
989 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 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 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 use Mail::IMAPClient;
1011 my $imap = Mail::IMAPClient->new(
1012 Server => $imaphost,
1013 User => $login,
1014 Password => $pass,
1015 Uid => 1, # optional
1016 );
1017 $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 # 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 folders
1029 Example:
1030 $imap->folders or die "Could not list folders: $@\n";
1032 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 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 For example:
1042 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 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 folders_hash
1061 my @fhashes = $imap->folders_hash
1062 or die "Could not get list of folder hashes.\n";
1063 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 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 {
1073 name => 'Mail/Box/Name',
1074 attrs => [ '\Marked', '\HasNoChildren' ],
1075 delim => '/',
1076 }
1077 IMAP servers implementing RFC6154 return attributes to be used to
1079 identify special-use mailboxes (folders).
1080 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 Version note: method added in Mail::IMAPClient 3.34
1089 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 Example:
1096 my $xlist = $imap->xlist_folders
1098 or die "Could not get xlist folders.\n";
1099 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 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 $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 The same list for a user using the French locale might look like this:
1123 $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 Mail::IMAPClient recognizes the following "xlist" folder names:
1135 Inbox
1137 AllMail
1138 Trash
1139 Drafts
1140 Sent
1141 Spam
1142 Starred
1143 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 If the server does not support the XLIST extension, this method returns
1150 undef.
1151 Version note: method added in Mail::IMAPClient 3.21
1153 has_capability
1155 Example:
1156 my $has_feature = $imap->has_capability($feature)
1158 or die "Could not do has_capability($feature): $@\n";
1159 Returns:
1161 "undef"
1163 If the underlying "capability" calls fails then "undef" is
1164 returned.
1165 "" 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 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 * CAPABILITY IMAP4rev1 SORT SORT=DISPLAY I18NLEVEL=1 AUTH=PLAIN AUTH=XTEST
1180 Results are returned as shown by the trailing comments:
1182 $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 idle
1197 Example:
1198 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 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 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 On failure <undef> is returned and "LastError" is set.
1215 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 See also "idle_data" and "done".
1222 idle_data
1224 Usage:
1225 # an optional timeout in seconds may be specified
1227 $imap->idle_data( [$timeout] )
1228 Example:
1230 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 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 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 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 On failure <undef> is returned and "LastError" is set.
1253 See also "imap" and "done".
1255 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 imap4rev1
1261 Example:
1262 $imap->imap4rev1 or die "Could not imap4rev1: $@\n";
1264 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 internaldate
1271 Example:
1272 my $msg_internal_date = $imap->internaldate($msgid)
1274 or die "internaldate failed: $@\n";
1275 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 get_bodystructure
1281 Example:
1282 my $bodyStructObject = $imap->get_bodystructure($msgid)
1284 or die "Could not get_bodystructure: $@\n";
1285 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 get_envelope
1292 Example:
1293 my $envObject = $imap->get_envelope(@args)
1295 or die "Could not get_envelope: $@\n";
1296 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 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 getacl
1309 Example:
1310 my $hash = $imap->getacl($folder)
1312 or die "Could not getacl for $folder: $@\n";
1313 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 get_header
1323 Example:
1324 my $messageId = $imap->get_header( $msg, "Message-Id" );
1326 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 The get_header method is a short-cut for:
1337 my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
1339 getquotaroot
1341 Example:
1342 my $results = $imap->getquotaroot($mailboxname)
1344 or die "Could not getquotaroot for $mailboxname: $@\n";
1345 The getquotaroot method implements the RFC2087 GETQUOTAROOT command.
1347 The "$mailboxname" defaults to "INBOX" if no argument is provided.
1348 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 See also RFC2087, "getquota", "setquota", "quota" and "quota_usage".
1355 getquota
1357 Example:
1358 my $results = $imap->getquota($quotaroot)
1360 or die "Could not getquota for $quotaroot: $@\n";
1361 The getquota method implements the RFC2087 GETQUOTA command. The
1363 "$quotaroot" defaults to "user/User" if no argument is provided.
1364 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 See also RFC2087, "getquotaroot", "quota" and "quota_usage".
1370 quota
1372 Example:
1373 my $limit = $imap->quota($quotaroot)
1375 or die "Could not get quota limit for $quotaroot: $@\n";
1376 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 On error "undef" is returned, otherwise the integer "STORAGE" limit
1382 provided by the server is returned.
1383 See also RFC2087, "getquotaroot", "getquota" and "quota_usage".
1385 quota_usage
1387 Example:
1388 my $usage = $imap->quota_usage($quotaroot)
1390 or die "Could not get quota usage for $quotaroot: $@\n";
1391 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 On error "undef" is returned, otherwise the integer "STORAGE" usage
1397 provided by the server is returned.
1398 See also RFC2087, "getquotaroot", "getquota" and "quota".
1400 setquota
1402 Example:
1403 my $results = $imap->setquota( $quotaroot, $resource, $limit )
1405 or die "Could not setquota for $quotaroot: $@\n";
1406 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 On error "undef" is returned, otherwise "Results" are returned.
1412 See also RFC2087, "getquotaroot" and "getquota".
1414 is_parent
1416 Example:
1417 my $hasKids = $imap->is_parent($folder);
1419 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 1 (or a positive integer)
1425 The "\HasChildren" attribute is set, indicating that the folder has
1426 children.
1427 0 (zero)
1429 The "\HasNoChildren" attribute is set, indicating that the folder
1430 has no children at this time.
1431 "undef"
1433 The "\NoInferiors" attribute is set, indicating the folder is not
1434 permitted to have children.
1435 Eg:
1437 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 list
1452 Example:
1453 my @raw_output = $imap->list(@args)
1455 or die "Could not list: $@\n";
1456 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 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 An "undef" value is returned in case of errors. Be sure to check for
1468 it.
1469 listrights
1471 Example:
1472 $imap->listrights( $folder, $user )
1474 or die "Could not listrights: $@\n";
1475 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 login
1485 Example:
1486 $imap->login or die "Could not login: $@\n";
1488 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 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 If the "Compress" parameter is set, the "compress" method will
1501 automatically be called after successful authentication.
1502 See also "proxyauth" and "Proxy" for additional information regarding
1504 ways of authenticating with a server via SASL and/or PROXYAUTH.
1505 proxyauth
1507 Example:
1508 $imap->login( "admin", "password" );
1510 $imap->proxyauth("someuser");
1511 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 logout
1517 Example:
1518 $imap->logout or die "Could not logout: $@\n";
1520 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 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 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 lsub
1539 Example:
1540 $imap->lsub(@args) or die "Could not lsub: $@\n";
1542 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 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 mark
1554 Example:
1555 $imap->mark(@msgs) or die "Could not mark: $@\n";
1557 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 Note that specifying "$imap->see(@msgs)" is just a shortcut for
1566 specifying "$imap->set_flag("Flagged",@msgs)".
1567 Massage
1569 Example:
1570 $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
1572 WARNING: This method may be deprecated in the future, consider using
1574 "Quote" instead of this method.
1575 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 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 It returns its argument as a correctly quoted string or a literal
1585 string.
1586 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 message_count
1591 Example:
1592 my $msgcount = $imap->message_count($folder);
1594 defined($msgcount) or die "message_count failed: $@\n";
1595 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 message_string
1613 Example:
1614 my $string = $imap->message_string($msgid)
1616 or die "message_string failed: $@\n";
1617 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 message_to_file
1626 Example:
1627 $imap->message_to_file( $file, @msgs )
1629 or die "message_to_file failed: $@\n";
1630 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 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 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 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 message_uid
1653 Example:
1654 my $msg_uid = $imap->message_uid($msg_seq_no)
1656 or die "Could not get uid for $msg_seq_no: $@\n";
1657 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 messages
1665 Example:
1666 # 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 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 An empty list is returned when no messages are found. On failure
1679 <undef> is returned and "LastError" is set.
1680 migrate
1682 Example:
1683 $imap_src->migrate( $imap_dest, "ALL", $targetFolder )
1685 or die "Could not migrate: ", $imap_src->LastError;
1686 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 1. a reference to the target Mail::IMAPClient object (not the calling
1692 object, which is connected to the source account);
1693 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 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 The target ($imap_dest) Mail::IMAPClient object must not be the same
1707 object as the source ($imap_src).
1708 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 To work around potential network timeouts on large messages, consider
1714 setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
1715 See also "Supportedflags".
1717 move
1719 Example:
1720 my $newUid = $imap->move( $newFolder, $oldUid )
1722 or die "Could not move: $@\n";
1723 $imap->expunge;
1724 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 a) a message sequence number,
1730 b) a comma-separated list of message sequence numbers, or
1732 c) a reference to an array of message sequence numbers.
1734 If the "Uid" parameter is true, then the arguments should be:
1736 a) a message UID,
1738 b) a comma-separated list of message UID's, or
1740 c) a reference to an array of message UID's.
1742 If the target folder does not exist then it will be created.
1744 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 If the move is not successful then move returns "undef".
1753 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 namespace
1759 Example:
1760 my $refs = $imap->namespace
1762 or die "namespace failed: $@\n";
1763 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 [
1769 [ $prefix_1, $separator_1 ],
1770 [ $prefix_2, $separator_2 ],
1771 [ $prefix_n, $separator_n ],
1772 ]
1773 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 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 [ [ "", "/" ] , undef, [ "#news", "." ] ];
1787 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 $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 on
1812 Example:
1813 my @msgs = $imap->on($Rfc3501_date)
1815 or warn "Could not find messages sent on $Rfc3501_date: $@\n";
1816 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 parse_headers
1822 Example:
1823 my $hashref = $imap->parse_headers( $msg || \@msgs, "Date", "Subject" )
1825 or die "Could not parse_headers: $@\n";
1826 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 A picture would look something like this:
1834 $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 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 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 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 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 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 use Mail::IMAPClient;
1884 my $imap = Mail::IMAPClient->new(
1885 Server => $imaphost, User => $login, Password => $pass, Uid => 1
1886 );
1887 $imap->select("demo");
1889 my $msgs = $imap->search("ALL");
1891 for my $h (
1892 # 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 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 recent
1911 Example:
1912 my @recent = $imap->recent or warn "No recent msgs: $@\n";
1914 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 recent_count
1920 Example:
1921 my $count = 0;
1923 defined($count = $imap->recent_count($folder))
1924 or die "recent_count failed: $@\n";
1925 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 noop
1933 Example:
1934 $imap->noop or die "noop failed: $@\n";
1936 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 reconnect
1946 Example:
1947 $imap->noop or $imap->reconnect or die "noop failed: $@\n";
1949 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 Version note: method added in Mail::IMAPClient 3.17
1957 rename
1959 Example:
1960 $imap->rename( $oldname, $nedwname )
1962 or die "rename failed: $@\n";
1963 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 restore_message
1970 Example:
1971 $imap->restore_message(@msgs) or die "restore_message failed: $@\n";
1973 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 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 > a message sequence number,
1984 > a comma-separated list of message sequence numbers,
1986 > a reference to an array of message sequence numbers, or
1988 If the "Uid" parameter is set to a true value, then each item in the
1990 list should be either:
1991 > a message UID,
1993 > a comma-separated list of UID's, or
1995 > a reference to an array of message UID's.
1997 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 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 run
2007 Example:
2008 $imap->run(@args) or die "run failed: $@\n";
2010 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 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 The run method does not do any syntax checking, other than rudimentary
2023 checking for a tag.
2024 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 If you want the control of run but you don't want to worry about tags
2033 then see "tag_and_run", below.
2034 search
2036 Example:
2037 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 # 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 # 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 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 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 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 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 • specify a single string/argument in the call to search.
2074 • specify args as scalar references (SCALAR) and the values of those
2076 SCALAR refs will be passed along as-is.
2077 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 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 see
2095 Example:
2096 $imap->see(@msgs) or die "see failed: $@\n";
2098 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 Note that specifying "$imap->see(@msgs)" is just a shortcut for
2107 specifying "$imap->"set_flag"("Seen",@msgs)".
2108 seen
2110 Example:
2111 my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
2113 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 select
2122 Example:
2123 $imap->select($folder) or die "select failed: $@\n";
2125 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 selectable
2131 Example:
2132 foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
2134 $imap->select($f);
2135 }
2136 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 sentbefore
2141 Example:
2142 my @msgs = $imap->sentbefore($Rfc3501_date)
2144 or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
2145 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 senton
2151 Example:
2152 my @msgs = $imap->senton($Rfc3501_date)
2154 or warn "Could not find any messages sent on $Rfc3501_date: $@\n";
2155 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 sentsince
2161 Example:
2162 my @msgs = $imap->sentsince($Rfc3501_date)
2164 or warn "Could not find any messages sent since $Rfc3501_date: $@\n";
2165 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 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 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 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 separator
2193 Example:
2194 my $sepChar = $imap->separator(@args)
2196 or die "Could not get separator: $@\n";
2197 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 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 set_flag
2215 Example:
2216 $imap->set_flag( "Seen", @msgs )
2218 or die "Could not set flag: $@\n";
2219 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 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 setacl
2237 Example:
2238 $imap->setacl( $folder, $userid, $aclstring )
2240 or die "Could not set acl: $@\n";
2241 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 since
2249 Example:
2250 my @msgs = $imap->since($date)
2252 or warn "Could not find any messages since $date: $@\n";
2253 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 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 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 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 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 size
2283 Example:
2284 my $size = $imap->size($msgId)
2286 or die "Could not find size of message $msgId: $@\n";
2287 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 sort
2295 Example:
2296 my @msgs = $imap->sort(@args);
2298 warn "Error in sort: $@\n" if $@;
2299 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 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 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 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 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 The sort method will clear $@ before attempting the SORT operation just
2340 as the "search" method does.
2341 starttls
2343 Example:
2344 $imap->starttls() or die "starttls failed: $@\n";
2346 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 Version note: method added in Mail::IMAPClient 3.22
2357 status
2359 Example:
2360 my @rawdata = $imap->status( $folder, qw/(Messages)/ )
2362 or die "Error obtaining status: $@\n";
2363 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 If status is not called in an array context then it returns a reference
2372 to an array rather than the array itself.
2373 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 store
2379 Example:
2380 $imap->store(@args) or die "Could not store: $@\n";
2382 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 subject
2399 Example:
2400 my $subject = $imap->subject($msg);
2402 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 my $subject = $imap->get_header($msg, "Subject");
2409 subscribed
2411 Example:
2412 my @subscribedFolders = $imap->subscribed
2414 or warn "Could not find subscribed folders: $@\n";
2415 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 Like "folders", you can optionally provide a prefix argument to the
2421 subscribed method.
2422 tag_and_run
2424 Example:
2425 my $output = $imap->tag_and_run(@args)
2427 or die "Could not tag_and_run: $@\n";
2428 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 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 uidexpunge
2443 Example:
2444 $imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";
2446 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 uidexpunge returns an array or arrayref (scalar context) of output
2452 lines returned from the UID EXPUNGE command.
2453 uidexpunge returns undef on failure.
2455 If the server does not support the UIDPLUS extension, this method
2457 returns undef.
2458 uidnext
2460 Example:
2461 my $nextUid = $imap->uidnext($folder) or die "uidnext failed: $@\n";
2463 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 thread
2469 Example:
2470 my $thread = $imap->thread( $algorithm, $charset, @search_args );
2472 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 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 If the character set is not specified it will default to UTF-8.
2483 If the search arguments are not specified, the default is ALL.
2485 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 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 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 uidvalidity
2500 Example:
2501 my $validity = $imap->uidvalidity($folder)
2503 or die "uidvalidity failed: $@\n";
2504 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 unmark
2510 Example:
2511 $imap->unmark(@msgs) or die "Could not unmark: $@\n";
2513 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 Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
2522 specifying "$imap->unset_flag("Flagged",@msgs)".
2523 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 unseen
2532 Example:
2533 my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
2535 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 unseen_count
2544 Example:
2545 foreach my $f ($imap->folders) {
2547 print "The $f folder has ",
2548 $imap->unseen_count($f)||0, " unseen messages.\n";
2549 }
2550 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 unset_flag
2557 Example:
2558 $imap->unset_flag( "\Seen", @msgs )
2560 or die "unset_flag failed: $@\n";
2561 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
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 copy($msg, $folder)
2580 Copy a message from the currently selected folder in the folder whose
2581 name is in $folder
2582 subscribe($folder)
2584 Subscribe to a folder
2585 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 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 my @raw = $imap->SEARCH("SUBJECT","Whatever...");
2598 which is slightly more efficient than the equivalent:
2600 $imap->search("SUBJECT","Whatever...");
2602 my @raw = $imap->Results;
2603 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
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 my $imap = Mail::IMAPClient->new ( parameter => "value",
2614 parameter2 => "value",
2615 ...
2616 );
2617 Parameters can also be set after an object has been instantiated by
2619 using the parameter's eponymous accessor method like this:
2620 my $imap = Mail::IMAPClient->new;
2622 $imap->parameter( "value");
2623 $imap->parameter2("value");
2624 The eponymous accessor methods can also be used without arguments to
2626 obtain the current value of the parameter as follows:
2627 my $imap = Mail::IMAPClient->new;
2629 $imap->parameter( "value");
2630 $imap->parameter2("value");
2631 ... # A whole bunch of awesome Perl code, omitted for brevity
2633 my $forgot = $imap->parameter;
2635 my $forgot2 = $imap->parameter2;
2636 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 Authmechanism
2643 Example:
2644 $imap->Authmechanism("CRAM-MD5");
2646 # or
2647 my $authmech = $imap->Authmechanism();
2648 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 my $authmech = "CRAM-MD5";
2657 $imap->has_capability($authmech) and $imap->Authmechanism($authmech);
2658 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 my $imap = Mail::IMAPClient->new(
2664 User => $user,
2665 Passord => $passord,
2666 Server => $server,
2667 Authmechanism => $authmech,
2668 %etc
2669 );
2670 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 Authcallback
2676 Example:
2677 $imap->Authcallback( \&callback );
2679 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 $imap->authenticate($imap->Authmechanism,$imap->Authcallback);
2686 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 Authuser
2692 The Authuser parameter is used by the DIGEST-MD5 "Authmechanism".
2693 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 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 Buffer
2703 Example:
2704 $Buffer = $imap->Buffer();
2706 # or:
2707 $imap->Buffer($new_value);
2708 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 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 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 Clear
2728 Example:
2729 $Clear = $imap->Clear();
2731 # or:
2732 $imap->Clear($integer);
2733 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 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 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 The default Clear value is set to five (5) in order to conserve memory.
2755 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 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 See also "compress" and "capability".
2768 Version note: attribute added in Mail::IMAPClient 3.30
2770 Debug
2772 Example:
2773 $Debug = $imap->Debug();
2775 # or:
2776 $imap->Debug($true_or_false);
2777 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 Debug_fh
2784 Example:
2785 $Debug_fh = $imap->Debug_fh();
2787 # or:
2788 $imap->Debug_fh($fileHandle);
2789 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 For example, you can:
2795 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 which is the same as:
2806 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 You can also:
2820 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 Specifying this parameter is not very useful unless "Debug" is set to a
2830 true value.
2831 Domain
2833 The Domain parameter is used by the NTLM "Authmechanism". The domain
2834 is an optional parameter for NTLM authentication.
2835 EnableServerResponseInLiteral
2837 Removed in 2.99_01 (now autodetect)
2838 Fast_io
2840 Example:
2841 $Fast_io = $imap->Fast_io();
2843 # or:
2844 $imap->Fast_io($true_or_false);
2845 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 See also "Buffer".
2852 Folder
2854 Example:
2855 $Folder = $imap->Folder();
2857 # or:
2858 $imap->Folder($new_value);
2859 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 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 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 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 Version note: attribute added in Mail::IMAPClient 3.17
2886 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 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 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 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 Version note: attribute added in Mail::IMAPClient 3.17
2905 Maxtemperrors
2907 Example:
2908 $Maxtemperrors = $imap->Maxtemperrors();
2910 # or:
2911 $imap->Maxtemperrors($number);
2912 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 Setting this parameter to the string "unlimited" (instead of undef) to
2919 ignore "Resource Temporarily Unavailable" errors is deprecated.
2920 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 Password
2928 Example:
2929 $Password = $imap->Password();
2931 # or:
2932 $imap->Password($new_value);
2933 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 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 Peek
2947 Example:
2948 $Peek = $imap->Peek();
2950 # or:
2951 $imap->Peek($true_or_false);
2952 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 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 Port
2965 Example:
2966 $Port = $imap->Port();
2968 # or:
2969 $imap->Port($new_value);
2970 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 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 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 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 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 See also "Readmethod".
2999 Ranges
3001 Example:
3002 $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 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 This parameter has no affect on the search method when search is called
3019 in a list context.
3020 RawSocket
3022 Example:
3023 $socket = $imap->RawSocket;
3024 # or:
3025 $imap->RawSocket($socketh);
3026 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 If you supply a socket handle yourself, either by doing something like:
3034 $imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
3036 or by doing something like:
3038 $imap = Mail::IMAPClient->new(User => $user,
3040 Password => $pass, Server => $host);
3041 # blah blah blah
3042 $imap->RawSocket($ssl);
3043 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 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 For a more DWIM approach to setting the socket see "Socket".
3059 Readmethod
3061 Example:
3062 $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 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 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 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 See also "Prewritemethod".
3094 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 Version note: attribute added in Mail::IMAPClient 3.30
3105 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 See also "Keepalive"
3114 Version note: attribute added in Mail::IMAPClient 3.17
3116 Server
3118 Example:
3119 $Server = $imap->Server();
3121 # or:
3122 $imap->Server($hostname);
3123 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 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 Example:
3139 print "This is very risky!\n" if $imap->Showcredentials();
3141 # or:
3142 $imap->Showcredentials(0); # mask credentials again
3143 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 Example:
3149 $Socket = $imap->Socket();
3151 # or:
3152 $imap->Socket($socket_fh);
3153 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 If you supply a socket handle yourself, either by doing something like:
3161 $imap = Mail::IMAPClient->new( Socket => $sock, User => ... );
3163 or by doing something like:
3165 $imap = Mail::IMAPClient->new(
3167 User => $user, Password => $pass, Server => $host
3168 );
3169 $imap->Socket($ssl);
3170 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 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 • read the initial greeting message from the server;
3182 • call "login" if the conditions apply (see "connect" for details);
3184 • leave the Mail::IMAPClient object in a suitable state.
3186 For these reasons, the following example will work "out of the box":
3188 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 If you need more control over the socket, e.g. you have to implement a
3201 fancier authentication method, see "RawSocket".
3202 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 Version note: attribute added in Mail::IMAPClient 3.22
3215 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 For example, to always pass MultiHomed => 1 to IO::Socket::...->new the
3222 following can be used:
3223 $imap = Mail::IMAPClient->new(
3225 ..., Socketargs => [ MultiHomed => 1 ], ...
3226 );
3227 See also "Ssl" for specific control of the args to IO::Socket::SSL.
3229 Version note: attribute added in Mail::IMAPClient 3.34
3231 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 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 Version note: attribute added in Mail::IMAPClient 3.18
3245 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 The names are to be specified as an ARRAY. Black-slashes and casing
3252 will be ignored.
3253 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 Timeout
3260 Example:
3261 $Timeout = $imap->Timeout();
3263 # or:
3264 $imap->Timeout($seconds);
3265 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 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 Uid
3275 Example:
3276 $Uid = $imap->Uid();
3278 # or:
3279 $imap->Uid($true_or_false);
3280 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 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 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 The methods currently affected by turning on the "Uid" flag are:
3304 copy fetch
3306 search store
3307 message_string message_uid
3308 body_string flags
3309 move size
3310 parse_headers thread
3311 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 Example 1:
3317 $imap->Uid(1);
3319 my @uids = $imap->search('SUBJECT',"Just a silly test"); #
3320 $imap->Uid(0);
3321 Example 2:
3323 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 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 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 By default, the "Uid" parameter is turned on.
3350 User
3352 Example:
3353 $User = $imap->User();
3355 # or:
3356 $imap->User($userid);
3357 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 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
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 Escaped_history
3374 Example:
3375 my @history = $imap->Escaped_history;
3377 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 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 Escaped_results
3390 Example:
3391 my @results = $imap->Escaped_results;
3393 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 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 History
3406 Example:
3407 my @history = $imap->History;
3409 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 IsUnconnected
3417 returns a true value if the object is currently in an "Unconnected"
3418 state.
3419 IsConnected
3421 returns a true value if the object is currently in either a
3422 "Connected", "Authenticated", or "Selected" state.
3423 IsAuthenticated
3425 returns a true value if the object is currently in either an
3426 "Authenticated" or "Selected" state.
3427 IsSelected
3429 returns a true value if the object is currently in a "Selected" state.
3430 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 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 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 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 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 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 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 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 Transaction
3487 The Transaction method returns the tag value (or transaction number) of
3488 the last IMAP client command.
3489
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 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 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 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 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 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 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 The following list summarizes the methods and parameters that you may
3536 find useful in implementing advanced authentication:
3537 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 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 "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 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 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 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 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 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 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 $Authcallback->( $challenge, $imap )
3606 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 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 The Readmethod can hold a subroutine to be used to replace sysread
3620 usually performed by Mail::IMAPClient.
3621 See "Prewritemethod" and "Readmethod" for details.
3623
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 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 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.
3642perl v5.34.0 2021-07-22 Mail::IMAPClient(3)