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 )
196 or die "Cannot connect to $host as $id: $@";
197 See also "Parameters", "connect" and "login" for more information on
199 how to manually connect and login after new.
200 Quote
202 Example:
203 $imap->search( HEADER => 'Message-id' => \$imap->Quote($msg_id) );
205 The Quote method accepts a value as an argument and returns its
207 argument as a correctly quoted string or a literal string. Since
208 version 3.17 Mail::IMAPClient automatically quotes search arguments we
209 use a SCALARREF so search will not modify or re-quote the value
210 returned by Quote.
211 Note this method should not be used on folder names for
213 Mail::IMAPClient methods, since methods that accept folder names as an
214 argument will quote the folder name arguments automatically.
215 If you are getting unexpected results when running methods with values
217 that have (or might have) embedded spaces, double quotes, braces, or
218 parentheses, then calling Quote may be necessary. This method should
219 not be used with arguments that are wrapped in quotes or parens if
220 those quotes or parens are required by RFC3501. For example, if the
221 RFC requires an argument in this format:
222 ( argument )
224 and the argument is (or might be) "pennies (from heaven)", then one
226 could use:
227 $argument = "(" . $imap->Quote($argument) . ")"
229 Of course, the fact that sometimes these characters are sometimes
231 required delimiters is precisely the reason you must quote them when
232 they are not delimiting.
233 However, there are times when a method fails unexpectedly and may
235 require the use of Quote to work. Should this happen, you can probably
236 file a bug/enhancement request for Mail::IMAPClient to safeguard the
237 particular call/case better.
238 An example is RFC822 Message-id's, which usually don't contain quotes
240 or parens. When dealing with these it is usually best to take
241 proactive, defensive measures from the very start and use Quote.
242 Range
244 Example:
245 my $parsed = $imap->parse_headers(
247 $imap->Range( $imap->messages ), "Date", "Subject"
248 );
249 The Range method will condense a list of message sequence numbers or
251 message UID's into the most compact format supported by RFC3501. It
252 accepts one or more arguments, each of which can be:
253 a) a message number,
255 b) a comma-separated list of message numbers,
256 c) a colon-separated range of message numbers (i.e. "$begin:$end")
257 d) a combination of messages and message ranges, separated by commas
258 (i.e. 1,3,5:8,10), or
259 e) a reference to an array whose elements are like a) through d).
260 The Range method returns a Mail::IMAPClient::MessageSet object. The
262 object uses overload and if treated as a string it will act like a
263 string. This means you can ignore its objectivity and just treat it
264 like a string whose value is your message set expressed in compact
265 format.
266 This method provides an easy way to add or remove messages from a
268 message set.
269 For more information see Mail::IMAPClient::MessageSet.
271 Rfc3501_date
273 Example:
274 $Rfc3501_date = $imap->Rfc3501_date($seconds);
276 # or:
277 $Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);
278 The Rfc3501_date method accepts one input argument, a number of seconds
280 since the epoch date. It returns an RFC3501 compliant date string for
281 that date (as required in date-related arguments to SEARCH, such as
282 "since", "before", etc.).
283 Rfc3501_datetime
285 Example:
286 $date = $imap->Rfc3501_datetime($seconds);
288 # or:
289 $date = Mail::IMAPClient->Rfc3501_datetime($seconds);
290 The Rfc3501_datetime method accepts one or two arguments: a obligatory
292 timestamp and an optional zone. The zone shall be formatted as
293 "[+-]\d{4}", and defaults to +0000. The timestamp follows the
294 definition of the output of the platforms specific "time", usually in
295 seconds since Jan 1st 1970. However, you have to correct the number
296 yourself for the zone.
297 Rfc822_date
299 Example:
300 $Rfc822_date = $imap->Rfc822_date($seconds);
302 # or:
303 $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
304 The Rfc822_date method accepts one input argument, a number of seconds
306 since the epoch date. It returns an RFC822 compliant date string for
307 that date (without the 'Date:' prefix). Useful for putting dates in
308 message strings before calling "append", "search", etc.
309 Strip_cr
311 Examples:
312 my $stripped = $imap->Strip_cr($string);
314 # or:
315 my @list = $imap->some_imap_method;
316 @list = $imap->Strip_cr(@list);
317 # or:
318 my $list = [ $imap->some_imap_method ]; # returns an array ref
319 $list = $imap->Strip_cr($list);
320 The Strip_cr method strips carriage returns from input and returns the
322 new string to the caller. This method accepts one or more lines of
323 text as arguments, and returns those lines with all <CR><LF> sequences
324 changed to <LF>. Any input argument with no carriage returns is
325 returned unchanged. If the first argument (not counting the class name
326 or object reference) is an array reference, then members of that array
327 are processed as above and subsequent arguments are ignored. If the
328 method is called in scalar context then an array reference is returned
329 instead of an array of results.
330 NOTE: Strip_cr does not remove new line characters.
332
334 Object methods must be invoked against objects created via the "new"
335 method and cannot be invoked as class methods.
336 There object methods typically fall into one of two categories. There
338 are mailbox methods which participate in the IMAP session's
339 conversation (i.e. they issue IMAP client commands) and object control
340 methods which do not result in IMAP commands but which may affect later
341 commands or provide details of previous ones.
342 This object control methods can be further broken down into two types,
344 Parameter accessor methods, which affect the behavior of future mailbox
345 methods, and "Status Methods", which report on the affects of previous
346 mailbox methods.
347 Methods that do not result in new IMAP client commands being issued
349 (such as the "Transaction", "Status", and "History" methods) all begin
350 with an uppercase letter, to distinguish them from methods that do
351 correspond to IMAP client commands. Class methods and eponymous
352 parameter methods likewise begin with an uppercase letter because they
353 also do not correspond to an IMAP client command.
354 As a general rule, mailbox control methods return "undef" on failure
356 and something besides "undef" when they succeed. This rule is modified
357 in the case of methods that return search results. When called in a
358 list context, searches that do not find matching results return an
359 empty list. When called in a scalar context, searches with no hits
360 return 'undef' instead of an array reference. If you want to know why
361 you received no hits, you should check "LastError" or $@, which will be
362 empty if the search was successful but had no matching results but
363 populated with an error message if the search encountered a problem
364 (such as invalid parameters).
365 A number of IMAP commands do not have corresponding Mail::IMAPClient
367 methods. Patches are welcome. In the pre-2.99 releases of this
368 module, they were automatically created (AUTOLOAD), but that was very
369 error-prone and stalled the progress of this module.
370
372 append
373 Example:
374 my $uid_or_true = $imap->append( $folder, $msgtext )
376 or die "Could not append: ", $imap->LastError;
377 WARNING: This method may be deprecated in the future, consider using
379 "append_string" instead of this method.
380 The append method adds a message to the specified folder. See
382 "append_string" for details as it is effectively an alias for that
383 method.
384 DEPRECATED BEHAVIOR: Additional arguments are added to the message
386 text, separated with <CR><LF>.
387 append_string
389 Example:
390 # brackets indicate optional arguments (not array refs):
392 my $uidort = $imap->append_string( $folder, $msgtext [,$flags [,$date ] ] )
393 or die "Could not append_string: ", $imap->LastError;
394 Arguments:
396 $folder
398 the name of the folder to append the message to
399 $msgtext
401 the message text (including headers) of the message
402 $flags
404 An optional list of flags to set. The list must be specified as a
405 space-separated list of flags, including any backslashes that may
406 be necessary and optionally enclosed by parenthesis.
407 $date
409 An optional RFC3501 date argument to set as the internal date. It
410 should be in the format described for date_time fields in RFC3501,
411 i.e. "dd-Mon-yyyy hh:mm:ss +0000".
412 If you want to specify a date/time but you don't want any flags
414 then specify undef as the third ($flags) argument.
415 Returns:
417 error: undef
419 On error, undef can be returned regardless of LIST/SCALAR context.
420 Check "LastError" for details.
421 success: UID or $imap
423 With UIDPLUS the UID of the new message is returned otherwise a
424 true value (currently $self) is returned.
425 To protect against "bare newlines", append will insert a carriage
427 return before any newline that is "bare".
428 append_file
430 Example:
431 my $new_msg_uid = $imap->append_file(
433 $folder,
434 $file,
435 [ undef, $flags, $date ] # optional
436 ) or die "Could not append_file: ", $imap->LastError;
437 The append_file method adds a message to the specified folder. Note:
439 The brackets in the example indicate optional arguments; they do not
440 mean that the argument should be an array reference.
441 Arguments:
443 $folder
445 the name of the folder to append the message to
446 $file
448 a filename, filehandle or SCALAR reference which holds an
449 RFC822-formatted message
450 undef
452 a deprecated argument used as a place holder for backwards
453 compatibility
454 $flags
456 The optional argument is handled the same as append_string.
457 $date
459 The optional argument is handled the same as append_string (RFC3501
460 date), with the exception that if $date is "1" (one) then the
461 modification time (mtime) of the file will be used.
462 Returns:
464 error: undef
466 On error, undef can be returned regardless of LIST/SCALAR context.
467 Check "LastError" for details.
468 success: UID or $imap
470 With UIDPLUS the UID of the new message is returned otherwise a
471 true value (currently $self) is returned.
472 To protect against "bare newlines", append_file will insert a carriage
474 return before any newline that is "bare".
475 The append_file method provides a mechanism for allowing large messages
477 to be appended without holding the whole file in memory.
478 Version note: In 2.x an optional third argument to use for
480 "input_record_separator" was allowed, however this argument is
481 ignored/not supported as of 3.x.
482 authenticate
484 Example:
485 $imap->authenticate( $authentication_mechanism, $coderef )
487 or die "Could not authenticate: ", $imap->LastError;
488 This method implements the AUTHENTICATE IMAP client command. It can be
490 called directly or may be called by "login" if the "Authmechanism"
491 parameter is set to anything except 'LOGIN'.
492 The authenticate method accepts two arguments, an authentication type
494 to be used (ie CRAM-MD5) and a code or subroutine reference to execute
495 to obtain a response. The authenticate method assumes that the
496 authentication type specified in the first argument follows a
497 challenge-response flow. The authenticate method issues the IMAP
498 Client AUTHENTICATE command and receives a challenge from the server.
499 That challenge (minus any tag prefix or enclosing '+' characters but
500 still in the original base64 encoding) is passed as the only argument
501 to the code or subroutine referenced in the second argument. The
502 return value from the 2nd argument's code is written to the server as
503 is, except that a <CR><LF> sequence is appended if necessary.
504 If one or both of the arguments are not specified in the call to
506 authenticate but their corresponding parameters have been set
507 ("Authmechanism" and "Authcallback", respectively) then the parameter
508 values are used. Arguments provided to the method call however will
509 override parameter settings.
510 If you do not specify a second argument and you have not set the
512 "Authcallback" parameter, then the first argument must be one of the
513 authentication mechanisms for which Mail::IMAPClient has built in
514 support.
515 See also the "login" method, which is the simplest form of
517 authentication defined by RFC3501.
518 before
520 Example:
521 my @msgs = $imap->before($Rfc3501_date)
523 or warn "No messages found before $Rfc3501_date.\n";
524 The before method works just like the "since" method, below, except it
526 returns a list of messages whose internal system dates are before the
527 date supplied as the argument to the before method.
528 body_string
530 Example:
531 my $string = $imap->body_string($msgId)
533 or die "Could not body_string: ", $imap->LastError;
534 The body_string method accepts a message sequence number (or a message
536 UID, if the "Uid" parameter is set to true) as an argument and returns
537 the message body as a string. The returned value contains the entire
538 message in one scalar variable, without the message headers.
539 bodypart_string
541 Example:
542 my $string = $imap->bodypart_string(
544 $msgid, $part_number, $length, $offset
545 ) or die "Could not get bodypart string: ", $imap->LastError;
546 The bodypart_string method accepts a message sequence number (or a
548 message UID, if the "Uid" parameter is set to true) and a body part as
549 arguments and returns the message part as a string. The returned value
550 contains the entire message part (or, optionally, a portion of the
551 part) in one scalar variable.
552 If an optional third argument is provided, that argument is the number
554 of bytes to fetch. (The default is the whole message part.) If an
555 optional fourth argument is provided then that fourth argument is the
556 offset into the part at which the fetch should begin. The default is
557 offset zero, or the beginning of the message part.
558 If you specify an offset without specifying a length then the offset
560 will be ignored and the entire part will be returned.
561 bodypart_string will return "undef" if it encounters an error.
563 capability
565 Example:
566 my $features = $imap->capability
568 or die "Could not determine capability: ", $imap->LastError;
569 The capability method returns an array of capabilities as returned by
571 the CAPABILITY IMAP Client command, or a reference to an array of
572 capabilities if called in scalar context. If the CAPABILITY IMAP
573 Client command fails for any reason then the capability method will
574 return "undef". Supported capabilities are cached by the client,
575 however, this cache is deleted after a connection is set to
576 Authenticated and when "starttls" is called.
577 See also "has_capability".
579 close
581 Example:
582 $imap->close or die "Could not close: $@\n";
584 The close method is used to close the currently selected folder via the
586 CLOSE IMAP client command. According to RFC3501, the CLOSE command
587 performs an implicit EXPUNGE, which means that any messages that are
588 flagged as \Deleted (i.e. with the "delete_message" method) will now be
589 deleted. If you haven't deleted any messages then close can be thought
590 of as an "unselect".
591 Note: this closes the currently selected folder, not the IMAP session.
593 See also "delete_message", "expunge", and RFC3501.
595 compress
597 Example:
598 $imap->compress or die "Could not enable RFC4978 compression: $@\n";
600 The compress method accepts no arguments. This method is used to
602 instruct the server to use the DEFLATE (RFC1951) compression extension.
603 See the "Compress" attribute for how to specify arguments for use
604 during the initialization process.
605 Version note: method added in Mail::IMAPClient 3.30
607 connect
609 Example:
610 $imap->connect or die "Could not connect: $@\n";
612 The connect method connects an imap object to the server. It returns
614 "undef" if it fails to connect for any reason. If values are available
615 for the "User" and "Password" parameters at the time that connect is
616 invoked, then connect will call the "login" method after connecting and
617 return the result of the "login" method to connect's caller. If either
618 or both of the "User" and "Password" parameters are unavailable but the
619 connection to the server succeeds then connect returns a pointer to the
620 IMAPClient object.
621 The "Server" parameter must be set (either during "new" method
623 invocation or via the "Server" object method) before invoking connect.
624 When the parameter is an absolute file path, an UNIX socket will get
625 opened. If the "Server" parameter is supplied to the "new" method then
626 connect is implicitly called during object construction.
627 The connect method sets the state of the object to "Connected" if it
629 successfully connects to the server. It returns "undef" on failure.
630 copy
632 Example:
633 # Here brackets indicate optional arguments:
635 my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
636 or die "Could not copy: $@\n";
637 Or:
639 # Now brackets indicate an array ref!
641 my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
642 or die "Could not copy: $@\n";
643 The copy method requires a folder name as the first argument, and a
645 list of one or more messages sequence numbers (or messages UID's, if
646 the UID parameter is set to a true value). The message sequence
647 numbers or UID's should refer to messages in the currently selected
648 folder. Those messages will be copied into the folder named in the
649 first argument.
650 The copy method returns "undef" on failure and a true value if
652 successful. If the server to which the current Mail::IMAPClient object
653 is connected supports the UIDPLUS capability then the true value
654 returned by copy will be a comma separated list of UID's, which are the
655 UID's of the newly copied messages in the target folder.
656 create
658 Example:
659 $imap->create($new_folder)
661 or die "Could not create $new_folder: $@\n";
662 The create method accepts one argument, the name of a folder (or what
664 RFC3501 calls a "mailbox") to create. If you specify additional
665 arguments to the create method and your server allows additional
666 arguments to the CREATE IMAP client command then the extra argument(s)
667 will be passed to your server.
668 If you specify additional arguments to the create method and your
670 server does not allow additional arguments to the CREATE IMAP client
671 command then the extra argument(s) will still be passed to your server
672 and the create will fail.
673 create returns a true value on success and "undef" on failure.
675 date
677 Example:
678 my $date = $imap->date($msg);
680 The date method accepts one argument, a message sequence number (or a
682 message UID if the "Uid" parameter is set to a true value). It returns
683 the date of message as specified in the message's RFC822 "Date: "
684 header, without the "Date: " prefix.
685 The date method is a short-cut for:
687 my $date = $imap->get_header($msg,"Date");
689 delete
691 Example:
692 $imap->delete($folder) or die "Could not delete $folder: $@\n";
694 The delete method accepts a single argument, the name of a folder to
696 delete. It returns a true value on success and "undef" on failure.
697 deleteacl
699 Example:
700 $imap->deleteacl( $folder, $userid )
702 or die "Could not delete acl: $@\n";
703 The deleteacl method accepts two input arguments, a folder name, a user
705 id (or authentication identifier, to use the terminology of RFC2086).
706 See RFC2086 for more information. (This is somewhat experimental and
707 its implementation may change.)
708 delete_message
710 Example:
711 my @msgs = $imap->seen;
713 scalar(@msgs) and $imap->delete_message(\@msgs)
714 or die "Could not delete_message: $@\n";
715 The above could also be rewritten like this:
717 # scalar context returns array ref
719 my $msgs = scalar($imap->seen);
720 scalar(@$msgs) and $imap->delete_message($msgs)
722 or die "Could not delete_message: $@\n";
723 Or, as a one-liner:
725 $imap->delete_message( scalar($imap->seen) )
727 or warn "Could not delete_message: $@\n";
728 # just give warning in case failure is
729 # due to having no 'seen' msgs in the 1st place!
730 The delete_message method accepts a list of arguments. If the "Uid"
732 parameter is not set to a true value, then each item in the list should
733 be either:
734 · a message sequence number,
736 · a comma-separated list of message sequence numbers,
738 · a reference to an array of message sequence numbers, or
740 If the "Uid" parameter is set to a true value, then each item in the
742 list should be either:
743 · a message UID,
745 · a comma-separated list of UID's, or
747 · a reference to an array of message UID's.
749 The messages identified by the sequence numbers or UID's will be
751 deleted. If successful, delete_message returns the number of messages
752 it was told to delete. However, since the delete is done by issuing
753 the +FLAGS.SILENT option of the STORE IMAP client command, there is no
754 guarantee that the delete was successful for every message. In this
755 manner the delete_message method sacrifices accuracy for speed.
756 Generally, though, if a single message in a list of messages fails to
757 be deleted it's because it was already deleted, which is what you
758 wanted anyway so why worry about it? If there is a more severe error,
759 i.e. the server replies "NO", "BAD", or, banish the thought, "BYE",
760 then delete_message will return "undef".
761 If you must have guaranteed results then use the IMAP STORE client
763 command (via the default method) and use the +FLAGS (\Deleted) option,
764 and then parse your results manually.
765 Eg:
767 $imap->store( $msg_id, '+FLAGS (\Deleted)' );
769 my @results = $imap->History( $imap->Transaction );
770 ... # code to parse output goes here
771 (Frankly I see no reason to bother with any of that; if a message
773 doesn't get deleted it's almost always because it's already not there,
774 which is what you want anyway. But 'your mileage may vary' and all
775 that.)
776 The IMAPClient object must be in "Selected" status to use the
778 delete_message method.
779 NOTE: All the messages identified in the input argument(s) must be in
781 the currently selected folder. Failure to comply with this requirement
782 will almost certainly result in the wrong message(s) being deleted.
783 ADDITIONAL NOTE: In the grand tradition of the IMAP protocol, deleting
785 a message doesn't actually delete the message. Really. If you want to
786 make sure the message has been deleted, you need to expunge the folder
787 (via the "expunge" method, which is implemented via the default
788 method). Or at least "close" it. This is generally considered a
789 feature, since after deleting a message, you can change your mind and
790 undelete it at any time before your "expunge" or "close".
791 See also: the "delete" method, to delete a folder, the "expunge"
793 method, to expunge a folder, the "restore_message" method to undelete a
794 message, and the "close" method (implemented here via the default
795 method) to close a folder. Oh, and don't forget about RFC3501.
796 deny_seeing
798 Example:
799 # Reset all read msgs to unread
801 # (produces error if there are no seen msgs):
802 $imap->deny_seeing( scalar($imap->seen) )
803 or die "Could not deny_seeing: $@\n";
804 The deny_seeing method accepts a list of one or more message sequence
806 numbers, or a single reference to an array of one or more message
807 sequence numbers, as its argument(s). It then unsets the "\Seen" flag
808 for those messages (so that you can "deny" that you ever saw them). Of
809 course, if the "Uid" parameter is set to a true value then those
810 message sequence numbers should be unique message id's.
811 Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
813 specifying "$imap->unset_flag("Seen",@msgs)".
814 disconnect
816 Example:
817 $imap->disconnect or warn "Could not logout: $@\n";
819 This method calls "logout", see "logout" for details.
821 done
823 Example:
824 my $tag = $imap->idle or warn "idle failed: $@\n";
826 doSomethingA();
827 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
828 doSomethingB();
829 my $results = $imap->done($tag) or warn "Error from done: $@\n";
830 The done method tells the IMAP server to terminate the IDLE command.
832 The only argument is the tag (identifier) received from the previous
833 call to "idle". If tag is not specified a default tag based on the
834 Count attribute is assumed to be the tag to look for in the response
835 from the server.
836 If an invalid tag is specified, or the default tag is wrong, then done
838 will hang indefinitely or until a timeout occurs.
839 If done is called when an "idle" command is not active then the server
841 will likely respond with an error like * BAD Invalid tag.
842 On failure <undef> is returned and "LastError" is set.
844 See also "idle", "idle_data" and "Results".
846 examine
848 Example:
849 $imap->examine($folder) or die "Could not examine: $@\n";
851 The examine method selects a folder in read-only mode and changes the
853 object's state to "Selected". The folder selected via the examine
854 method can be examined but no changes can be made unless it is first
855 selected via the "select" method.
856 The examine method accepts one argument, which is the name of the
858 folder to select.
859 exists
861 Example:
862 $imap->exists($folder) or warn "$folder not found: $@\n";
864 Accepts one argument, a folder name. Returns true if the folder exists
866 or false if it does not exist.
867 expunge
869 Example:
870 $imap->expunge($folder) or die "Could not expunge: $@\n";
872 The expunge method accepts one optional argument, a folder name. It
874 expunges the folder specified as the argument, or the currently
875 selected folder (if any) when no argument is supplied.
876 Although RFC3501 does not permit optional arguments (like a folder
878 name) to the EXPUNGE client command, the "expunge" method does. Note:
879 expunging a folder deletes the messages that have the \Deleted flag set
880 (i.e. messages flagged via "delete_message").
881 See also the "close" method, which "deselects" as well as expunges.
883 fetch
885 Usage:
886 $imap->fetch( [$seq_set|ALL], @msg_data_items )
888 Example:
890 my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
892 The fetch method implements the FETCH IMAP client command. It accepts
894 a list of arguments, which will be converted into a space-delimited
895 list of arguments to the FETCH IMAP client command. If no arguments
896 are supplied then fetch does a FETCH ALL. If the "Uid" parameter is
897 set to a true value then the first argument will be treated as a UID or
898 list of UID's, which means that the UID FETCH IMAP client command will
899 be run instead of FETCH. (It would really be a good idea at this point
900 to review RFC3501.)
901 If called in array context, fetch will return an array of output lines.
903 The output lines will be returned just as they were received from the
904 server, so your script will have to be prepared to parse out the bits
905 you want. The only exception to this is literal strings, which will be
906 inserted into the output line at the point at which they were
907 encountered (without the {nnn} literal field indicator). See RFC3501
908 for a description of literal fields.
909 If fetch is called in a scalar context, then a reference to an array
911 (as described above) is returned instead of the entire array.
912 fetch returns "undef" on failure. Inspect "LastError" or $@ for an
914 explanation of your error.
915 fetch_hash
917 Usage:
918 $imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
920 Examples:
922 my $hashref = $imap->fetch_hash("RFC822.SIZE");
924 OR
926 my $hashref = {};
928 $imap->fetch_hash( "RFC822.SIZE", $hashref );
929 print "Msg #$_ is $hashref->{$_}->{'RFC822.SIZE'} bytes\n" for (keys %$hashref);
930 The fetch_hash method accepts a list of message attributes to be
932 fetched (as described in RFC3501). It returns a hash whose keys are
933 all the messages in the currently selected folder and whose values are
934 key-value pairs of fetch keywords and the message's value for that
935 keyword (see sample output below).
936 If fetch_hash is called in scalar context, it returns a reference to
938 the hash instead of the hash itself. If the last argument is a hash
939 reference, then that hash reference will be used as the place where
940 results are stored (and that reference will be returned upon successful
941 completion). If the last argument is not a reference then it will be
942 treated as one of the FETCH attributes and a new hash will be created
943 and returned (either by value or by reference, depending on the context
944 in which fetch_hash was called).
945 For example, if you have a folder with 3 messages and want the size and
947 internal date for each of them, you could do the following:
948 use Mail::IMAPClient;
950 use Data::Dumper;
951 # ... other code goes here
952 $imap->select($folder);
953 my $hash = $imap->fetch_hash( "RFC822.SIZE", "INTERNALDATE" );
954 # (Same as:
955 # my $hash = $imap->fetch_hash("RFC822.SIZE");
956 # $imap->fetch_hash( "INTERNALDATE", $hash );
957 # ).
958 print Data::Dumper->Dumpxs( [$hash], ['$hash'] );
959 This would result in Data::Dumper output similar to the following:
961 $hash = {
963 '1' => {
964 'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
965 'RFC822.SIZE' => '1586',
966 },
967 '2' => {
968 'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
969 'RFC822.SIZE' => '1945',
970 },
971 '3' => {
972 'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
973 'RFC822.SIZE' => '134314',
974 }
975 };
976 By itself this method may be useful for tasks like obtaining the size
978 of every message in a folder. It issues one command and receives one
979 (possibly long!) response from the server.
980 If the fetch request causes the server to return data in a
982 parenthesized list, the data within the parenthesized list may be
983 escaped via the Escape() method. Use the Unescape() method to get the
984 raw values back in this case.
985 flags
987 Example:
988 my @flags = $imap->flags($msgid)
990 or die "Could not flags: $@\n";
991 The flags method implements the FETCH IMAP client command to list a
993 single message's flags. It accepts one argument, a message sequence
994 number (or a message UID, if the "Uid" parameter is true), and returns
995 an array (or a reference to an array, if called in scalar context)
996 listing the flags that have been set. Flag names are provided with
997 leading backslashes.
998 As of version 1.11, you can supply either a list of message id's or a
1000 reference to an array of message id's (which means either sequence
1001 number, if the Uid parameter is false, or message UID's, if the Uid
1002 parameter is true) instead of supplying a single message sequence
1003 number or UID. If you do, then the return value will not be an array
1004 or array reference; instead, it will be a hash reference, with each key
1005 being a message sequence number (or UID) and each value being a
1006 reference to an array of flags set for that message.
1007 For example, if you want to display the flags for every message in the
1009 folder where you store e-mail related to your plans for world
1010 domination, you could do something like this:
1011 use Mail::IMAPClient;
1013 my $imap = Mail::IMAPClient->new(
1014 Server => $imaphost,
1015 User => $login,
1016 Password => $pass,
1017 Uid => 1, # optional
1018 );
1019 $imap->select("World Domination");
1021 # get the flags for every message in my 'World Domination' folder
1022 $flaghash = $imap->flags( scalar( $imap->search("ALL") ) );
1023 # pump through sorted hash keys to print results:
1025 for my $k ( sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash ) {
1026 # print: Message 1: \Flag1, \Flag2, \Flag3
1027 print "Message $k:\t", join( ", ", @{$flaghash->{$k}} ), "\n";
1028 }
1029 folders
1031 Example:
1032 $imap->folders or die "Could not list folders: $@\n";
1034 The folders method returns an array listing the available folders. It
1036 will only be successful if the object is in the Authenticated or
1037 Selected states.
1038 The folders method accepts one optional argument, which is a prefix.
1040 If a prefix is supplied to the folders method, then only folders
1041 beginning with the prefix will be returned.
1042 For example:
1044 print join( ", ", $imap->folders ), ".\n";
1046 # Prints:
1047 # INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1048 print join( ", ", $imap->folders("Projects") ), ".\n";
1049 # Prints:
1050 # Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1051 print join( ", ", $imap->folders("Projects" . $imap->separator) ), ".\n";
1052 # Prints:
1053 # Projects/Completed, Projects/Ongoing
1054 Please note that documentation previously suggested that if you just
1056 want to list a folder's subfolders (and not the folder itself), then
1057 you need to include the hierarchy separator character (as returned by
1058 the "separator" method). However, this does not match the behavior of
1059 the existing implementation, so you will need to manually exclude the
1060 parent folder from the results.
1061 folders_hash
1063 my @fhashes = $imap->folders_hash
1064 or die "Could not get list of folder hashes.\n";
1065 The folders_hash method accepts one optional argument, which is a
1067 prefix. If a prefix is supplied to the folders_hash method, then only
1068 folders beginning with the prefix will be returned.
1069 An array(ref) of hashes is returned that contain information about the
1071 requested folders. Each hash contains three keys (name, attrs, delim)
1072 and looks like the following:
1073 {
1075 name => 'Mail/Box/Name',
1076 attrs => [ '\Marked', '\HasNoChildren' ],
1077 delim => '/',
1078 }
1079 IMAP servers implementing RFC6154 return attributes to be used to
1081 identify special-use mailboxes (folders).
1082 my $sattr_re = /\A\\(?:All|Archive|Drafts|Flagged|Junk|Sent|Trash)\Z/;
1084 foreach my $fhash (@fhashes) {
1085 next unless defined $fhash->{name};
1086 my @special = grep { $sattr_re } @{ $fhash->{attrs} };
1087 print("special: $fhash->{name} : @special\n") if (@special);
1088 }
1089 Version note: method added in Mail::IMAPClient 3.34
1091 xlist_folders (DEPRECATED)
1093 This method is deprecated as of version 3.34. Please use folders_hash
1094 instead. See RFC6154 for attributes to be used to identify special-use
1095 mailboxes (folders).
1096 Example:
1098 my $xlist = $imap->xlist_folders
1100 or die "Could not get xlist folders.\n";
1101 IMAP servers implementing the XLIST extension (such as Gmail) designate
1103 particular folders to be used for particular functions. This is useful
1104 in the case where you want to know which folder should be used for
1105 Trash when the actual folder name can't be predicted (e.g. in the case
1106 of Gmail, the folder names change depending on the user's locale
1107 settings).
1108 The xlist_folders method returns a hash listing any "xlist" folder
1110 names, with the values listing the actual folders that should be used
1111 for those names. For example, using this method with a Gmail user
1112 using the English (US) locale might give this output from Data::Dumper:
1113 $VAR1 = {
1115 'Inbox' => 'Inbox',
1116 'AllMail' => '[Gmail]/All Mail',
1117 'Trash' => '[Gmail]/Trash',
1118 'Drafts' => '[Gmail]/Drafts',
1119 'Sent' => '[Gmail]/Sent Mail',
1120 'Spam' => '[Gmail]/Spam',
1121 'Starred' => '[Gmail]/Starred'
1122 };
1123 The same list for a user using the French locale might look like this:
1125 $VAR1 = {
1127 'Inbox' => 'Bo&AO4-te de r&AOk-ception',
1128 'AllMail' => '[Gmail]/Tous les messages',
1129 'Trash' => '[Gmail]/Corbeille',
1130 'Drafts' => '[Gmail]/Brouillons',
1131 'Sent' => '[Gmail]/Messages envoy&AOk-s',
1132 'Spam' => '[Gmail]/Spam',
1133 'Starred' => '[Gmail]/Suivis'
1134 };
1135 Mail::IMAPClient recognizes the following "xlist" folder names:
1137 Inbox
1139 AllMail
1140 Trash
1141 Drafts
1142 Sent
1143 Spam
1144 Starred
1145 These are currently the only ones supported by Gmail. The XLIST
1147 extension is not documented, and there are no other known
1148 implementations other than Gmail, so this list is based on what Gmail
1149 provides.
1150 If the server does not support the XLIST extension, this method returns
1152 undef.
1153 Version note: method added in Mail::IMAPClient 3.21
1155 has_capability
1157 Example:
1158 my $has_feature = $imap->has_capability($feature)
1160 or die "Could not do has_capability($feature): $@\n";
1161 Returns true if the IMAP server to which the IMAPClient object is
1163 connected has the capability specified as an argument to
1164 has_capability. If the server does not have the capability then the
1165 empty string "" is returned, if the underlying "capability" calls fails
1166 then undef is returned.
1167 idle
1169 Example:
1170 my $tag = $imap->idle or warn "idle failed: $@\n";
1172 doSomethingA();
1173 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1174 doSomethingB();
1175 my $results = $imap->done($tag) or warn "Error from done: $@\n";
1176 The idle method tells the IMAP server the client is ready to accept
1178 unsolicited mailbox update messages (on the selected folder/mailbox).
1179 This method is only valid on servers that support the IMAP IDLE
1180 extension, see RFC2177 for details.
1181 The idle method accepts no arguments and returns the tag (identifier)
1183 that was sent by the client for this command. This tag should be
1184 supplied as the argument to "done" when ending the IDLE command.
1185 On failure <undef> is returned and "LastError" is set.
1187 The method "idle_data" may be used once idle has been successful.
1189 However, no mailbox operations may be called until the idle command has
1190 been terminated by calling "done". Failure to do so will result in an
1191 error and the idle command will typically be terminated by the server.
1192 See also "idle_data" and "done".
1194 idle_data
1196 Usage:
1197 # an optional timeout in seconds may be specified
1199 $imap->idle_data( [$timeout] )
1200 Example:
1202 my $tag = $imap->idle or warn "idle failed: $@\n";
1204 doSomethingA();
1205 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1206 doSomethingB();
1207 my $results = $imap->done($tag) or warn "Error from done: $@\n";
1208 The idle_data method can be used to accept any unsolicited mailbox
1210 update messages that have been sent by the server during an "idle"
1211 command. This method does not send any commands to the server, it
1212 simply looks for and optionally waits for data from the server and
1213 returns that data to the caller.
1214 The idle_data method accepts an optional $timeout argument and returns
1216 an array (or an array reference if called in scalar context) with the
1217 messages from the server.
1218 By default a timeout of 0 seconds is used (do not block). Internally
1220 the timeout is passed to "select" in perlfunc. The timeout controls
1221 how long the select call blocks if there are no messages waiting to be
1222 read from the server.
1223 On failure <undef> is returned and "LastError" is set.
1225 See also "imap" and "done".
1227 Version note: method added in Mail::IMAPClient 3.23 Warning: this
1229 method is considered experimental and the interface/output may change
1230 in a future version.
1231 imap4rev1
1233 Example:
1234 $imap->imap4rev1 or die "Could not imap4rev1: $@\n";
1236 Returns true if the IMAP server to which the IMAPClient object is
1238 connected has the IMAP4REV1 capability. If the server does not have
1239 the capability then the empty string "" is returned, if the underlying
1240 "capability" calls fails then undef is returned.
1241 internaldate
1243 Example:
1244 my $msg_internal_date = $imap->internaldate($msgid)
1246 or die "Could not internaldate: $@\n";
1247 internaldate accepts one argument, a message id (or UID if the "Uid"
1249 parameter is true), and returns that message's internal date or undef
1250 if the call fails or internal date is not returned.
1251 get_bodystructure
1253 Example:
1254 my $bodyStructObject = $imap->get_bodystructure($msgid)
1256 or die "Could not get_bodystructure: $@\n";
1257 The get_bodystructure method accepts one argument, a message sequence
1259 number or, if "Uid" is true, a message UID. It obtains the message's
1260 body structure and returns a parsed Mail::IMAPClient::BodyStructure
1261 object for the message.
1262 get_envelope
1264 Example:
1265 my $envObject = $imap->get_envelope(@args)
1267 or die "Could not get_envelope: $@\n";
1268 The get_envelope method accepts one argument, a message sequence number
1270 or, if "Uid" is true, a message UID. It obtains the message's envelope
1271 and returns a Mail::IMAPClient::BodyStructure::Envelope object for the
1272 envelope, which is just a version of the envelope that's been parsed
1273 into a Perl object.
1274 For more information on how to use this object once you've gotten it,
1276 see the Mail::IMAPClient::BodyStructure documentation. (As of this
1277 writing there is no separate pod document for
1278 Mail::IMAPClient::BodyStructure::Envelope.)
1279 getacl
1281 Example:
1282 my $hash = $imap->getacl($folder)
1284 or die "Could not getacl for $folder: $@\n";
1285 getacl accepts one argument, the name of a folder. If no argument is
1287 provided then the currently selected folder is used as the default. It
1288 returns a reference to a hash. The keys of the hash are userids that
1289 have access to the folder, and the value of each element are the
1290 permissions for that user. The permissions are listed in a string in
1291 the order returned from the server with no white space or punctuation
1292 between them.
1293 get_header
1295 Example:
1296 my $messageId = $imap->get_header( $msg, "Message-Id" );
1298 The get_header method accepts two arguments, a message sequence number
1300 or UID and the name of an RFC822 header (without the trailing colon).
1301 It returns the value for that header in the message whose sequence
1302 number or UID was passed as the first argument. If no value can be
1303 found it returns "undef"; if multiple values are found it returns the
1304 first one. Its return value is always a scalar. get_header uses case
1305 insensitive matching to get the value, so you do not have to worry
1306 about the case of your second argument.
1307 The get_header method is a short-cut for:
1309 my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
1311 getquotaroot
1313 Example:
1314 my $results = $imap->getquotaroot($mailboxname)
1316 or die "Could not getquotaroot for $mailboxname: $@\n";
1317 The getquotaroot method implements the RFC2087 GETQUOTAROOT command.
1319 The "$mailboxname" defaults to "INBOX" if no argument is provided.
1320 On error "undef" is returned, otherwise "Results" are returned. The
1322 results should have the untagged QUOTAROOT response from the server
1323 along with the QUOTAROOT's resource usage and limits in an untagged
1324 QUOTA response.
1325 See also RFC2087, "getquota", "setquota", "quota" and "quota_usage".
1327 getquota
1329 Example:
1330 my $results = $imap->getquota($quotaroot)
1332 or die "Could not getquota for $quotaroot: $@\n";
1333 The getquota method implements the RFC2087 GETQUOTA command. The
1335 "$quotaroot" defaults to "user/User" if no argument is provided.
1336 On error "undef" is returned, otherwise "Results" are returned. The
1338 results from the server should have the untagged QUOTA response from
1339 the server.
1340 See also RFC2087, "getquotaroot", "quota" and "quota_usage".
1342 quota
1344 Example:
1345 my $limit = $imap->quota($quotaroot)
1347 or die "Could not get quota limit for $quotaroot: $@\n";
1348 The quota method takes the "Results" from getquota and parses out the
1350 "STORAGE" limit returned by the server. The "$quotaroot" defaults to
1351 "INBOX" if no argument is provided.
1352 On error "undef" is returned, otherwise the integer "STORAGE" limit
1354 provided by the server is returned.
1355 See also RFC2087, "getquotaroot", "getquota" and "quota_usage".
1357 quota_usage
1359 Example:
1360 my $usage = $imap->quota_usage($quotaroot)
1362 or die "Could not get quota usage for $quotaroot: $@\n";
1363 The quota_usage method takes the "Results" from getquota and parses out
1365 the "STORAGE" usage returned by the server. The "$quotaroot" defaults
1366 to "INBOX" if no argument is provided.
1367 On error "undef" is returned, otherwise the integer "STORAGE" usage
1369 provided by the server is returned.
1370 See also RFC2087, "getquotaroot", "getquota" and "quota".
1372 setquota
1374 Example:
1375 my $results = $imap->setquota( $quotaroot, $resource, $limit )
1377 or die "Could not setquota for $quotaroot: $@\n";
1378 The setquota method implements the RFC2087 SETQUOTA command. It
1380 accepts multiple pairs of $resource and $limit arguments. The
1381 "$quotaroot" defaults to "user/User" if not defined.
1382 On error "undef" is returned, otherwise "Results" are returned.
1384 See also RFC2087, "getquotaroot" and "getquota".
1386 is_parent
1388 Example:
1389 my $hasKids = $imap->is_parent($folder);
1391 The is_parent method accepts one argument, the name of a folder. It
1393 returns a value that indicates whether or not the folder has children.
1394 The value it returns is either:
1395 1 (or a positive integer)
1397 The "\HasChildren" attribute is set, indicating that the folder has
1398 children.
1399 0 (zero)
1401 The "\HasNoChildren" attribute is set, indicating that the folder
1402 has no children at this time.
1403 "undef"
1405 The "\NoInferiors" attribute is set, indicating the folder is not
1406 permitted to have children.
1407 Eg:
1409 my $parenthood = $imap->is_parent($folder);
1411 if ( defined($parenthood) ) {
1412 if ($parenthood) {
1413 print "$folder has children.\n";
1414 }
1415 else {
1416 print "$folder is permitted children, but has none.\n";
1417 }
1418 }
1419 else {
1420 print "$folder is not permitted to have children.\n";
1421 }
1422 list
1424 Example:
1425 my @raw_output = $imap->list(@args)
1427 or die "Could not list: $@\n";
1428 The list method implements the IMAP LIST client command. Arguments are
1430 passed to the IMAP server as received, separated from each other by
1431 spaces. If no arguments are supplied then the default list command
1432 "tag LIST "" '*'" is issued.
1433 The list method returns an array (or an array reference, if called in a
1435 scalar context). The array is the unadulterated output of the LIST
1436 command. (If you want your output adulterated then see the "folders"
1437 method, above.)
1438 An "undef" value is returned in case of errors. Be sure to check for
1440 it.
1441 listrights
1443 Example:
1444 $imap->listrights( $folder, $user )
1446 or die "Could not listrights: $@\n";
1447 The listrights method implements the IMAP LISTRIGHTS client command
1449 (RFC2086). It accepts two arguments, the foldername and a user id. It
1450 returns the rights the specified user has for the specified folder. If
1451 called in a scalar context then the rights are returned a strings, with
1452 no punctuation or white space or any nonsense like that. If called in
1453 array context then listrights returns an array in which each element is
1454 one right.
1455 login
1457 Example:
1458 $imap->login or die "Could not login: $@\n";
1460 The login method implements the IMAP LOGIN client command to log into
1462 the server. It automatically calls "authenticate" if the Authmechanism
1463 parameter is set to anything except 'LOGIN' otherwise a clear text
1464 LOGIN is attempted.
1465 The User and Password parameters must be set before the login method
1467 can be invoked. On success, a Mail::IMAPClient object with the Status
1468 of Authenticated is returned. On failure, undef is returned and $@ is
1469 set. The methods "new", "connect", and "Socket" may automatically
1470 invoke login see the documentation of each method for details.
1471 If the "Compress" parameter is set, the "compress" method will
1473 automatically be called after successful authentication.
1474 See also "proxyauth" and "Proxy" for additional information regarding
1476 ways of authenticating with a server via SASL and/or PROXYAUTH.
1477 proxyauth
1479 Example:
1480 $imap->login( "admin", "password" );
1482 $imap->proxyauth("someuser");
1483 The proxyauth method implements the IMAP PROXYAUTH client command. The
1485 command is used by Sun/iPlanet/Netscape IMAP servers to allow an
1486 administrative user to masquerade as another user.
1487 logout
1489 Example:
1490 $imap->logout or die "Could not logout: $@\n";
1492 The logout method implements the LOGOUT IMAP client command. This
1494 method causes the server to end the connection and the IMAPClient
1495 client enters the Unconnected state. This method does not, destroy the
1496 IMAPClient object, thus the "connect" and "login" methods can be used
1497 to establish a new IMAP session.
1498 Note that RFC2683 section 3.1.2 (Severed connections) makes some
1500 recommendations on how IMAP clients should behave. It is up to the
1501 user of this module to decide on the preferred behavior and code
1502 accordingly.
1503 Version note: documentation (from 2.x through 3.23) claimed that
1505 Mail::IMAPClient would attempt to log out of the server during DESTROY
1506 if the object is in the "Connected" state. This documentation was
1507 apparently incorrect from at least 2.2.2 and possibly earlier versions
1508 on up.
1509 lsub
1511 Example:
1512 $imap->lsub(@args) or die "Could not lsub: $@\n";
1514 The lsub method implements the IMAP LSUB client command. Arguments are
1516 passed to the IMAP server as received, separated from each other by
1517 spaces. If no arguments are supplied then the default lsub command
1518 "tag LSUB "" '*'" is issued.
1519 The lsub method returns an array (or an array reference, if called in a
1521 scalar context). The array is the unaltered output of the LSUB
1522 command. If you want an array of subscribed folders then see the
1523 "subscribed" method, below.
1524 mark
1526 Example:
1527 $imap->mark(@msgs) or die "Could not mark: $@\n";
1529 The mark method accepts a list of one or more messages sequence
1531 numbers, or a single reference to an array of one or more message
1532 sequence numbers, as its argument(s). It then sets the "\Flagged" flag
1533 for those message(s). Of course, if the "Uid" parameter is set to a
1534 true value then those message sequence numbers had better be unique
1535 message id's.
1536 Note that specifying "$imap->see(@msgs)" is just a shortcut for
1538 specifying "$imap->set_flag("Flagged",@msgs)".
1539 Massage
1541 Example:
1542 $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
1544 WARNING: This method may be deprecated in the future, consider using
1546 "Quote" instead of this method.
1547 The Massage method accepts a value as an argument and, optionally, a
1549 second value that, when true, indicates that the first argument is not
1550 the name of an existing folder.
1551 WARNING: If the first argument has double quotes at the beginning and
1553 end of its value, those double quote will be stripped unless the second
1554 argument does not evaluate to true.
1555 It returns its argument as a correctly quoted string or a literal
1557 string.
1558 Note that you should rarely use this on folder names, since methods
1560 that accept folder names as an argument will call Quote for you.
1561 message_count
1563 Example:
1564 my $msgcount = $imap->message_count($folder);
1566 defined($msgcount) or die "Could not message_count: $@\n";
1567 The message_count method accepts the name of a folder as an argument
1569 and returns the number of messages in that folder. Internally, it
1570 invokes the "status" method (see above) and parses out the results to
1571 obtain the number of messages. If you don't supply an argument to
1572 message_count then it will return the number of messages in the
1573 currently selected folder (assuming of course that you've used the
1574 "select" or "examine" method to select it instead of trying something
1575 funky). Note that RFC2683 contains warnings about the use of the IMAP
1576 STATUS command (and thus the "status" method and therefore the
1577 message_count method) against the currently selected folder. You
1578 should carefully consider this before using message_count on the
1579 currently selected folder. You may be better off using "search" or one
1580 of its variants (especially "messages"), and then counting the results.
1581 On the other hand, I regularly violate this rule on my server without
1582 suffering any dire consequences. Your mileage may vary.
1583 message_string
1585 Example:
1586 my $string = $imap->message_string($msgid)
1588 or die "Could not message_string: $@\n";
1589 The message_string method accepts a message sequence number (or message
1591 UID if "Uid" is true) as an argument and returns the message as a
1592 string. The returned value contains the entire message in one scalar
1593 variable, including the message headers. Note that using this method
1594 will set the message's "\Seen" flag as a side effect, unless Peek is
1595 set to a true value.
1596 message_to_file
1598 Example:
1599 $imap->message_to_file( $file, @msgs )
1601 or die "Could not message_to_file: $@\n";
1602 The message_to_file method accepts a filename or file handle and one or
1604 more message sequence numbers (or message UIDs if "Uid" is true) as
1605 arguments and places the message string(s) (including RFC822 headers)
1606 into the file named in the first argument (or prints them to the file
1607 handle, if a file handle is passed). The returned value is true on
1608 success and "undef" on failure.
1609 If the first argument is a reference, it is assumed to be an open file
1611 handle and will not be closed when the method completes, If it is a
1612 file, it is opened in append mode, written to, then closed.
1613 Note that using this method will set the message's "\Seen" flag as a
1615 side effect. But you can use the "deny_seeing" method to set it back,
1616 or set the "Peek" parameter to a true value to prevent setting the
1617 "\Seen" flag at all.
1618 This method currently works by making some basic assumptions about the
1620 server's behavior, notably that the message text will be returned as a
1621 literal string but that nothing else will be. If you have a better
1622 idea then I'd like to hear it.
1623 message_uid
1625 Example:
1626 my $msg_uid = $imap->message_uid($msg_seq_no)
1628 or die "Could not get uid for $msg_seq_no: $@\n";
1629 The message_uid method accepts a message sequence number (or message
1631 UID if "Uid" is true) as an argument and returns the message's UID.
1632 Yes, if "Uid" is true then it will use the IMAP UID FETCH UID client
1633 command to obtain and return the very same argument you supplied. This
1634 is an IMAP feature so don't complain to me about it.
1635 messages
1637 Example:
1638 # Get a list of messages in the current folder:
1640 my @msgs = $imap->messages or die "Could not messages: $@\n";
1641 # Get a reference to an array of messages in the current folder:
1642 my $msgs = $imap->messages or die "Could not messages: $@\n";
1643 If called in list context, the messages method returns a list of all
1645 the messages in the currently selected folder. If called in scalar
1646 context, it returns a reference to an array containing all the messages
1647 in the folder. If you have the "Uid" parameter turned off, then this
1648 is the same as specifying "1 ... $imap->message_count"; if you have UID
1649 set to true then this is the same as specifying
1650 "$imap->"search"("ALL")".
1651 migrate
1653 Example:
1654 $imap_src->migrate( $imap_dest, "ALL", $targetFolder )
1656 or die "Could not migrate: ", $imap_src->LastError;
1657 The migrate method copies the indicated message(s) from the currently
1659 selected folder to another Mail::IMAPClient object's session. It
1660 requires these arguments:
1661 1. a reference to the target Mail::IMAPClient object (not the calling
1663 object, which is connected to the source account);
1664 2. the message(s) to be copied, specified as either a) the message
1666 sequence number (or message UID if the UID parameter is true) of a
1667 single message, b) a reference to an array of message sequence
1668 numbers (or message UID's if the UID parameter is true) or c) the
1669 special string "ALL", which is a shortcut for the results of
1670 ""search"("ALL")".
1671 3. the name of the destination folder on the target mailbox to receive
1673 the message(s). If this argument is not supplied or is undef then
1674 the currently selected folder on the calling object will be used.
1675 The destination folder will be automatically created if necessary.
1676 The target ($imap_dest) Mail::IMAPClient object must not be the same
1678 object as the source ($imap_src).
1679 This method does not attempt to minimize memory usage. In the future
1681 it could be enhanced to (optionally) write message data to a temporary
1682 file to avoid storing the entire message in memory.
1683 To work around potential network timeouts on large messages, consider
1685 setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
1686 See also "Supportedflags".
1688 move
1690 Example:
1691 my $newUid = $imap->move( $newFolder, $oldUid )
1693 or die "Could not move: $@\n";
1694 $imap->expunge;
1695 The move method moves messages from the currently selected folder to
1697 the folder specified in the first argument to move. If the "Uid"
1698 parameter is not true, then the rest of the arguments should be either:
1699 a) a message sequence number,
1701 b) a comma-separated list of message sequence numbers, or
1703 c) a reference to an array of message sequence numbers.
1705 If the "Uid" parameter is true, then the arguments should be:
1707 a) a message UID,
1709 b) a comma-separated list of message UID's, or
1711 c) a reference to an array of message UID's.
1713 If the target folder does not exist then it will be created.
1715 If move is successful, then it returns a true value. Furthermore, if
1717 the Mail::IMAPClient object is connected to a server that has the
1718 UIDPLUS capability, then the true value will be the comma-separated
1719 list of UID's for the newly copied messages. The list will be in the
1720 order in which the messages were moved which should correspond to the
1721 order of the message UID provided by the caller.
1722 If the move is not successful then move returns "undef".
1724 Note that a move really just involves copying the message to the new
1726 folder and then setting the \Deleted flag. To actually delete the
1727 original message you will need to run "expunge" (or "close").
1728 namespace
1730 Example:
1731 my $refs = $imap->namespace
1733 or die "Could not namespace: $@\n";
1734 The namespace method runs the NAMESPACE IMAP command (as defined in RFC
1736 2342). When called in a list context, it returns a list of three
1737 references. Each reference looks like this:
1738 [
1740 [ $prefix_1, $separator_1 ],
1741 [ $prefix_2, $separator_2 ],
1742 [ $prefix_n, $separator_n ],
1743 ]
1744 The first reference provides a list of prefixes and separator
1746 characters for the available personal namespaces. The second reference
1747 provides a list of prefixes and separator characters for the available
1748 shared namespaces. The third reference provides a list of prefixes and
1749 separator characters for the available public namespaces.
1750 If any of the three namespaces are unavailable on the current server
1752 then an 'undef' is returned instead of a reference. So for example if
1753 shared folders were not supported on the server but personal and public
1754 namespaces were both available (with one namespace each), the returned
1755 value might resemble this:
1756 [ [ "", "/" ] , undef, [ "#news", "." ] ];
1758 If the namespace method is called in scalar context, it returns a
1760 reference to the above-mentioned list of three references, thus
1761 creating a single structure that would pretty-print something like
1762 this:
1763 $VAR1 = [
1765 [
1766 [ $user_prefix_1, $user_separator_1 ],
1767 [ $user_prefix_2, $user_separator_2 ],
1768 [ $user_prefix_n, $user_separator_n ],
1769 ], # or undef
1770 [
1771 [ $shared_prefix_1, $shared_separator_1 ],
1772 [ $shared_prefix_2, $shared_separator_2 ],
1773 [ $shared_prefix_n, $shared_separator_n ],
1774 ], # or undef
1775 [
1776 [ $public_prefix_1, $public_separator_1 ],
1777 [ $public_prefix_2, $public_separator_2 ],
1778 [ $public_prefix_n, $public_separator_n ],
1779 ], # or undef
1780 ];
1781 on
1783 Example:
1784 my @msgs = $imap->on($Rfc3501_date)
1786 or warn "Could not find messages sent on $Rfc3501_date: $@\n";
1787 The on method works just like the "since" method, below, except it
1789 returns a list of messages whose internal system dates are the same as
1790 the date supplied as the argument.
1791 parse_headers
1793 Example:
1794 my $hashref = $imap->parse_headers($msg||\@msgs, "Date", "Subject")
1796 or die "Could not parse_headers: $@\n";
1797 The parse_headers method accepts as arguments a message sequence number
1799 and a list of header fields. It returns a hash reference in which the
1800 keys are the header field names (without the colon) and the values are
1801 references to arrays of values. A picture would look something like
1802 this:
1803 $hashref = $imap->parse_headers(1,"Date","Received","Subject","To");
1805 $hashref = {
1806 "Date" => [ "Thu, 09 Sep 1999 09:49:04 -0400" ] ,
1807 "Received" => [ q/
1808 from mailhub ([111.11.111.111]) by mailhost.bigco.com
1809 (Netscape Messaging Server 3.6) with ESMTP id AAA527D for
1810 <bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
1811 /, q/
1812 from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
1813 id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
1814 (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
1815 /, q/
1816 from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
1817 with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
1818 18 Jun 1999 16:29:05 +0000 (GMT)
1819 /] ,
1820 "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
1821 "To" => [ "Big Shot <big.shot@bigco.com> ] ,
1822 };
1823 The text in the example for the "Received" array has been formatted to
1825 make reading the example easier. The actual values returned are just
1826 strings of words separated by spaces and with newlines and carriage
1827 returns stripped off. The Received header is probably the main reason
1828 that the parse_headers method creates a hash of lists rather than a
1829 hash of values.
1830 If the second argument to parse_headers is 'ALL' or if it is
1832 unspecified then all available headers are included in the returned
1833 hash of lists.
1834 If you're not emotionally prepared to deal with a hash of lists then
1836 you can always call the "fetch" method yourself with the appropriate
1837 parameters and parse the data out any way you want to. Also, in the
1838 case of headers whose contents are also reflected in the envelope, you
1839 can use the "get_envelope" method as an alternative to "parse_headers".
1840 If the "Uid" parameter is true then the first argument will be treated
1842 as a message UID. If the first argument is a reference to an array of
1843 message sequence numbers (or UID's if "Uid" is true), then
1844 parse_headers will be run against each message in the array. In this
1845 case the return value is a hash, in which the key is the message
1846 sequence number (or UID) and the value is a reference to a hash as
1847 described above.
1848 An example of using parse_headers to print the date and subject of
1850 every message in your smut folder could look like this:
1851 use Mail::IMAPClient;
1853 my $imap = Mail::IMAPClient->new(
1854 Server => $imaphost, User => $login, Password => $pass, Uid => 1
1855 );
1856 $imap->select("demo");
1858 my $msgs = $imap->search("ALL");
1860 for my $h (
1861 # get the Subject and Date from every message in folder "demo" the
1863 # first arg is a reference to an array listing all messages in the
1864 # folder (which is what gets returned by the $imap->search("ALL")
1865 # method when called in scalar context) and the remaining arguments
1866 # are the fields to parse out The key is the message number, which
1867 # in this case we don't care about:
1868 values %{ $imap->parse_headers( $msgs , "Subject", "Date") } )
1870 {
1871 # $h is the value of each element in the hash ref returned
1872 # from parse_headers, and $h is also a reference to a hash.
1873 # We'll only print the first occurrence of each field because
1874 # we don't expect more than one Date: or Subject: line per
1875 # message.
1876 print map { "$_:\t$h->{$_}[0]\n"} keys %$h;
1877 }
1878 recent
1880 Example:
1881 my @recent = $imap->recent or warn "No recent msgs: $@\n";
1883 The recent method performs an IMAP SEARCH RECENT search against the
1885 selected folder and returns an array of sequence numbers (or UID's, if
1886 the "Uid" parameter is true) of messages that are recent.
1887 recent_count
1889 Example:
1890 my $count = 0;
1892 defined($count = $imap->recent_count($folder))
1893 or die "Could not recent_count: $@\n";
1894 The recent_count method accepts as an argument a folder name. It
1896 returns the number of recent messages in the folder (as returned by the
1897 IMAP client command "STATUS folder RECENT"), or "undef" in the case of
1898 an error. The recent_count method was contributed by Rob Deker
1899 (deker@ikimbo.com).
1900 noop
1902 Example:
1903 $imap->noop or die "noop failed: $@\n";
1905 The noop method performs an IMAP NOOP command. Per RFC3501 this
1907 command does nothing and always succeeds. However, if a connection
1908 times out or other errors occur while communicating with the server,
1909 this method can still fail. This command can be used as a periodic
1910 poll to check for (untagged) status updates (new messages, etc.) from
1911 the server and also to reset any inactivity/auto-logout timers the
1912 server may maintain.
1913 reconnect
1915 Example:
1916 $imap->noop or $imap->reconnect or die "noop failed: $@\n";
1918 Attempt to reconnect if the IMAP connection unless $imap is already in
1920 the IsConnected state. This method calls "connect" and optionally
1921 "select" if a Folder was previously selected. On success, returns the
1922 (same) $imap object. On failure <undef> is returned and "LastError" is
1923 set.
1924 Version note: method added in Mail::IMAPClient 3.17
1926 rename
1928 Example:
1929 $imap->rename($oldname,$nedwname)
1931 or die "Could not rename: $@\n";
1932 The rename method accepts two arguments: the name of an existing
1934 folder, and a new name for the folder. The existing folder will be
1935 renamed to the new name using the RENAME IMAP client command. rename
1936 will return a true value if successful, or "undef" if unsuccessful.
1937 restore_message
1939 Example:
1940 $imap->restore_message(@msgs) or die "Could not restore_message: $@\n";
1942 The restore_message method is used to undo a previous "delete_message"
1944 operation (but not if there has been an intervening "expunge" or
1945 "close"). The IMAPClient object must be in "Selected" status to use
1946 the restore_message method.
1947 The restore_message method accepts a list of arguments. If the "Uid"
1949 parameter is not set to a true value, then each item in the list should
1950 be either:
1951 > a message sequence number,
1953 > a comma-separated list of message sequence numbers,
1955 > a reference to an array of message sequence numbers, or
1957 If the "Uid" parameter is set to a true value, then each item in the
1959 list should be either:
1960 > a message UID,
1962 > a comma-separated list of UID's, or
1964 > a reference to an array of message UID's.
1966 The messages identified by the sequence numbers or UID's will have
1968 their \Deleted flags cleared, effectively "undeleting" the messages.
1969 restore_message returns the number of messages it was able to restore.
1970 Note that restore_messages is similar to calling
1972 ""unset_flag"("\Deleted",@msgs)", except that restore_messages returns
1973 a (slightly) more meaningful value. Also it's easier to type.
1974 run
1976 Example:
1977 $imap->run(@args) or die "Could not run: $@\n";
1979 The run method is provided to make those uncommon things possible...
1981 however, we would like you to contribute the knowledge of missing
1982 features with us.
1983 The run method excepts one or two arguments. The first argument is a
1985 string containing an IMAP Client command, including a tag and all
1986 required arguments. The optional second argument is a string to look
1987 for that will indicate success. (The default is "/OK.*/"). The run
1988 method returns an array (or arrayref in scalar context) of output lines
1989 from the command, which you are free to parse as you see fit.
1990 The run method does not do any syntax checking, other than rudimentary
1992 checking for a tag.
1993 When run processes the command, it increments the transaction count and
1995 saves the command and responses in the History buffer in the same way
1996 other commands do. However, it also creates a special entry in the
1997 History buffer named after the tag supplied in the string passed as the
1998 first argument. If you supply a numeric value as the tag then you may
1999 risk overwriting a previous transaction's entry in the History buffer.
2000 If you want the control of run but you don't want to worry about tags
2002 then see "tag_and_run", below.
2003 search
2005 Example:
2006 my $msgs1 = $imap->search(@args);
2008 if ($msgs) {
2009 print "search matches: @$msgs1";
2010 }
2011 else {
2012 warn "Error in search: $@\n" if $@;
2013 }
2014 # or note: be sure to quote string properly
2016 my $msgs2 = $imap->search( \( $imap->Quote($msgid), "FROM", q{"me"} ) )
2017 or warn "search failed: $@\n";
2018 # or note: be sure to quote string properly
2020 my $msgs3 = $imap->search('TEXT "string not in mailbox"')
2021 or warn "search failed: $@\n";
2022 The search method implements the SEARCH IMAP client command. Any
2024 arguments supplied to search are prefixed with a space then appended to
2025 the SEARCH IMAP client command. The SEARCH IMAP client command allows
2026 for many options and arguments. See RFC3501 for details.
2027 As of version 3.17 search tries to "DWIM" by automatically quoting
2029 things that likely need quotes when the words do not match any of the
2030 following:
2031 ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED
2033 FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
2034 SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
2035 TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
2036 UNKEYWORD UNSEEN
2037 The following options exist to avoid the automatic quoting (note:
2039 caller is responsible for verifying the data sent in these cases is
2040 properly escaped/quoted):
2041 · specify a single string/argument in the call to search.
2043 · specify args as scalar references (SCALAR) and the values of those
2045 SCALAR refs will be passed along as-is.
2046 The search method returns an array containing sequence numbers of
2048 messages that passed the SEARCH IMAP client command's search criteria.
2049 If the "Uid" parameter is true then the array will contain message
2050 UID's. If search is called in scalar context then a pointer to the
2051 array will be passed, instead of the array itself. If no messages meet
2052 the criteria then search returns an empty list (when in list context)
2053 or "undef" (in scalar context).
2054 Since a valid, successful search can legitimately return zero matches,
2056 you may wish to distinguish between a search that correctly returns
2057 zero hits and a search that has failed for some other reason (i.e.
2058 invalid search parameters). Therefore, the $@ variable will always be
2059 cleared before the SEARCH command is issued to the server, and will
2060 thus remain empty unless the server gives a BAD or NO response to the
2061 SEARCH command.
2062 see
2064 Example:
2065 $imap->see(@msgs) or die "Could not see: $@\n";
2067 The see method accepts a list of one or more messages sequence numbers,
2069 or a single reference to an array of one or more message sequence
2070 numbers, as its argument(s). It then sets the \Seen flag for those
2071 message(s). Of course, if the "Uid" parameter is set to a true value
2072 then those message sequence numbers had better be unique message id's,
2073 but then you already knew that, didn't you?
2074 Note that specifying "$imap->see(@msgs)" is just a shortcut for
2076 specifying "$imap->"set_flag"("Seen",@msgs)".
2077 seen
2079 Example:
2080 my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
2082 The seen method performs an IMAP SEARCH SEEN search against the
2084 selected folder and returns an array of sequence numbers of messages
2085 that have already been seen (ie their \Seen flag is set). If the "Uid"
2086 parameter is true then an array of message UID's will be returned
2087 instead. If called in scalar context than a reference to the array
2088 (rather than the array itself) will be returned.
2089 select
2091 Example:
2092 $imap->select($folder) or die "Could not select: $@\n";
2094 The select method selects a folder and changes the object's state to
2096 Selected. It accepts one argument, which is the name of the folder to
2097 select.
2098 selectable
2100 Example:
2101 foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
2103 $imap->select($f);
2104 }
2105 The selectable method accepts one value, a folder name, and returns
2107 true if the folder is selectable or false if it is not selectable.
2108 sentbefore
2110 Example:
2111 my @msgs = $imap->sentbefore($Rfc3501_date)
2113 or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
2114 The sentbefore method works just like "sentsince", below, except it
2116 searches for messages that were sent before the date supplied as an
2117 argument to the method.
2118 senton
2120 Example:
2121 my @msgs = $imap->senton($Rfc3501_date)
2123 or warn "Could not find any messages sent on $Rfc3501_date: $@\n";
2124 The senton method works just like "sentsince", below, except it
2126 searches for messages that were sent on the exact date supplied as an
2127 argument to the method.
2128 sentsince
2130 Example:
2131 my @msgs = $imap->sentsince($Rfc3501_date)
2133 or warn "Could not find any messages sent since $Rfc3501_date: $@\n";
2134 The sentsince method accepts one argument, a date in either epoch time
2136 format (seconds since 1/1/1970, or as output by time and as accepted by
2137 localtime) or in the date_text format as defined in RFC3501 (dd-Mon-
2138 yyyy, where Mon is the English-language three-letter abbreviation for
2139 the month).
2140 It searches for items in the currently selected folder for messages
2142 sent since the day whose date is provided as the argument. It uses the
2143 RFC822 Date: header to determine the sentsince date. (Actually, it the
2144 server that uses the Date: header; this documentation just assumes that
2145 the date is coming from the Date: header because that's what RFC3501
2146 dictates.)
2147 In the case of arguments supplied as a number of seconds, the returned
2149 result list will include items sent on or after that day, regardless of
2150 whether they arrived before the specified time on that day. The IMAP
2151 protocol does not support searches at a granularity finer than a day,
2152 so neither do I. On the other hand, the only thing I check for in a
2153 date_text argument is that it matches the pattern
2154 "/\d\d-\D\D\D-\d\d\d\d/" (notice the lack of anchors), so if your
2155 server lets you add something extra to a date_text string then so will
2156 Mail::IMAPClient.
2157 If you'd like, you can use the "Rfc3501_date" method to convert from
2159 epoch time (as returned by time) into an RFC3501 date specification.
2160 separator
2162 Example:
2163 my $sepChar = $imap->separator(@args)
2165 or die "Could not get separator: $@\n";
2166 The separator method returns the character used as a separator
2168 character in folder hierarchies. On UNIX-based servers, this is often
2169 but not necessarily a forward slash (/). It accepts one argument, the
2170 name of a folder whose hierarchy's separator should be returned. If no
2171 folder name is supplied then the separator for the INBOX is returned,
2172 which probably is good enough.
2173 If you want your programs to be portable from IMAP server brand X to
2175 IMAP server brand Y, then you should never use hard-coded separator
2176 characters to specify subfolders. (In fact, it's even more complicated
2177 than that, since some server don't allow any subfolders at all, some
2178 only allow subfolders under the "INBOX" folder, and some forbid
2179 subfolders in the inbox but allow them "next" to the inbox.
2180 Furthermore, some server implementations do not allow folders to
2181 contain both subfolders and mail messages; other servers allow this.)
2182 set_flag
2184 Example:
2185 $imap->set_flag( "Seen", @msgs )
2187 or die "Could not set flag: $@\n";
2188 The set_flag method accepts the name of a flag as its first argument
2190 and a list of one or more messages sequence numbers, or a single
2191 reference to an array of one or more message sequence numbers, as its
2192 next argument(s). It then sets the flag specified for those
2193 message(s). Of course, if the "Uid" parameter is set to a true value
2194 then those message sequence numbers had better be unique message id's,
2195 just as you'd expect.
2196 Note that when specifying the flag in question, the preceding backslash
2198 (\) is entirely optional. (For you, that is. Mail::IMAPClient still
2199 has remember to stick it in there before passing the command to the
2200 server if the flag is one of the reserved flags specified in RFC3501.
2201 This is in fact so important that the method checks its argument and
2202 adds the backslash when necessary, which is why you don't have to worry
2203 about it overly much.)
2204 setacl
2206 Example:
2207 $imap->setacl( $folder, $userid, $aclstring )
2209 or die "Could not set acl: $@\n";
2210 The setacl method accepts three input arguments, a folder name, a user
2212 id (or authentication identifier, to use the terminology of RFC2086),
2213 and an access rights modification string. See RFC2086 for more
2214 information. (This is somewhat experimental and its implementation may
2215 change.)
2216 since
2218 Example:
2219 my @msgs = $imap->since($date)
2221 or warn "Could not find any messages since $date: $@\n";
2222 The since method accepts a date in either epoch format (seconds since
2224 1/1/1970, or as output by "time" in perlfunc and as accepted by
2225 "localtime" in perlfunc) or in the date_text format as defined in
2226 RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter
2227 abbreviation for the month). It searches for items in the currently
2228 selected folder for messages whose internal dates are on or after the
2229 day whose date is provided as the argument. It uses the internal
2230 system date for a message to determine if that message was sent since
2231 the given date.
2232 In the case of arguments supplied as a number of seconds, the returned
2234 result list will include items whose internal date is on or after that
2235 day, regardless of whether they arrived before the specified time on
2236 that day.
2237 If since is called in a list context then it will return a list of
2239 messages meeting the SEARCH SINCE criterion, or an empty list if no
2240 messages meet the criterion.
2241 If since is called in a scalar context then it will return a reference
2243 to an array of messages meeting the SEARCH SINCE criterion, or "undef"
2244 if no messages meet the criterion.
2245 Since since is a front-end to "search", some of the same rules apply.
2247 For example, the $@ variable will always be cleared before the SEARCH
2248 command is issued to the server, and will thus remain empty unless the
2249 server gives a BAD or NO response to the SEARCH command.
2250 size
2252 Example:
2253 my $size = $imap->size($msgId)
2255 or die "Could not find size of message $msgId: $@\n";
2256 The size method accepts one input argument, a sequence number (or
2258 message UID if the "Uid" parameter is true). It returns the size of
2259 the message in the currently selected folder with the supplied sequence
2260 number (or UID). The IMAPClient object must be in a Selected state in
2261 order to use this method.
2262 sort
2264 Example:
2265 my @msgs = $imap->sort(@args);
2267 warn "Error in sort: $@\n" if $@;
2268 The sort method is just like the "search" method, only different. It
2270 implements the SORT extension as described in
2271 http://search.ietf.org/internet-drafts/draft-ietf-imapext-sort-10.txt.
2272 It would be wise to use the "has_capability" method to verify that the
2273 SORT capability is available on your server before trying to use the
2274 sort method. If you forget to check and you're connecting to a server
2275 that doesn't have the SORT capability then sort will return undef.
2276 "LastError" will then say you are "BAD". If your server doesn't
2277 support the SORT capability then you'll have to use "search" and then
2278 sort the results yourself.
2279 The first argument to sort is a space-delimited list of sorting
2281 criteria. The Internet Draft that describes SORT requires that this
2282 list be wrapped in parentheses, even if there is only one sort
2283 criterion. If you forget the parentheses then the sort method will add
2284 them. But you have to forget both of them, or none. This isn't CMS
2285 running under VM!
2286 The second argument is a character set to use for sorting. Different
2288 character sets use different sorting orders, so this argument is
2289 important. Since all servers must support UTF-8 and US-ASCII if they
2290 support the SORT capability at all, you can use one of those if you
2291 don't have some other preferred character set in mind.
2292 The rest of the arguments are searching criteria, just as you would
2294 supply to the "search" method. These are all documented in RFC3501.
2295 If you just want all of the messages in the currently selected folder
2296 returned to you in sorted order, use ALL as your only search criterion.
2297 The sort method returns an array containing sequence numbers of
2299 messages that passed the SORT IMAP client command's search criteria.
2300 If the "Uid" parameter is true then the array will contain message
2301 UID's. If sort is called in scalar context then a pointer to the array
2302 will be passed, instead of the array itself. The message sequence
2303 numbers or unique identifiers are ordered according to the sort
2304 criteria specified. The sort criteria are nested in the order
2305 specified; that is, items are sorted first by the first criterion, and
2306 within the first criterion they are sorted by the second criterion, and
2307 so on.
2308 The sort method will clear $@ before attempting the SORT operation just
2310 as the "search" method does.
2311 starttls
2313 Example:
2314 $imap->starttls() or die "starttls failed: $@\n";
2316 The starttls method accepts no arguments. This method is used to
2318 upgrade an exiting connection which is not authenticated to a TLS/SSL
2319 connection by using the IMAP STARTTLS command followed by using the
2320 start_SSL class method from IO::Socket::SSL to do the necessary TLS
2321 negotiation. The negotiation is done in a blocking fashion with a
2322 default Timeout of 30 seconds. The arguments used in the call to
2323 start_SSL can be controlled by setting the Mail::IMAPClient "Starttls"
2324 attribute to an ARRAY reference containing the desired arguments.
2325 Version note: method added in Mail::IMAPClient 3.22
2327 status
2329 Example:
2330 my @rawdata = $imap->status( $folder, qw/(Messages)/ )
2332 or die "Error obtaining status: $@\n";
2333 The status method accepts one argument, the name of a folder (or
2335 mailbox, to use RFC3501's terminology), and returns an array containing
2336 the results of running the IMAP STATUS client command against that
2337 folder. If additional arguments are supplied then they are appended to
2338 the IMAP STATUS client command string, separated from the rest of the
2339 string and each other with spaces.
2340 If status is not called in an array context then it returns a reference
2342 to an array rather than the array itself.
2343 The status method should not be confused with the Status method (with
2345 an uppercase 'S'), which returns information about the IMAPClient
2346 object. (See the section labeled "Status Methods", below).
2347 store
2349 Example:
2350 $imap->store(@args) or die "Could not store: $@\n";
2352 The store method accepts a message sequence number or comma-separated
2354 list of message sequence numbers as a first argument, a message data
2355 item name, and a value for the message data item. Currently, data
2356 items are the word "FLAGS" followed by a space and a list of flags (in
2357 parens). The word "FLAGS" can be modified by prefixing it with either
2358 a "+" or a "-" (to indicate "add these flags" or "remove these flags")
2359 and by suffixing it with ".SILENT" (which reduces the amount of output
2360 from the server; very useful with large message sets). Normally you
2361 won't need to call store because there are oodles of methods that will
2362 invoke store for you with the correct arguments. Furthermore, these
2363 methods are friendlier and more flexible with regards to how you
2364 specify your arguments. See for example "see", "deny_seeing",
2365 "delete_message", and "restore_message". Or "mark", "unmark",
2366 "set_flag", and "unset_flag".
2367 subject
2369 Example:
2370 my $subject = $imap->subject($msg);
2372 The subject method accepts one argument, a message sequence number (or
2374 a message UID, if the Uid parameter is true). The text in the
2375 "Subject" header of that message is returned (without the "Subject: "
2376 prefix). This method is a short-cut for:
2377 my $subject = $imap->get_header($msg, "Subject");
2379 subscribed
2381 Example:
2382 my @subscribedFolders = $imap->subscribed
2384 or warn "Could not find subscribed folders: $@\n";
2385 The subscribed method works like the folders method, above, except that
2387 the returned list (or array reference, if called in scalar context)
2388 contains only the subscribed folders.
2389 Like "folders", you can optionally provide a prefix argument to the
2391 subscribed method.
2392 tag_and_run
2394 Example:
2395 my $output = $imap->tag_and_run(@args)
2397 or die "Could not tag_and_run: $@\n";
2398 The tag_and_run method accepts one or two arguments. The first
2400 argument is a string containing an IMAP Client command, without a tag
2401 but with all required arguments. The optional second argument is a
2402 string to look for that will indicate success (without pattern
2403 delimiters). The default is "OK.*".
2404 The tag_and_run method will prefix your string (from the first
2406 argument) with the next transaction number and run the command. It
2407 returns an array of output lines from the command, which you are free
2408 to parse as you see fit. Using this method instead of run (above) will
2409 free you from having to worry about handling the tags (and from
2410 worrying about the side affects of naming your own tags).
2411 uidexpunge
2413 Example:
2414 $imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";
2416 The uidexpunge method implements the UID EXPUNGE IMAP (RFC4315 UIDPLUS
2418 ext) client command to permanently remove all messages that have the
2419 \Deleted flag set and have a UID that is included in the list of UIDs.
2420 uidexpunge returns an array or arrayref (scalar context) of output
2422 lines returned from the UID EXPUNGE command.
2423 uidexpunge returns undef on failure.
2425 If the server does not support the UIDPLUS extension, this method
2427 returns undef.
2428 uidnext
2430 Example:
2431 my $nextUid = $imap->uidnext($folder) or die "Could not uidnext: $@\n";
2433 The uidnext method accepts one argument, the name of a folder, and
2435 returns the numeric string that is the next available message UID for
2436 that folder.
2437 thread
2439 Example:
2440 my $thread = $imap->thread($algorithm, $charset, @search_args );
2442 The thread method accepts zero to three arguments. The first argument
2444 is the threading algorithm to use, generally either ORDEREDSUBJECT or
2445 REFERENCES. The second argument is the character set to use, and the
2446 third argument is the set of search arguments to use.
2447 If the algorithm is not supplied, it defaults to REFERENCES if
2449 available, or ORDEREDSUBJECT if available. If neither of these is
2450 available then the thread method returns undef.
2451 If the character set is not specified it will default to UTF-8.
2453 If the search arguments are not specified, the default is ALL.
2455 If thread is called for an object connected to a server that does not
2457 support the THREADS extension then the thread method will return
2458 "undef".
2459 The threads method will issue the THREAD command as defined in
2461 http://www.ietf.org/internet-drafts/draft-ietf-imapext-thread-11.txt.
2462 It returns an array of threads. Each element in the array is either a
2463 message id or a reference to another array of (sub)threads.
2464 If the "Uid" parameter is set to a true value then the message id's
2466 returned in the thread structure will be message UID's. Otherwise they
2467 will be message sequence numbers.
2468 uidvalidity
2470 Example:
2471 my $validity = $imap->uidvalidity($folder)
2473 or die "Could not uidvalidity: $@\n";
2474 The uidvalidity method accepts one argument, the name of a folder, and
2476 returns the numeric string that is the unique identifier validity value
2477 for the folder.
2478 unmark
2480 Example:
2481 $imap->unmark(@msgs) or die "Could not unmark: $@\n";
2483 The unmark method accepts a list of one or more messages sequence
2485 numbers, or a single reference to an array of one or more message
2486 sequence numbers, as its argument(s). It then unsets the \Flagged flag
2487 for those message(s). Of course, if the "Uid" parameter is set to a
2488 true value then those message sequence numbers should really be unique
2489 message id's.
2490 Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
2492 specifying "$imap->unset_flag("Flagged",@msgs)".
2493 Note also that the \Flagged flag is just one of many possible flags.
2495 This is a little confusing, but you'll have to get used to the idea
2496 that among the reserved flags specified in RFC3501 is one name
2497 \Flagged. There is no specific meaning for this flag; it means
2498 whatever the mailbox owner (or delegate) wants it to mean when it is
2499 turned on.
2500 unseen
2502 Example:
2503 my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
2505 The unseen method performs an IMAP SEARCH UNSEEN search against the
2507 selected folder and returns an array of sequence numbers of messages
2508 that have not yet been seen (ie their \Seen flag is not set). If the
2509 "Uid" parameter is true then an array of message UID's will be returned
2510 instead. If called in scalar context than a pointer to the array
2511 (rather than the array itself) will be returned.
2512 Note that when specifying the flag in question, the preceding backslash
2514 (\) is entirely optional.
2515 unseen_count
2517 Example:
2518 foreach my $f ($imap->folders) {
2520 print "The $f folder has ",
2521 $imap->unseen_count($f)||0, " unseen messages.\n";
2522 }
2523 The unseen_count method accepts the name of a folder as an argument and
2525 returns the number of unseen messages in that folder. If no folder
2526 argument is provided then it returns the number of unseen messages in
2527 the currently selected Folder.
2528 unset_flag
2530 Example:
2531 $imap->unset_flag( "\Seen", @msgs )
2533 or die "Could not unset_flag: $@\n";
2534 The unset_flag method accepts the name of a flag as its first argument
2536 and a list of one or more messages sequence numbers, or a single
2537 reference to an array of one or more message sequence numbers, as its
2538 next argument(s). It then unsets the flag specified for those
2539 message(s). Of course, if the "Uid" parameter is set to a true value
2540 then those message sequence numbers had better be unique message id's,
2541 just as you'd expect.
2542
2544 Until release 2.99, when you called a method which did not exist, they
2545 where automatically translated into an IMAP call with the same name via
2546 an AUTOLOAD hack. This "feature" was removed for various reasons:
2547 people made typos in the capitalization of method names, and the
2548 program still seemed to work correctly. Besides, it blocked further
2549 development of this module, because people did not contribute their
2550 private extensions to the protocol implementation.
2551 copy($msg, $folder)
2553 Copy a message from the currently selected folder in the folder whose
2554 name is in $folder
2555 subscribe($folder)
2557 Subscribe to a folder
2558 CAUTION: Once again, remember to quote your quotes (or use the "Quote"
2560 method) if you want quotes to be part of the IMAP command string.
2561 You can also use the default method to override the behavior of
2563 implemented IMAP methods by changing the case of the method name,
2564 preferably to all-uppercase so as not to conflict with the Class method
2565 and accessor method namespace. For example, if you don't want the
2566 "search" method's behavior (which returns a list of message numbers)
2567 but would rather have an array of raw data returned from your "search"
2568 operation, you can issue the following snippet:
2569 my @raw = $imap->SEARCH("SUBJECT","Whatever...");
2571 which is slightly more efficient than the equivalent:
2573 $imap->search("SUBJECT","Whatever...");
2575 my @raw = $imap->Results;
2576 Of course you probably want the search results tucked nicely into a
2578 list for you anyway, in which case you might as well use the "search"
2579 method.
2580
2582 There are several parameters that influence the behavior of an
2583 IMAPClient object. Each is set by specifying a named value pair during
2584 new method invocation as follows:
2585 my $imap = Mail::IMAPClient->new ( parameter => "value",
2587 parameter2 => "value",
2588 ...
2589 );
2590 Parameters can also be set after an object has been instantiated by
2592 using the parameter's eponymous accessor method like this:
2593 my $imap = Mail::IMAPClient->new;
2595 $imap->parameter( "value");
2596 $imap->parameter2("value");
2597 The eponymous accessor methods can also be used without arguments to
2599 obtain the current value of the parameter as follows:
2600 my $imap = Mail::IMAPClient->new;
2602 $imap->parameter( "value");
2603 $imap->parameter2("value");
2604 ... # A whole bunch of awesome Perl code, omitted for brevity
2606 my $forgot = $imap->parameter;
2608 my $forgot2 = $imap->parameter2;
2609 Note that in these examples I'm using 'parameter' and 'parameter2' as
2611 generic parameter names. The IMAPClient object doesn't actually have
2612 parameters named 'parameter' and 'parameter2'. On the contrary, the
2613 available parameters are:
2614 Authmechanism
2616 Example:
2617 $imap->Authmechanism("CRAM-MD5");
2619 # or
2620 my $authmech = $imap->Authmechanism();
2621 If specified, the Authmechanism causes the specified authentication
2623 mechanism to be used whenever Mail::IMAPClient would otherwise invoke
2624 login. If the value specified for the Authmechanism parameter is not a
2625 valid authentication mechanism for your server then you will never ever
2626 be able to log in again for the rest of your Perl script, probably. So
2627 you might want to check, like this:
2628 my $authmech = "CRAM-MD5";
2630 $imap->has_capability($authmech) and $imap->Authmechanism($authmech);
2631 Of course if you know your server supports your favorite authentication
2633 mechanism then you know, so you can then include your Authmechanism
2634 with your new call, as in:
2635 my $imap = Mail::IMAPClient->new(
2637 User => $user,
2638 Passord => $passord,
2639 Server => $server,
2640 Authmechanism => $authmech,
2641 %etc
2642 );
2643 If Authmechanism is supplied but Authcallback is not then you had
2645 better be supporting one of the authentication mechanisms that
2646 Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2647 Authcallback
2649 Example:
2650 $imap->Authcallback( \&callback );
2652 This specifies a default callback to the default authentication
2654 mechanism (see "Authmechanism", above). Together, these two methods
2655 replace automatic calls to login with automatic calls that look like
2656 this (sort of):
2657 $imap->authenticate($imap->Authmechanism,$imap->Authcallback);
2659 If Authmechanism is supplied but Authcallback is not then you had
2661 better be supporting one of the authentication mechanisms that
2662 Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2663 Authuser
2665 The Authuser parameter is used by the DIGEST-MD5 "Authmechanism".
2666 Typically when you authenticate the username specified in the User
2668 parameter is used. However, when using the DIGEST-MD5 Authmechanism
2669 the Authuser can be used to specify a different username for the login.
2670 This can be useful to mark messages as seen for the Authuser if you
2672 don't know the password of the user as the seen state is often a per-
2673 user state.
2674 Buffer
2676 Example:
2677 $Buffer = $imap->Buffer();
2679 # or:
2680 $imap->Buffer($new_value);
2681 The Buffer parameter sets the size of a block of I/O. It is ignored
2683 unless "Fast_io", below, is set to a true value (the default), or
2684 unless you are using the "migrate" method. It's value should be the
2685 number of bytes to attempt to read in one I/O operation. The default
2686 value is 4096.
2687 When using the "migrate" method, you can often achieve dramatic
2689 improvements in throughput by adjusting this number upward. However,
2690 doing so also entails a memory cost, so if set too high you risk losing
2691 all the benefits of the "migrate" method's chunking algorithm. Your
2692 program can thus terminate with an "out of memory" error and you'll
2693 have no one but yourself to blame.
2694 Note that, as hinted above, the Buffer parameter affects the behavior
2696 of the "migrate" method regardless of whether you have "Fast_io" turned
2697 on. Believe me, you don't want to go around migrating tons of mail
2698 without using buffered I/O!
2699 Clear
2701 Example:
2702 $Clear = $imap->Clear();
2704 # or:
2705 $imap->Clear($integer);
2706 The name of this parameter, for historical reasons, is somewhat
2708 misleading. It should be named Wrap, because it specifies how many
2709 transactions are stored in the wrapped history buffer. But it didn't
2710 always work that way; the buffer used to actually get cleared. The
2711 name though remains the same in the interests of backwards
2712 compatibility.
2713 Clear specifies that the object's history buffer should be wrapped
2715 after every n transactions, where n is the value specified for the
2716 Clear parameter. Calling the eponymous Clear method without an
2717 argument will return the current value of the Clear parameter but will
2718 not cause clear the history buffer to wrap.
2719 Setting Clear to 0 turns off automatic history buffer wrapping, and
2721 setting it to 1 turns off the history buffer facility (except for the
2722 last transaction, which cannot be disabled without breaking the
2723 IMAPClient module). Setting Clear to 0 will not cause an immediate
2724 clearing of the history buffer; setting it to 1 (or any other number)
2725 will (except of course for that inevitable last transaction).
2726 The default Clear value is set to five (5) in order to conserve memory.
2728 Compress
2730 If set, Mail::IMAPClient attempts to enable use of the RFC4978 COMPRESS
2731 DEFLATE extension. This requires that the server supports this
2732 CAPABILITY. This attribute can be set to a true value to enable or an
2733 ARRAYREF to control the arguments used in the call to
2734 Compress::Zlib::deflateInit().
2735 Mail::IMAPClient will automatically use Compress::Zlib to
2737 deflate/inflate the data to/from the server. This attribute is used in
2738 the "login" method.
2739 See also "compress" and "capability".
2741 Version note: attribute added in Mail::IMAPClient 3.30
2743 Debug
2745 Example:
2746 $Debug = $imap->Debug();
2748 # or:
2749 $imap->Debug($true_or_false);
2750 Sets the debugging flag to either a true or false value. Can be
2752 supplied with the "new" method call or separately by calling the Debug
2753 object method. Use of this parameter is strongly recommended when
2754 debugging scripts and required when reporting bugs.
2755 Debug_fh
2757 Example:
2758 $Debug_fh = $imap->Debug_fh();
2760 # or:
2761 $imap->Debug_fh($fileHandle);
2762 Specifies the file handle to which debugging information should be
2764 printed. It can either a file handle object reference or a file handle
2765 glob. The default is to print debugging info to STDERR.
2766 For example, you can:
2768 use Mail::IMAPClient;
2770 use IO::File;
2771 # set $user, $pass, and $server here
2772 my $dh = IO::File->new(">debugging.output")
2773 or die "Can't open debugging.output: $!\n";
2774 my $imap = Mail::IMAPClient->new(
2775 User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh
2776 );
2777 which is the same as:
2779 use Mail::IMAPClient;
2781 use IO::File;
2782 # set $user, $pass, and $server here
2783 my $imap = Mail::IMAPClient->new(
2784 User => $user,
2785 Password => $pass,
2786 Server => $server,
2787 Debug => "yes, please",
2788 Debug_fh => IO::File->new(">debugging.output")
2789 || die "Can't open debugging.output: $!\n"
2790 );
2791 You can also:
2793 use Mail::IMAPClient;
2795 # set $user, $pass, and $server here
2796 open(DBG,">debugging.output")
2797 or die "Can't open debugging.output: $!\n";
2798 my $imap = Mail::IMAPClient->new(
2799 User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG
2800 );
2801 Specifying this parameter is not very useful unless "Debug" is set to a
2803 true value.
2804 Domain
2806 The Domain parameter is used by the NTLM "Authmechanism". The domain
2807 is an optional parameter for NTLM authentication.
2808 EnableServerResponseInLiteral
2810 Removed in 2.99_01 (now autodetect)
2811 Fast_io
2813 Example:
2814 $Fast_io = $imap->Fast_io();
2816 # or:
2817 $imap->Fast_io($true_or_false);
2818 The Fast_io parameter controls whether or not the Mail::IMAPClient
2820 object will attempt to use non-blocking I/O on the IMAP socket. It is
2821 turned on by default (unless the caller provides the socket to be
2822 used).
2823 See also "Buffer".
2825 Folder
2827 Example:
2828 $Folder = $imap->Folder();
2830 # or:
2831 $imap->Folder($new_value);
2832 The Folder parameter returns the name of the currently-selected folder
2834 (in case you forgot). It can also be used to set the name of the
2835 currently selected folder, which is completely unnecessary if you used
2836 the "select" method (or "select"'s read-only equivalent, the "examine"
2837 method) to select it.
2838 Note that setting the Folder parameter does not automatically select a
2840 new folder; you use the "select" or "examine" object methods for that.
2841 Generally, the Folder parameter should only be queried (by using the
2842 no-argument form of the Folder method). You will only need to set the
2843 Folder parameter if you use some mysterious technique of your own for
2844 selecting a folder, which you probably won't do.
2845 Ignoresizeerrors
2847 Certain (caching) servers, like Exchange 2007, often report the wrong
2848 message size. Instead of chopping the message into a size that it fits
2849 the specified size, the reported size will be simply ignored when this
2850 parameter is set to 1.
2851 Keepalive
2853 Some firewalls and network gear like to timeout connections prematurely
2854 if the connection sits idle. The Keepalive parameter, when set to a
2855 true value, affects the behavior of "new" and "Socket" by enabling
2856 SO_KEEPALIVE on the socket.
2857 Version note: attribute added in Mail::IMAPClient 3.17
2859 Maxcommandlength
2861 The Maxcommandlength attribute is used by fetch() to limit length of
2862 commands sent to a server. The default is 1000 chars, following the
2863 recommendation of RFC2683 section 3.2.1.5.
2864 Note: this attribute should also be used for several other methods but
2866 this has not yet been implemented please feel free to file bugs for
2867 methods where you run into problems with this.
2868 This attribute should remove the need for utilities like imapsync to
2870 create their own split() functions and instead allows Mail::IMAPClient
2871 to DWIM.
2872 In practice, this parameter has proven to be useful to overcome a limit
2874 of 8000 octets for UW-IMAPD and 16384 octets for Courier/Cyrus IMAP
2875 servers.
2876 Version note: attribute added in Mail::IMAPClient 3.17
2878 Maxtemperrors
2880 Example:
2881 $Maxtemperrors = $imap->Maxtemperrors();
2883 # or:
2884 $imap->Maxtemperrors($number);
2885 The Maxtemperrors parameter specifies the number of times a read or
2887 write operation is allowed to fail on a "Resource Temporarily
2888 Available" (e.g. EAGAIN) error. The default setting is undef which
2889 means there is no limit.
2890 Setting this parameter to the string "unlimited" (instead of undef) to
2892 ignore "Resource Temporarily Unavailable" errors is deprecated.
2893 Note: This setting should be used with caution and may be removed in a
2895 future release. Setting this can cause methods to return to the caller
2896 before data is received (and then handled) properly thereby possibly
2897 then leaving the module in a bad state. In the future, this behavior
2898 may be changed in an attempt to avoid this situation.
2899 Password
2901 Example:
2902 $Password = $imap->Password();
2904 # or:
2905 $imap->Password($new_value);
2906 Specifies the password to use when logging into the IMAP service on the
2908 host specified in the Server parameter as the user specified in the
2909 User parameter. Can be supplied with the new method call or separately
2910 by calling the Password object method.
2911 If Server, User, and Password are all provided to the "new" method,
2913 then the newly instantiated object will be connected to the host
2914 specified in Server (at either the port specified in Port or the
2915 default port 143) and then logged on as the user specified in the User
2916 parameter (using the password provided in the Password parameter). See
2917 the discussion of the "new" method, below.
2918 Peek
2920 Example:
2921 $Peek = $imap->Peek();
2923 # or:
2924 $imap->Peek($true_or_false);
2925 Setting Peek to a true value will prevent the "body_string",
2927 "message_string" and "message_to_file" methods from automatically
2928 setting the \Seen flag. Setting "Peek" to 0 (zero) will force
2929 "body_string", "message_string", "message_to_file", and "parse_headers"
2930 to always set the \Seen flag.
2931 The default is to set the seen flag whenever you fetch the body of a
2933 message but not when you just fetch the headers. Passing undef to the
2934 eponymous Peek method will reset the Peek parameter to its pristine,
2935 default state.
2936 Port
2938 Example:
2939 $Port = $imap->Port();
2941 # or:
2942 $imap->Port($new_value);
2943 Specifies the port on which the IMAP server is listening. A default
2945 value of 993 (if "Ssl" is true) or 143 is set during a call to
2946 "connect" if no value is provided by the caller. This argument can be
2947 supplied with the "new" method call or separately by calling the "Port"
2948 object method.
2949 Prewritemethod
2951 Prewritemethod parameter should contain a reference to a subroutine
2952 that will do "special things" to data before it is sent to the IMAP
2953 server (such as encryption or signing).
2954 This method will be called immediately prior to sending an IMAP client
2956 command to the server. Its first argument is a reference to the
2957 Mail::IMAPClient object and the second argument is a string containing
2958 the command that will be sent to the server. Your Prewritemethod
2959 should return a string that has been signed or encrypted or whatever;
2960 this returned string is what will actually be sent to the server.
2961 Your Prewritemethod will probably need to know more than this to do
2963 whatever it does. It is recommended that you tuck all other pertinent
2964 information into a hash, and store a reference to this hash somewhere
2965 where your method can get to it, possibly in the Mail::IMAPClient
2966 object itself.
2967 Note that this method should not actually send anything over the socket
2969 connection to the server; it merely converts data prior to sending.
2970 See also "Readmethod".
2972 Ranges
2974 Example:
2975 $imap->Ranges(1);
2977 # or:
2978 my $search = $imap->search(@search_args);
2979 if ( $imap->Ranges) { # $search is a MessageSet object
2980 print "This is my condensed search result: $search\n";
2981 print "This is every message in the search result: ",
2982 join(",",@$search),"\n;
2983 }
2984 If set to a true value, then the "search" method will return a
2986 Mail::IMAPClient::MessageSet object if called in a scalar context,
2987 instead of the array reference that fetch normally returns when called
2988 in a scalar context. If set to zero or if undefined, then search will
2989 continue to return an array reference when called in scalar context.
2990 This parameter has no affect on the search method when search is called
2992 in a list context.
2993 RawSocket
2995 Example:
2996 $socket = $imap->RawSocket;
2997 # or:
2998 $imap->RawSocket($socketh);
2999 The RawSocket method can be used to obtain the socket handle of the
3001 current connection (say, to do I/O on the connection that is not
3002 otherwise supported by Mail::IMAPClient) or to replace the current
3003 socket with a new handle (for instance an SSL handle, see
3004 IO::Socket::SSL, but be sure to see the "Socket" method as well).
3005 If you supply a socket handle yourself, either by doing something like:
3007 $imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
3009 or by doing something like:
3011 $imap = Mail::IMAPClient->new(User => $user,
3013 Password => $pass, Server => $host);
3014 # blah blah blah
3015 $imap->RawSocket($ssl);
3016 then it will be up to you to establish the connection AND to
3018 authenticate, either via the "login" method, or the fancier
3019 "authenticate", or, since you know so much anyway, by just doing raw
3020 I/O against the socket until you're logged in. If you do any of this
3021 then you should also set the "State" parameter yourself to reflect the
3022 current state of the object (i.e. Connected, Authenticated, etc).
3023 Note that no operation will be attempted on the socket when this method
3025 is called. In particular, after the TCP connections towards the IMAP
3026 server is established, the protocol mandates the server to send an
3027 initial greeting message, and you will have to explicitly cope with
3028 this message before doing any other operation, e.g. trying to call
3029 "login". Caveat emptor.
3030 For a more DWIM approach to setting the socket see "Socket".
3032 Readmethod
3034 Example:
3035 $imap->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET
3037 sub {
3038 my ( $self, $handle, $buffer, $count, $offset ) = @_;
3039 my $rc = sysread( $handle, $$buffer, $count, $offset );
3040 # do something useful here...
3041 }
3042 );
3043 Readmethod should contain a reference to a subroutine that will replace
3045 sysread. The subroutine will be passed the following arguments: first
3046 the used Mail::IMAPClient object. Second, a reference to a socket.
3047 Third, a reference to a scalar variable into which data is read
3048 (BUFFER). The data placed here should be "finished data", so if you are
3049 decrypting or removing signatures then be sure to do that before you
3050 place data into this buffer. Fourth, the number of bytes requested to
3051 be read; the LENGTH of the request. Lastly, the OFFSET into the BUFFER
3052 where the data should be read. If not supplied it should default to
3053 zero.
3054 Note that this method completely replaces reads from the connection to
3056 the server, so if you define one of these then your subroutine will
3057 have to actually do the read. It is for things like this that we have
3058 the "Socket" parameter and eponymous accessor method.
3059 Your Readmethod will probably need to know more than this to do
3061 whatever it does. It is recommended that you tuck all other pertinent
3062 information into a hash, and store a reference to this hash somewhere
3063 where your method can get to it, possibly in the Mail::IMAPClient
3064 object itself.
3065 See also "Prewritemethod".
3067 Readmoremethod
3069 Readmoremethod should contain a reference to a subroutine that will
3070 replace/enhance the behavior of the internal _read_more() method. The
3071 subroutine will be passed the following arguments: first the used
3072 Mail::IMAPClient object. Second, a reference to a socket. Third, a
3073 timeout value which is used as the timeout value for CORE::select() by
3074 default. Depending upon changes/features introduced by Readmethod
3075 changes may be required here.
3076 Version note: attribute added in Mail::IMAPClient 3.30
3078 Reconnectretry
3080 If an IMAP connection sits idle too long, the connection may be closed
3081 by the server or firewall, etc. The Reconnectretry parameter, when
3082 given a positive integer value, will cause Mail::IMAPClient to retrying
3083 IMAP commands up to X times when an EPIPE or ECONNRESET error occurs.
3084 This is disabled (0) by default.
3085 See also "Keepalive"
3087 Version note: attribute added in Mail::IMAPClient 3.17
3089 Server
3091 Example:
3092 $Server = $imap->Server();
3094 # or:
3095 $imap->Server($hostname);
3096 Specifies the hostname or IP address of the host running the IMAP
3098 server. If provided as part of the "new" method call, then the new
3099 IMAP object will automatically be connected at the time of
3100 instantiation. (See the "new" method, below.) Can be supplied with the
3101 "new" method call or separately by calling the Server object method.
3102 Showcredentials
3104 Normally debugging output will mask the login credentials when the
3105 plain text login mechanism is used. Setting Showcredentials to a true
3106 value will suppress this, so that you can see the string being passed
3107 back and forth during plain text login. Only set this to true when you
3108 are debugging problems with the IMAP LOGIN command, and then turn it
3109 off right away when you're finished working on that problem.
3110 Example:
3112 print "This is very risky!\n" if $imap->Showcredentials();
3114 # or:
3115 $imap->Showcredentials(0); # mask credentials again
3116 Socket
3118 PLEASE NOTE The semantics of this method has changed as of version
3119 2.99_04 of this module. If you need the old semantics use "RawSocket".
3120 Example:
3122 $Socket = $imap->Socket();
3124 # or:
3125 $imap->Socket($socket_fh);
3126 The Socket method can be used to obtain the socket handle of the
3128 current connection. This may be necessary to do I/O on the connection
3129 that is not otherwise supported by Mail::IMAPClient) or to replace the
3130 current socket with a new handle (for instance an SSL handle, see
3131 IO::Socket::SSL).
3132 If you supply a socket handle yourself, either by doing something like:
3134 $imap = Mail::IMAPClient->new( Socket => $sock, User => ... );
3136 or by doing something like:
3138 $imap = Mail::IMAPClient->new(
3140 User => $user, Password => $pass, Server => $host
3141 );
3142 $imap->Socket($ssl);
3143 then you are responsible for establishing the connection, i.e. make
3145 sure that $ssl in the example is a valid and connected socket.
3146 This method is primarily used to provide a drop-in replacement for
3148 IO::Socket::INET, used by "connect" by default. In fact, this method
3149 is called by "connect" itself after having established a suitable
3150 IO::Socket::INET socket connection towards the target server; for this
3151 reason, this method also carries the normal operations associated with
3152 "connect", namely:
3153 · read the initial greeting message from the server;
3155 · call "login" if the conditions apply (see "connect" for details);
3157 · leave the Mail::IMAPClient object in a suitable state.
3159 For these reasons, the following example will work "out of the box":
3161 use IO::Socket::SSL;
3163 my $imap = Mail::IMAPClient->new
3164 ( User => 'your-username',
3165 Password => 'your-password',
3166 Socket => IO::Socket::SSL->new
3167 ( Proto => 'tcp',
3168 PeerAddr => 'some.imap.server',
3169 PeerPort => 993, # IMAP over SSL standard port
3170 ),
3171 );
3172 If you need more control over the socket, e.g. you have to implement a
3174 fancier authentication method, see "RawSocket".
3175 Starttls
3177 If an IMAP connection must start TLS/SSL after connecting to a server
3178 then set this attribute. If the value is set to an arrayref then they
3179 will be used as arguments to IO::Socket::SSL->start_SSL. By default
3180 this connection is set to blocking while establishing the connection
3181 with a timeout of 30 seconds. The socket will be reset to the original
3182 blocking/non-blocking value after a successful TLS negotiation has
3183 occurred. The arguments used in the call to start_SSL can be
3184 controlled by setting this attribute to an ARRAY reference containing
3185 the desired arguments.
3186 Version note: attribute added in Mail::IMAPClient 3.22
3188 Socketargs
3190 The arguments used in the call to IO::Socket::{UNIX|INET|SSL}->new can
3191 be controlled by setting this attribute to an ARRAY reference
3192 containing the desired arguments.
3193 For example, to always pass MultiHomed => 1 to IO::Socket::...->new the
3195 following can be used:
3196 $imap = Mail::IMAPClient->new(
3198 ..., Socketargs => [ MultiHomed => 1 ], ...
3199 );
3200 See also "Ssl" for specific control of the args to IO::Socket::SSL.
3202 Version note: attribute added in Mail::IMAPClient 3.34
3204 Ssl
3206 If an IMAP connection requires SSL you can set the Ssl attribute to '1'
3207 and Mail::IMAPClient will automatically use IO::Socket::SSL instead of
3208 IO::Socket::INET to connect to the server. This attribute is used in
3209 the "connect" method. The arguments used in the call to
3210 IO::Socket::SSL->new can be controlled by setting this attribute to an
3211 ARRAY reference containing the desired arguments.
3212 See also "connect" for details on connection initiation and "Socket"
3214 and "Rawsocket" if you need to take more control of connection
3215 management.
3216 Version note: attribute added in Mail::IMAPClient 3.18
3218 Supportedflags
3220 Especially when "migrate()" is used, the receiving peer may need to be
3221 configured explicitly with the list of supported flags; that may be
3222 different from the source IMAP server.
3223 The names are to be specified as an ARRAY. Black-slashes and casing
3225 will be ignored.
3226 You may also specify a CODE reference, which will be called for each of
3228 the flags separately. In this case, the flags are not (yet)
3229 normalized. The returned lists of the CODE calls are shape the
3230 resulting flag list.
3231 Timeout
3233 Example:
3234 $Timeout = $imap->Timeout();
3236 # or:
3237 $imap->Timeout($seconds);
3238 Specifies the timeout value in seconds for reads (default is 600).
3240 Specifying a Timeout will prevent Mail::IMAPClient from blocking in a
3241 read.
3242 Since timeouts are implemented via the Perl select operator, the
3244 Timeout parameter may be set to a fractional number of seconds.
3245 Setting Timeout to 0 (zero) disables the timeout feature.
3246 Uid
3248 Example:
3249 $Uid = $imap->Uid();
3251 # or:
3252 $imap->Uid($true_or_false);
3253 If "Uid" is set to a true value (i.e. 1) then the behavior of the
3255 "fetch", "search", "copy", and "store" methods (and their derivatives)
3256 is changed so that arguments that would otherwise be message sequence
3257 numbers are treated as message UID's and so that return values (in the
3258 case of the "search" method and its derivatives) that would normally be
3259 message sequence numbers are instead message UID's.
3260 Internally this is implemented as a switch that, if turned on, causes
3262 methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or
3263 COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH,
3264 or UID COPY, respectively. The main difference between message
3265 sequence numbers and message UID's is that, according to RFC3501, UID's
3266 must not change during a session and should not change between
3267 sessions, and must never be reused. Sequence numbers do not have that
3268 same guarantee and in fact may be reused right away.
3269 Since folder names also have a unique identifier (UIDVALIDITY), which
3271 is provided when the folder is "select"ed or "examine"d or by doing
3272 something like "$imap->status($folder,"UIDVALIDITY"), it is possible to
3273 uniquely identify every message on the server, although normally you
3274 won't need to bother.
3275 The methods currently affected by turning on the "Uid" flag are:
3277 copy fetch
3279 search store
3280 message_string message_uid
3281 body_string flags
3282 move size
3283 parse_headers thread
3284 Note that if for some reason you only want the "Uid" parameter turned
3286 on for one command, then you can choose between the following two
3287 snippets, which are equivalent:
3288 Example 1:
3290 $imap->Uid(1);
3292 my @uids = $imap->search('SUBJECT',"Just a silly test"); #
3293 $imap->Uid(0);
3294 Example 2:
3296 my @uids;
3298 foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
3299 chomp $r;
3300 $r =~ s/\r$//;
3301 $r =~ s/^\*\s+SEARCH\s+// or next;
3302 push @uids, grep(/\d/,(split(/\s+/,$r)));
3303 }
3304 In the second example, we used the default method to issue the UID IMAP
3306 Client command, being careful to use an all-uppercase method name so as
3307 not to inadvertently call the "Uid" accessor method. Then we parsed
3308 out the message UIDs manually, since we don't have the benefit of the
3309 built-in "search" method doing it for us.
3310 Please be very careful when turning the "Uid" parameter on and off
3312 throughout a script. If you loose track of whether you've got the
3313 "Uid" parameter turned on you might do something sad, like deleting the
3314 wrong message. Remember, like all eponymous accessor methods, the Uid
3315 method without arguments will return the current value for the "Uid"
3316 parameter, so do yourself a favor and check. The safest approach is
3317 probably to turn it on at the beginning (or just let it default to
3318 being on) and then leave it on. (Remember that leaving it turned off
3319 can lead to problems if changes to a folder's contents cause
3320 resequencing.)
3321 By default, the "Uid" parameter is turned on.
3323 User
3325 Example:
3326 $User = $imap->User();
3328 # or:
3329 $imap->User($userid);
3330 Specifies the userid to use when logging into the IMAP service. Can be
3332 supplied with the "new" method call or separately by calling the User
3333 object method.
3334 Parameters can be set during "new" method invocation by passing named
3336 parameter/value pairs to the method, or later by calling the
3337 parameter's eponymous object method.
3338
3340 There are several object methods that return the status of the object.
3341 They can be used at any time to check the status of an IMAPClient
3342 object, but are particularly useful for determining the cause of
3343 failure when a connection and login are attempted as part of a single
3344 "new" method invocation. The status methods are:
3345 Escaped_history
3347 Example:
3348 my @history = $imap->Escaped_history;
3350 The Escaped_history method is almost identical to the History method.
3352 Unlike the History method, however, server output transmitted literally
3353 will be wrapped in double quotes, with all double quotes, backslashes
3354 escaped. If called in a scalar context, Escaped_history returns an
3355 array reference rather than an array.
3356 Escaped_history is useful if you are retrieving output and processing
3358 it manually, and you are depending on the above special characters to
3359 delimit the data. It is not useful when retrieving message contents;
3360 use message_string or body_string for that.
3361 Escaped_results
3363 Example:
3364 my @results = $imap->Escaped_results;
3366 The Escaped_results method is almost identical to the Results method.
3368 Unlike the Results method, however, server output transmitted literally
3369 will be wrapped in double quotes, with all double quotes, backslashes
3370 escaped. If called in a scalar context, Escaped_results returns an
3371 array reference rather than an array.
3372 Escaped_results is useful if you are retrieving output and processing
3374 it manually, and you are depending on the above special characters to
3375 delimit the data. It is not useful when retrieving message contents;
3376 use message_string or body_string for that.
3377 History
3379 Example:
3380 my @history = $imap->History;
3382 The History method is almost identical to the "Results" method. Unlike
3384 the "Results" method, however, the IMAP command that was issued to
3385 create the results being returned is not included in the returned
3386 results. If called in a scalar context, History returns an array
3387 reference rather than an array.
3388 IsUnconnected
3390 returns a true value if the object is currently in an "Unconnected"
3391 state.
3392 IsConnected
3394 returns a true value if the object is currently in either a
3395 "Connected", "Authenticated", or "Selected" state.
3396 IsAuthenticated
3398 returns a true value if the object is currently in either an
3399 "Authenticated" or "Selected" state.
3400 IsSelected
3402 returns a true value if the object is currently in a "Selected" state.
3403 LastError
3405 Internally LastError is implemented just like a parameter (as described
3406 in "Parameters", above). There is a LastError attribute and an
3407 eponymous accessor method which returns the LastError text string
3408 describing the last error condition encountered by the server.
3409 Note that some errors are more serious than others, so LastError's
3411 value is only meaningful if you encounter an error condition that you
3412 don't like. For example, if you use the "exists" method to see if a
3413 folder exists and the folder does not exist, then an error message will
3414 be recorded in LastError even though this is not a particularly serious
3415 error. On the other hand, if you didn't use "exists" and just tried to
3416 "select" a non-existing folder, then "select" would return "undef"
3417 after setting LastError to something like "NO SELECT failed: Can't open
3418 mailbox "mailbox": no such mailbox". At this point it would be useful
3419 to print out the contents of LastError as you die.
3420 LastIMAPCommand
3422 New in version 2.0.4, LastIMAPCommand returns the exact IMAP command
3423 string to be sent to the server. Useful mainly in constructing error
3424 messages when "LastError" just isn't enough.
3425 Report
3427 The Report method returns an array containing a history of the IMAP
3428 session up to the point that Report was called. It is primarily meant
3429 to assist in debugging but can also be used to retrieve raw output for
3430 manual parsing. The value of the "Clear" parameter controls how many
3431 transactions are in the report.
3432 Results
3434 The Results method returns an array containing the results of one IMAP
3435 client command. It accepts one argument, the transaction number of the
3436 command whose results are to be returned. If transaction number is
3437 unspecified then Results returns the results of the last IMAP client
3438 command issued. If called in a scalar context, Results returns an
3439 array reference rather than an array.
3440 State
3442 The State method returns a numerical value that indicates the current
3443 status of the IMAPClient object. If invoked with an argument, it will
3444 set the object's state to that value. If invoked without an argument,
3445 it behaves just like "Status", below.
3446 Normally you will not have to invoke this function. An exception is if
3448 you are bypassing the Mail::IMAPClient module's "connect" and/or
3449 "login" modules to set up your own connection (say, for example, over a
3450 secure socket), in which case you must manually do what the "connect"
3451 and "login" methods would otherwise do for you.
3452 Status
3454 The Status method returns a numerical value that indicates the current
3455 status of the IMAPClient object. (Not to be confused with the "status"
3456 method, all lower-case, which is the implementation of the STATUS IMAP
3457 client command.)
3458 Transaction
3460 The Transaction method returns the tag value (or transaction number) of
3461 the last IMAP client command.
3462
3464 If you just want to use plain text authentication or any of the
3465 supported "Advanced Authentication Mechanisms" then there is no need to
3466 read this section.
3467 There are a number of methods and parameters that you can use to build
3469 your own authentication mechanism. All of the methods and parameters
3470 discussed in this section are described in more detail elsewhere in
3471 this document. This section provides a starting point for building
3472 your own authentication mechanism.
3473 There are many authentication mechanisms out there, if your preferred
3475 mechanism is not currently supported but you manage to get it working
3476 please consider donating them to this module. Patches and suggestions
3477 are always welcome.
3478 Support for add-on authentication mechanisms in Mail::IMAPClient is
3480 pretty straight forward. You create a callback to be used to provide
3481 the response to the server's challenge. The "Authcallback" parameter
3482 contains a reference to the callback, which can be an anonymous
3483 subroutine or a named subroutine. Then, you identify your
3484 authentication mechanism, either via the "Authmechanism" parameter or
3485 as an argument to "authenticate".
3486 You may also need to provide a subroutine to encrypt (or whatever) data
3488 before it is sent to the server. The "Prewritemethod" parameter must
3489 contain a reference to this subroutine. And, you will need to decrypt
3490 data from the server; a reference to the subroutine that does this must
3491 be stored in the "Readmethod" parameter.
3492 This framework is based on the assumptions that a) the mechanism you
3494 are using requires a challenge-response exchange, and b) the mechanism
3495 does not fundamentally alter the exchange between client and server but
3496 merely wraps the exchange in a layer of encryption. It also assumes
3497 that the line-oriented nature of the IMAP conversation is preserved;
3498 authentication mechanisms that break up messages into blocks of a
3499 predetermined size may still be possible but will certainly be more
3500 difficult to implement.
3501 Alternatively, if you have access to imtest, a utility included in the
3503 Cyrus IMAP distribution, you can use that utility to broker your
3504 communications with the IMAP server. This is quite easy to implement.
3505 An example, examples/imtestExample.pl, can be found in the "examples"
3506 subdirectory of the source distribution.
3507 The following list summarizes the methods and parameters that you may
3509 find useful in implementing advanced authentication:
3510 The authenticate method
3512 The "authenticate" method uses the "Authmechanism" parameter to
3513 determine how to authenticate with the server see the method
3514 documentation for details.
3515 Socket and RawSocket
3517 The "Socket" and "RawSocket" methods provide access to the socket
3518 connection. The socket is typically automatically created by the
3519 "connect" method, but if you are implementing an advanced
3520 authentication technique you may choose to set up your own socket
3521 connection and then set this parameter manually, bypassing the
3522 connect method completely. This is also useful if you want to use
3523 IO::Socket::INET alternatives like IO::Socket::SSL and need full
3524 control.
3525 "RawSocket" simply gets/sets the socket without attempting any
3527 interaction on it. In this case, you have to be sure to handle all
3528 the preliminary operations and manually set the Mail::IMAPClient
3529 object in sync with its actual status with respect to this socket
3530 (see below for additional parameters regarding this, especially the
3531 "State" parameter).
3532 Unlike "RawSocket", "Socket" attempts to carry on preliminary
3534 connection phases if the conditions apply. If both parameters are
3535 present, this takes the precedence over "RawSocket". If "Starttls"
3536 is set, then the "starttls" method will be called by "Socket".
3537 PLEASE NOTE As of version 2.99_04 of this module, semantics for
3539 "Socket" have changed to make it more "DWIM". "RawSocket" was
3540 introduced as a replacement for the "Socket" parameter in older
3541 version.
3542 State, Server, User, Password, Proxy and Domain Parameters
3544 If you need to make your own connection to the server and perform
3545 your authentication manually, then you can set these parameters to
3546 keep your Mail::IMAPClient object in sync with its actual status.
3547 Of these, only the "State" parameter is always necessary. The
3548 others need to be set only if you think your program will need them
3549 later.
3550 Authmechanism
3552 Set this to the value that AUTHENTICATE should send to the server
3553 as the authentication mechanism. If you are brokering your own
3554 authentication then this parameter may be less useful. It exists
3555 primarily so that you can set it when you call "new" to instantiate
3556 your object. The "new" method will call "connect", which will call
3557 "login". If "login" sees that you have set an Authmechanism then
3558 it will call authenticate, using your Authmechanism and
3559 Authcallback parameters as arguments.
3560 Authcallback
3562 The "Authcallback", if set, holds a pointer to a subroutine
3563 (CODEREF). The "login" method will use this as the callback
3564 argument to the authenticate method if the Authmechanism and
3565 Authcallback parameters are both set. If you set Authmechanism but
3566 not Authcallback then the default callback for your mechanism will
3567 be used. All supported authentication mechanisms have a default
3568 callback; in every other case not supplying the callback results in
3569 an error.
3570 Most advanced authentication mechanisms require a challenge-
3572 response exchange. After the "authenticate" method sends "<tag>
3573 AUTHENTICATE <Authmechanism>\015\012" to the IMAP server, the
3574 server replies with a challenge. The "authenticate" method then
3575 invokes the code whose reference is stored in the Authcallback
3576 parameter as follows:
3577 $Authcallback->( $challenge, $imap )
3579 where $Authcallback is the code reference stored in the
3581 Authcallback parameter, $challenge is the challenge received from
3582 the IMAP server, and $imap is a pointer to the Mail::IMAPClient
3583 object. The return value from the Authcallback routine should be
3584 the response to the challenge, and that return value will be sent
3585 by the "authenticate" method to the server.
3586 Prewritemethod/Readmethod
3588 The Prewritemethod can hold a subroutine that will do whatever
3589 encryption is necessary and then return the result to the caller so
3590 it in turn can be sent to the server.
3591 The Readmethod can hold a subroutine to be used to replace sysread
3593 usually performed by Mail::IMAPClient.
3594 See "Prewritemethod" and "Readmethod" for details.
3596
3598 Please send bug reports to "bug-Mail-IMAPClient@rt.cpan.org" or
3599 http://rt.cpan.org/Public/Dist/Display.html?Name=Mail-IMAPClient
3600
3602 Copyright (C) 1999-2003 The Kernen Group, Inc.
3603 Copyright (C) 2007-2009 Mark Overmeer
3604 Copyright (C) 2010-2017 Phil Pearl (Lobbes)
3605 All rights reserved.
3606 This library is free software; you can redistribute it and/or modify it
3608 under the same terms as Perl itself, either Perl version 5.8.0 or, at
3609 your option, any later version of Perl 5 you may have available.
3610 This program is distributed in the hope that it will be useful, but
3612 WITHOUT ANY WARRANTY; without even the implied warranty of
3613 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
3614 GNU General Public License or the Artistic License for more details.
3615perl v5.28.0 2017-02-02 Mail::IMAPClient(3)