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-quite the valaue
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 appropriately
215 automatically.
216 If you are getting unexpected results when running methods with values
218 that have (or might have) embedded spaces, double quotes, braces, or
219 parentheses, then calling Quote may be necessary. This method should
220 not be used with arguments that are wrapped in quotes or parens if
221 those quotes or parens are required by RFC3501. For example, if the
222 RFC requires an argument in this format:
223 ( argument )
225 and the argument is (or might be) "pennies (from heaven)", then one
227 could use:
228 $argument = "(" . $imap->Quote($argument) . ")"
230 Of course, the fact that sometimes these characters are sometimes
232 required delimiters is precisely the reason you must quote them when
233 they are not delimiting.
234 However, there are times when a method fails unexpectedly and may
236 require the use of Quote to work. Should this happen, you can probably
237 file a bug/enhancement request for Mail::IMAPClient to safeguard the
238 particular call/case better.
239 An example is RFC822 Message-id's, which usually don't contain quotes
241 or parens. When dealing with these it is usually best to take
242 proactive, defensive measures from the very start and use Quote.
243 Range
245 Example:
246 my $parsed = $imap->parse_headers(
248 $imap->Range( $imap->messages ), "Date", "Subject"
249 );
250 The Range method will condense a list of message sequence numbers or
252 message UID's into the most compact format supported by RFC3501. It
253 accepts one or more arguments, each of which can be:
254 a) a message number,
256 b) a comma-separated list of message numbers,
257 c) a colon-separated range of message numbers (i.e. "$begin:$end")
258 d) a combination of messages and message ranges, separated by commas
259 (i.e. 1,3,5:8,10), or
260 e) a reference to an array whose elements are like a) through d).
261 The Range method returns a Mail::IMAPClient::MessageSet object. The
263 object uses overload and if treated as a string it will act like a
264 string. This means you can ignore its objectivity and just treat it
265 like a string whose value is your message set expressed in compact
266 format.
267 This method provides an easy way to add or remove messages from a
269 message set.
270 For more information see Mail::IMAPClient::MessageSet.
272 Rfc3501_date
274 Example:
275 $Rfc3501_date = $imap->Rfc3501_date($seconds);
277 # or:
278 $Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);
279 The Rfc3501_date method accepts one input argument, a number of seconds
281 since the epoch date. It returns an RFC3501 compliant date string for
282 that date (as required in date-related arguments to SEARCH, such as
283 "since", "before", etc.).
284 Rfc3501_datetime
286 Example:
287 $date = $imap->Rfc3501_datetime($seconds);
289 # or:
290 $date = Mail::IMAPClient->Rfc3501_datetime($seconds);
291 The Rfc3501_datetime method accepts one or two arguments: a obligatory
293 timestamp and an optional zone. The zone shall be formatted as
294 "[+-]\d{4}", and defaults to +0000. The timestamp follows the
295 definition of the output of the platforms specific "time", usually in
296 seconds since Jan 1st 1970. However, you have to correct the number
297 yourself for the zone.
298 Rfc822_date
300 Example:
301 $Rfc822_date = $imap->Rfc822_date($seconds);
303 # or:
304 $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
305 The Rfc822_date method accepts one input argument, a number of seconds
307 since the epoch date. It returns an RFC822 compliant date string for
308 that date (without the 'Date:' prefix). Useful for putting dates in
309 message strings before calling "append", "search", etc.
310 Strip_cr
312 Examples:
313 my $stripped = $imap->Strip_cr($string);
315 # or:
316 my @list = $imap->some_imap_method;
317 @list = $imap->Strip_cr(@list);
318 # or:
319 my $list = [ $imap->some_imap_method ]; # returns an array ref
320 $list = $imap->Strip_cr($list);
321 The Strip_cr method strips carriage returns from input and returns the
323 new string to the caller. This method accepts one or more lines of
324 text as arguments, and returns those lines with all <CR><LF> sequences
325 changed to <LF>. Any input argument with no carriage returns is
326 returned unchanged. If the first argument (not counting the class name
327 or object reference) is an array reference, then members of that array
328 are processed as above and subsequent arguments are ignored. If the
329 method is called in scalar context then an array reference is returned
330 instead of an array of results.
331 NOTE: Strip_cr does not remove new line characters.
333
335 Object methods must be invoked against objects created via the "new"
336 method and cannot be invoked as class methods.
337 There object methods typically fall into one of two categories. There
339 are mailbox methods which participate in the IMAP session's
340 conversation (i.e. they issue IMAP client commands) and object control
341 methods which do not result in IMAP commands but which may affect later
342 commands or provide details of previous ones.
343 This object control methods can be further broken down into two types,
345 Parameter accessor methods, which affect the behavior of future mailbox
346 methods, and "Status Methods", which report on the affects of previous
347 mailbox methods.
348 Methods that do not result in new IMAP client commands being issued
350 (such as the "Transaction", "Status", and "History" methods) all begin
351 with an uppercase letter, to distinguish them from methods that do
352 correspond to IMAP client commands. Class methods and eponymous
353 parameter methods likewise begin with an uppercase letter because they
354 also do not correspond to an IMAP client command.
355 As a general rule, mailbox control methods return "undef" on failure
357 and something besides "undef" when they succeed. This rule is modified
358 in the case of methods that return search results. When called in a
359 list context, searches that do not find matching results return an
360 empty list. When called in a scalar context, searches with no hits
361 return 'undef' instead of an array reference. If you want to know why
362 you received no hits, you should check "LastError" or $@, which will be
363 empty if the search was successful but had no matching results but
364 populated with an error message if the search encountered a problem
365 (such as invalid parameters).
366 A number of IMAP commands do not have corresponding Mail::IMAPClient
368 methods. Patches are welcome. In the pre-2.99 releases of this
369 module, they were automatically created (AUTOLOAD), but that was very
370 error-prone and stalled the progress of this module.
371
373 append
374 Example:
375 my $uid_or_true = $imap->append( $folder, $msgtext )
377 or die "Could not append: ", $imap->LastError;
378 WARNING: This method may be deprecated in the future, consider using
380 "append_string" instead of this method.
381 The append method adds a message to the specified folder. See
383 "append_string" for details as it is effectively an alias for that
384 method.
385 DEPRECATED BEHAVIOR: Additional arguments are added to the message
387 text, separated with <CR><LF>.
388 append_string
390 Example:
391 # brackets indicate optional arguments (not array refs):
393 my $uidort = $imap->append_string( $folder, $msgtext [,$flags [,$date ] ] )
394 or die "Could not append_string: ", $imap->LastError;
395 Arguments:
397 $folder
399 the name of the folder to append the message to
400 $msgtext
402 the message text (including headers) of the message
403 $flags
405 An optional list of flags to set. The list must be specified as a
406 space-separated list of flags, including any backslashes that may
407 be necessary and optionally enclosed by parenthesis.
408 $date
410 An optional RFC3501 date argument to set as the internal date. It
411 should be in the format described for date_time fields in RFC3501,
412 i.e. "dd-Mon-yyyy hh:mm:ss +0000".
413 If you want to specify a date/time but you don't want any flags
415 then specify undef as the third ($flags) argument.
416 Returns:
418 error: undef
420 On error, undef can be returned regardless of LIST/SCALAR context.
421 Check "LastError" for details.
422 success: UID or $imap
424 With UIDPLUS the UID of the new message is returned otherwise a
425 true value (currently $self) is returned.
426 To protect against "bare newlines", append will insert a carriage
428 return before any newline that is "bare".
429 append_file
431 Example:
432 my $new_msg_uid = $imap->append_file(
434 $folder,
435 $file,
436 [ undef, $flags, $date ] # optional
437 ) or die "Could not append_file: ", $imap->LastError;
438 The append_file method adds a message to the specified folder. Note:
440 The brackets in the example indicate optional arguments; they do not
441 mean that the argument should be an array reference.
442 Arguments:
444 $folder
446 the name of the folder to append the message to
447 $file
449 a filename, filehandle or SCALAR reference which holds an
450 RFC822-formatted message
451 undef
453 a deprecated argument used as a place holder for backwards
454 compatibility
455 $flags
457 The optional argument is handled the same as append_string.
458 $date
460 The optional argument is handled the same as append_string (RFC3501
461 date), with the exception that if $date is "1" (one) then the
462 modification time (mtime) of the file will be used.
463 Returns:
465 error: undef
467 On error, undef can be returned regardless of LIST/SCALAR context.
468 Check "LastError" for details.
469 success: UID or $imap
471 With UIDPLUS the UID of the new message is returned otherwise a
472 true value (currently $self) is returned.
473 To protect against "bare newlines", append_file will insert a carriage
475 return before any newline that is "bare".
476 The append_file method provides a mechanism for allowing large messages
478 to be appended without holding the whole file in memory.
479 Version note: In 2.x an optional third argument to use for
481 "input_record_separator" was allowed, however this argument is
482 ignored/not supported as of 3.x.
483 authenticate
485 Example:
486 $imap->authenticate( $authentication_mechanism, $coderef )
488 or die "Could not authenticate: ", $imap->LastError;
489 This method implements the AUTHENTICATE IMAP client command. It can be
491 called directly or may be called by "login" if the "Authmechanism"
492 parameter is set to anything except 'LOGIN'.
493 The authenticate method accepts two arguments, an authentication type
495 to be used (ie CRAM-MD5) and a code or subroutine reference to execute
496 to obtain a response. The authenticate method assumes that the
497 authentication type specified in the first argument follows a
498 challenge-response flow. The authenticate method issues the IMAP
499 Client AUTHENTICATE command and receives a challenge from the server.
500 That challenge (minus any tag prefix or enclosing '+' characters but
501 still in the original base64 encoding) is passed as the only argument
502 to the code or subroutine referenced in the second argument. The
503 return value from the 2nd argument's code is written to the server as
504 is, except that a <CR><LF> sequence is appended if necessary.
505 If one or both of the arguments are not specified in the call to
507 authenticate but their corresponding parameters have been set
508 ("Authmechanism" and "Authcallback", respectively) then the parameter
509 values are used. Arguments provided to the method call however will
510 override parameter settings.
511 If you do not specify a second argument and you have not set the
513 "Authcallback" parameter, then the first argument must be one of the
514 authentication mechanisms for which Mail::IMAPClient has built in
515 support.
516 See also the "login" method, which is the simplest form of
518 authentication defined by RFC3501.
519 before
521 Example:
522 my @msgs = $imap->before($Rfc3501_date)
524 or warn "No messages found before $Rfc3501_date.\n";
525 The before method works just like the "since" method, below, except it
527 returns a list of messages whose internal system dates are before the
528 date supplied as the argument to the before method.
529 body_string
531 Example:
532 my $string = $imap->body_string($msgId)
534 or die "Could not body_string: ", $imap->LastError;
535 The body_string method accepts a message sequence number (or a message
537 UID, if the "Uid" parameter is set to true) as an argument and returns
538 the message body as a string. The returned value contains the entire
539 message in one scalar variable, without the message headers.
540 bodypart_string
542 Example:
543 my $string = $imap->bodypart_string(
545 $msgid, $part_number, $length, $offset
546 ) or die "Could not get bodypart string: ", $imap->LastError;
547 The bodypart_string method accepts a message sequence number (or a
549 message UID, if the "Uid" parameter is set to true) and a body part as
550 arguments and returns the message part as a string. The returned value
551 contains the entire message part (or, optionally, a portion of the
552 part) in one scalar variable.
553 If an optional third argument is provided, that argument is the number
555 of bytes to fetch. (The default is the whole message part.) If an
556 optional fourth argument is provided then that fourth argument is the
557 offset into the part at which the fetch should begin. The default is
558 offset zero, or the beginning of the message part.
559 If you specify an offset without specifying a length then the offset
561 will be ignored and the entire part will be returned.
562 bodypart_string will return "undef" if it encounters an error.
564 capability
566 Example:
567 my $features = $imap->capability
569 or die "Could not determine capability: ", $imap->LastError;
570 The capability method returns an array of capabilities as returned by
572 the CAPABILITY IMAP Client command, or a reference to an array of
573 capabilities if called in scalar context. If the CAPABILITY IMAP
574 Client command fails for any reason then the capability method will
575 return "undef".
576 close
578 Example:
579 $imap->close or die "Could not close: $@\n";
581 The close method is used to close the currently selected folder via the
583 CLOSE IMAP client command. According to RFC3501, the CLOSE command
584 performs an implicit EXPUNGE, which means that any messages that are
585 flagged as \Deleted (i.e. with the "delete_message" method) will now be
586 deleted. If you haven't deleted any messages then close can be thought
587 of as an "unselect".
588 Note: this closes the currently selected folder, not the IMAP session.
590 See also "delete_message", "expunge", and RFC3501.
592 connect
594 Example:
595 $imap->connect or die "Could not connect: $@\n";
597 The connect method connects an imap object to the server. It returns
599 "undef" if it fails to connect for any reason. If values are available
600 for the "User" and "Password" parameters at the time that connect is
601 invoked, then connect will call the "login" method after connecting and
602 return the result of the "login" method to connect's caller. If either
603 or both of the "User" and "Password" parameters are unavailable but the
604 connection to the server succeeds then connect returns a pointer to the
605 IMAPClient object.
606 The "Server" parameter must be set (either during "new" method
608 invocation or via the "Server" object method) before invoking connect.
609 When the parameter is an absolute file path, an UNIX socket will get
610 opened. If the "Server" parameter is supplied to the "new" method then
611 connect is implicitly called during object construction.
612 The connect method sets the state of the object to "Connected" if it
614 successfully connects to the server. It returns "undef" on failure.
615 copy
617 Example:
618 # Here brackets indicate optional arguments:
620 my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
621 or die "Could not copy: $@\n";
622 Or:
624 # Now brackets indicate an array ref!
626 my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
627 or die "Could not copy: $@\n";
628 The copy method requires a folder name as the first argument, and a
630 list of one or more messages sequence numbers (or messages UID's, if
631 the UID parameter is set to a true value). The message sequence
632 numbers or UID's should refer to messages in the currently selected
633 folder. Those messages will be copied into the folder named in the
634 first argument.
635 The copy method returns "undef" on failure and a true value if
637 successful. If the server to which the current Mail::IMAPClient object
638 is connected supports the UIDPLUS capability then the true value
639 returned by copy will be a comma separated list of UID's, which are the
640 UID's of the newly copied messages in the target folder.
641 create
643 Example:
644 $imap->create($new_folder)
646 or die "Could not create $new_folder: $@\n";
647 The create method accepts one argument, the name of a folder (or what
649 RFC3501 calls a "mailbox") to create. If you specify additional
650 arguments to the create method and your server allows additional
651 arguments to the CREATE IMAP client command then the extra argument(s)
652 will be passed to your server.
653 If you specify additional arguments to the create method and your
655 server does not allow additional arguments to the CREATE IMAP client
656 command then the extra argument(s) will still be passed to your server
657 and the create will fail.
658 create returns a true value on success and "undef" on failure.
660 date
662 Example:
663 my $date = $imap->date($msg);
665 The date method accepts one argument, a message sequence number (or a
667 message UID if the "Uid" parameter is set to a true value). It returns
668 the date of message as specified in the message's RFC822 "Date: "
669 header, without the "Date: " prefix.
670 The date method is a short-cut for:
672 my $date = $imap->get_header($msg,"Date");
674 delete
676 Example:
677 $imap->delete($folder) or die "Could not delete $folder: $@\n";
679 The delete method accepts a single argument, the name of a folder to
681 delete. It returns a true value on success and "undef" on failure.
682 delete_message
684 Example:
685 my @msgs = $imap->seen;
687 scalar(@msgs) and $imap->delete_message(\@msgs)
688 or die "Could not delete_message: $@\n";
689 The above could also be rewritten like this:
691 # scalar context returns array ref
693 my $msgs = scalar($imap->seen);
694 scalar(@$msgs) and $imap->delete_message($msgs)
696 or die "Could not delete_message: $@\n";
697 Or, as a one-liner:
699 $imap->delete_message( scalar($imap->seen) )
701 or warn "Could not delete_message: $@\n";
702 # just give warning in case failure is
703 # due to having no 'seen' msgs in the 1st place!
704 The delete_message method accepts a list of arguments. If the "Uid"
706 parameter is not set to a true value, then each item in the list should
707 be either:
708 · a message sequence number,
710 · a comma-separated list of message sequence numbers,
712 · a reference to an array of message sequence numbers, or
714 If the "Uid" parameter is set to a true value, then each item in the
716 list should be either:
717 · a message UID,
719 · a comma-separated list of UID's, or
721 · a reference to an array of message UID's.
723 The messages identified by the sequence numbers or UID's will be
725 deleted. If successful, delete_message returns the number of messages
726 it was told to delete. However, since the delete is done by issuing
727 the +FLAGS.SILENT option of the STORE IMAP client command, there is no
728 guarantee that the delete was successful for every message. In this
729 manner the delete_message method sacrifices accuracy for speed.
730 Generally, though, if a single message in a list of messages fails to
731 be deleted it's because it was already deleted, which is what you
732 wanted anyway so why worry about it? If there is a more severe error,
733 i.e. the server replies "NO", "BAD", or, banish the thought, "BYE",
734 then delete_message will return "undef".
735 If you must have guaranteed results then use the IMAP STORE client
737 command (via the default method) and use the +FLAGS (\Deleted) option,
738 and then parse your results manually.
739 Eg:
741 $imap->store( $msg_id, '+FLAGS (\Deleted)' );
743 my @results = $imap->History( $imap->Transaction );
744 ... # code to parse output goes here
745 (Frankly I see no reason to bother with any of that; if a message
747 doesn't get deleted it's almost always because it's already not there,
748 which is what you want anyway. But 'your mileage may vary' and all
749 that.)
750 The IMAPClient object must be in "Selected" status to use the
752 delete_message method.
753 NOTE: All the messages identified in the input argument(s) must be in
755 the currently selected folder. Failure to comply with this requirement
756 will almost certainly result in the wrong message(s) being deleted.
757 ADDITIONAL NOTE: In the grand tradition of the IMAP protocol, deleting
759 a message doesn't actually delete the message. Really. If you want to
760 make sure the message has been deleted, you need to expunge the folder
761 (via the "expunge" method, which is implemented via the default
762 method). Or at least "close" it. This is generally considered a
763 feature, since after deleting a message, you can change your mind and
764 undelete it at any time before your "expunge" or "close".
765 See also: the "delete" method, to delete a folder, the "expunge"
767 method, to expunge a folder, the "restore_message" method to undelete a
768 message, and the "close" method (implemented here via the default
769 method) to close a folder. Oh, and don't forget about RFC3501.
770 deny_seeing
772 Example:
773 # Reset all read msgs to unread
775 # (produces error if there are no seen msgs):
776 $imap->deny_seeing( scalar($imap->seen) )
777 or die "Could not deny_seeing: $@\n";
778 The deny_seeing method accepts a list of one or more message sequence
780 numbers, or a single reference to an array of one or more message
781 sequence numbers, as its argument(s). It then unsets the "\Seen" flag
782 for those messages (so that you can "deny" that you ever saw them). Of
783 course, if the "Uid" parameter is set to a true value then those
784 message sequence numbers should be unique message id's.
785 Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
787 specifying "$imap->unset_flag("Seen",@msgs)".
788 disconnect
790 Example:
791 $imap->disconnect or warn "Could not logout: $@\n";
793 This method calls "logout", see "logout" for details.
795 done
797 Example:
798 my $tag = $imap->idle or warn "idle failed: $@\n";
800 doSomethingA();
801 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
802 doSomethingB();
803 my $results = $imap->done($tag) or warn "Error from done: $@\n";
804 The done method tells the IMAP server to terminate the IDLE command.
806 The only argument is the tag (identifier) received from the previous
807 call to "idle". If tag is not specified a default tag based on the
808 Count attribute is assumed to be the tag to look for in the response
809 from the server.
810 If an invalid tag is specified, or the default tag is wrong, then done
812 will hang indefinitely or until a timeout occurs.
813 If done is called when an "idle" command is not active then the server
815 will likely respond with an error like * BAD Invalid tag.
816 On failure <undef> is returned and "LastError" is set.
818 See also "idle", "imap_data" and "Results".
820 examine
822 Example:
823 $imap->examine($folder) or die "Could not examine: $@\n";
825 The examine method selects a folder in read-only mode and changes the
827 object's state to "Selected". The folder selected via the examine
828 method can be examined but no changes can be made unless it is first
829 selected via the "select" method.
830 The examine method accepts one argument, which is the name of the
832 folder to select.
833 exists
835 Example:
836 $imap->exists($folder) or warn "$folder not found: $@\n";
838 Accepts one argument, a folder name. Returns true if the folder exists
840 or false if it does not exist.
841 expunge
843 Example:
844 $imap->expunge($folder) or die "Could not expunge: $@\n";
846 The expunge method accepts one optional argument, a folder name. It
848 expunges the folder specified as the argument, or the currently
849 selected folder (if any) when no argument is supplied.
850 Although RFC3501 does not permit optional arguments (like a folder
852 name) to the EXPUNGE client command, the "expunge" method does. Note:
853 expunging a folder deletes the messages that have the \Deleted flag set
854 (i.e. messages flagged via "delete_message").
855 See also the "close" method, which "deselects" as well as expunges.
857 fetch
859 Usage:
860 $imap->fetch( [$seq_set|ALL], @msg_data_items )
862 Example:
864 my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
866 The fetch method implements the FETCH IMAP client command. It accepts
868 a list of arguments, which will be converted into a space-delimited
869 list of arguments to the FETCH IMAP client command. If no arguments
870 are supplied then fetch does a FETCH ALL. If the "Uid" parameter is
871 set to a true value then the first argument will be treated as a UID or
872 list of UID's, which means that the UID FETCH IMAP client command will
873 be run instead of FETCH. (It would really be a good idea at this point
874 to review RFC3501.)
875 If called in array context, fetch will return an array of output lines.
877 The output lines will be returned just as they were received from the
878 server, so your script will have to be prepared to parse out the bits
879 you want. The only exception to this is literal strings, which will be
880 inserted into the output line at the point at which they were
881 encountered (without the {nnn} literal field indicator). See RFC3501
882 for a description of literal fields.
883 If fetch is called in a scalar context, then a reference to an array
885 (as described above) is returned instead of the entire array.
886 fetch returns "undef" on failure. Inspect "LastError" or $@ for an
888 explanation of your error.
889 fetch_hash
891 Usage:
892 $imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
894 Example:
896 my $hashref = {};
898 $imap->fetch_hash( "RFC822.SIZE", $hashref );
899 print "Msg #$m is $hashref->{$m} bytes\n" foreach my $m (keys %$hashref);
900 The fetch_hash method accepts a list of message attributes to be
902 fetched (as described in RFC3501). It returns a hash whose keys are
903 all the messages in the currently selected folder and whose values are
904 key-value pairs of fetch keywords and the message's value for that
905 keyword (see sample output below).
906 If fetch_hash is called in scalar context, it returns a reference to
908 the hash instead of the hash itself. If the last argument is a hash
909 reference, then that hash reference will be used as the place where
910 results are stored (and that reference will be returned upon successful
911 completion). If the last argument is not a reference then it will be
912 treated as one of the FETCH attributes and a new hash will be created
913 and returned (either by value or by reference, depending on the context
914 in which fetch_hash was called).
915 For example, if you have a folder with 3 messages and want the size and
917 internal date for each of them, you could do the following:
918 use Mail::IMAPClient;
920 use Data::Dumper;
921 # ... other code goes here
922 $imap->select($folder);
923 my $hash = $imap->fetch_hash("RFC822.SIZE","INTERNALDATE");
924 # (Same as:
925 # my $hash = $imap->fetch_hash("RFC822.SIZE");
926 # $imap->fetch_hash("INTERNALDATE",$hash);
927 # ).
928 print Data::Dumper->Dumpxs([$hash],['$hash']);
929 This would result in Data::Dumper output similar to the following:
931 $hash = {
933 '1' => {
934 'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
935 'RFC822.SIZE' => '1586',
936 },
937 '2' => {
938 'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
939 'RFC822.SIZE' => '1945',
940 },
941 '3' => {
942 'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
943 'RFC822.SIZE' => '134314',
944 }
945 };
946 By itself this method may be useful for tasks like obtaining the size
948 of every message in a folder. It issues one command and receives one
949 (possibly long!) response from the server.
950 If the fetch request causes the server to return data in a
952 parenthesized list, the data within the parenthesized list may be
953 escaped via the Escape() method. Use the Unescape() method to get the
954 raw values back in this case.
955 flags
957 Example:
958 my @flags = $imap->flags($msgid)
960 or die "Could not flags: $@\n";
961 The flags method implements the FETCH IMAP client command to list a
963 single message's flags. It accepts one argument, a message sequence
964 number (or a message UID, if the "Uid" parameter is true), and returns
965 an array (or a reference to an array, if called in scalar context)
966 listing the flags that have been set. Flag names are provided with
967 leading backslashes.
968 As of version 1.11, you can supply either a list of message id's or a
970 reference to an array of of message id's (which means either sequence
971 number, if the Uid parameter is false, or message UID's, if the Uid
972 parameter is true) instead of supplying a single message sequence
973 number or UID. If you do, then the return value will not be an array
974 or array reference; instead, it will be a hash reference, with each key
975 being a message sequence number (or UID) and each value being a
976 reference to an array of flags set for that message.
977 For example, if you want to display the flags for every message in the
979 folder where you store e-mail related to your plans for world
980 domination, you could do something like this:
981 use Mail::IMAPClient;
983 my $imap = Mail::IMAPClient->new(
984 Server => $imaphost,
985 User => $login,
986 Password => $pass,
987 Uid => 1, # optional
988 );
989 $imap->select("World Domination");
991 # get the flags for every message in my 'World Domination' folder
992 $flaghash = $imap->flags( scalar( $imap->search("ALL") ) );
993 # pump through sorted hash keys to print results:
995 for my $k (sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash) {
996 # print: Message 1: \Flag1, \Flag2, \Flag3
997 print "Message $k:\t",join(", ",@{$flaghash->{$k}}),"\n";
998 }
999 folders
1001 Example:
1002 $imap->folders or die "Could not list folders: $@\n";
1004 The folders method returns an array listing the available folders. It
1006 will only be successful if the object is in the Authenticated or
1007 Selected states.
1008 The folders argument accepts one optional argument, which is a prefix.
1010 If a prefix is supplied to the folders method, then only folders
1011 beginning with the prefix will be returned.
1012 For example:
1014 print join(", ",$imap->folders),".\n";
1016 # Prints:
1017 # INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1018 print join(", ",$imap->folders("Projects"),".\n";
1019 # Prints:
1020 # Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1021 print join(", ",$imap->folders("Projects" . $imap->separator),".\n";
1022 # Prints:
1023 # Projects/Completed, Projects/Ongoing
1024 Notice that if you just want to list a folder's subfolders (and not the
1026 folder itself), then you need to include the hierarchy separator
1027 character (as returned by the "separator" method).
1028 xlist_folders
1030 Example:
1031 my $xlist = $imap->xlist_folders
1033 or die "Could not get xlist folders.\n";
1034 IMAP servers implementing the XLIST extension (such as Gmail) designate
1036 particular folders to be used for particular functions. This is useful
1037 in the case where you want to know which folder should be used for
1038 Trash when the actual folder name can't be predicted (e.g. in the case
1039 of Gmail, the folder names change depending on the user's locale
1040 settings).
1041 The xlist_folders method returns a hash listing any "xlist" folder
1043 names, with the values listing the actual folders that should be used
1044 for those names. For example, using this method with a Gmail user
1045 using the English (US) locale might give this output from Data::Dumper:
1046 $VAR1 = {
1048 'Inbox' => 'Inbox',
1049 'AllMail' => '[Gmail]/All Mail',
1050 'Trash' => '[Gmail]/Trash',
1051 'Drafts' => '[Gmail]/Drafts',
1052 'Sent' => '[Gmail]/Sent Mail',
1053 'Spam' => '[Gmail]/Spam',
1054 'Starred' => '[Gmail]/Starred'
1055 };
1056 The same list for a user using the French locale might look like this:
1058 $VAR1 = {
1060 'Inbox' => 'Bo&AO4-te de r&AOk-ception',
1061 'AllMail' => '[Gmail]/Tous les messages',
1062 'Trash' => '[Gmail]/Corbeille',
1063 'Drafts' => '[Gmail]/Brouillons',
1064 'Sent' => '[Gmail]/Messages envoy&AOk-s',
1065 'Spam' => '[Gmail]/Spam',
1066 'Starred' => '[Gmail]/Suivis'
1067 };
1068 Mail::IMAPClient recognizes the following "xlist" folder names:
1070 Inbox
1072 AllMail
1073 Trash
1074 Drafts
1075 Sent
1076 Spam
1077 Starred
1078 These are currently the only ones supported by Gmail. The XLIST
1080 extension is not documented, and there are no other known
1081 implementations other than Gmail, so this list is based on what Gmail
1082 provides.
1083 If the server does not support the XLIST extension, this method returns
1085 undef.
1086 Version note: method added in Mail::IMAPClient 3.21
1088 has_capability
1090 Example:
1091 my $has_feature = $imap->has_capability($feature)
1093 or die "Could not do has_capability($feature): $@\n";
1094 Returns true if the IMAP server to which the IMAPClient object is
1096 connected has the capability specified as an argument to
1097 has_capability. If the server does not have the capability then the
1098 empty string "" is returned, if the underlying "capability" calls fails
1099 then undef is returned.
1100 idle
1102 Example:
1103 my $tag = $imap->idle or warn "idle failed: $@\n";
1105 doSomethingA();
1106 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1107 doSomethingB();
1108 my $results = $imap->done($tag) or warn "Error from done: $@\n";
1109 The idle method tells the IMAP server the client is ready to accept
1111 unsolicited mailbox update messages. This method is only valid on
1112 servers that support the IMAP IDLE extension, see RFC2177 for details.
1113 The idle method accepts no arguments and returns the tag (identifier)
1115 that was sent by the client for this command. This tag should be
1116 supplied as the argument to "done" when ending the IDLE command.
1117 On failure <undef> is returned and "LastError" is set.
1119 The method "idle_data" may be used once idle has been successful.
1121 However, no mailbox operations may be called until the idle command has
1122 been terminated by calling "done". Failure to do so will result in an
1123 error and the idle command will typically be terminated by the server.
1124 See also "imap_data" and "done".
1126 idle_data
1128 Example:
1129 my $tag = $imap->idle or warn "idle failed: $@\n";
1131 doSomethingA();
1132 my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
1133 doSomethingB();
1134 my $results = $imap->done($tag) or warn "Error from done: $@\n";
1135 The idle_data method can be used to accept any unsolicited mailbox
1137 update messages that have been sent by the server during an "idle"
1138 command. This method does not send any commands to the server, it
1139 simply waits for data from the server and returns that data to the
1140 caller.
1141 The idle method accepts an optional $timeout argument and returns an
1143 array (or an array reference if called in scalar context) with the
1144 messages from the server.
1145 By default a timeout of 0 seconds is used (do not block). Internally
1147 the timeout is passed to "select" in perlfunc. The timeout controls
1148 how long the select call blocks if there are no messages waiting to be
1149 read from the server.
1150 On failure <undef> is returned and "LastError" is set.
1152 See also "imap" and "done".
1154 Version note: method added in Mail::IMAPClient 3.23 Warning: this
1156 method is considered experimental and the interface/output may change
1157 in a future version.
1158 imap4rev1
1160 Example:
1161 $imap->imap4rev1 or die "Could not imap4rev1: $@\n";
1163 Returns true if the IMAP server to which the IMAPClient object is
1165 connected has the IMAP4REV1 capability. If the server does not have
1166 the capability then the empty string "" is returned, if the underlying
1167 "capability" calls fails then undef is returned.
1168 internaldate
1170 Example:
1171 my $msg_internal_date = $imap->internaldate($msgid)
1173 or die "Could not internaldate: $@\n";
1174 internaldate accepts one argument, a message id (or UID if the "Uid"
1176 parameter is true), and returns that message's internal date or undef
1177 if the call fails or internal date is not returned.
1178 get_bodystructure
1180 Example:
1181 my $bodyStructObject = $imap->get_bodystructure($msgid)
1183 or die "Could not get_bodystructure: $@\n";
1184 The get_bodystructure method accepts one argument, a message sequence
1186 number or, if "Uid" is true, a message UID. It obtains the message's
1187 body structure and returns a parsed Mail::IMAPClient::BodyStructure
1188 object for the message.
1189 get_envelope
1191 Example:
1192 my $envObject = $imap->get_envelope(@args)
1194 or die "Could not get_envelope: $@\n";
1195 The get_envelope method accepts one argument, a message sequence number
1197 or, if "Uid" is true, a message UID. It obtains the message's envelope
1198 and returns a Mail::IMAPClient::BodyStructure::Envelope object for the
1199 envelope, which is just a version of the envelope that's been parsed
1200 into a Perl object.
1201 For more information on how to use this object once you've gotten it,
1203 see the Mail::IMAPClient::BodyStructure documention. (As of this
1204 writing there is no separate pod document for
1205 Mail::IMAPClient::BodyStructure::Envelope.)
1206 getacl
1208 Example:
1209 my $hash = $imap->getacl($folder)
1211 or die "Could not getacl for $folder: $@\n";
1212 getacl accepts one argument, the name of a folder. If no argument is
1214 provided then the currently selected folder is used as the default. It
1215 returns a reference to a hash. The keys of the hash are userids that
1216 have access to the folder, and the value of each element are the
1217 permissions for that user. The permissions are listed in a string in
1218 the order returned from the server with no white space or punctuation
1219 between them.
1220 get_header
1222 Example:
1223 my $messageId = $imap->get_header( $msg, "Message-Id" );
1225 The get_header method accepts two arguments, a message sequence number
1227 or UID and the name of an RFC822 header (without the trailing colon).
1228 It returns the value for that header in the message whose sequence
1229 number or UID was passed as the first argument. If no value can be
1230 found it returns "undef"; if multiple values are found it returns the
1231 first one. Its return value is always a scalar. get_header uses case
1232 insensitive matching to get the value, so you do not have to worry
1233 about the case of your second argument.
1234 The get_header method is a short-cut for:
1236 my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
1238 is_parent
1240 Example:
1241 my $hasKids = $imap->is_parent($folder);
1243 The is_parent method accepts one argument, the name of a folder. It
1245 returns a value that indicates whether or not the folder has children.
1246 The value it returns is either 1) a true value (indicating that the
1247 folder has children), 2) 0 if the folder has no children at this time,
1248 or 3) "undef" if the folder is not permitted to have children.
1249 Eg:
1251 my $parenthood = $imap->is_parent($folder);
1253 if (defined($parenthood)) {
1254 if ($parenthood) {
1255 print "$folder has children.\n";
1256 } else {
1257 print "$folder is permitted children, but has none.\n";
1258 }
1259 } else {
1260 print "$folder is not permitted to have children.\n";
1261 }
1262 list
1264 Example:
1265 my @raw_output = $imap->list(@args)
1267 or die "Could not list: $@\n";
1268 The list method implements the IMAP LIST client command. Arguments are
1270 passed to the IMAP server as received, separated from each other by
1271 spaces. If no arguments are supplied then the default list command
1272 "tag LIST "" '*'" is issued.
1273 The list method returns an array (or an array reference, if called in a
1275 scalar context). The array is the unadulterated output of the LIST
1276 command. (If you want your output adulterated then see the "folders"
1277 method, above.)
1278 An "undef" value is returned in case of errors. Be sure to check for
1280 it.
1281 listrights
1283 Example:
1284 $imap->listrights($folder,$user)
1286 or die "Could not listrights: $@\n";
1287 The listrights method implements the IMAP LISTRIGHTS client command
1289 (RFC2086). It accepts two arguments, the foldername and a user id. It
1290 returns the rights the specified user has for the specified folder. If
1291 called in a scalar context then the rights are returned a strings, with
1292 no punctuation or white space or any nonsense like that. If called in
1293 array context then listrights returns an array in which each element is
1294 one right.
1295 login
1297 Example:
1298 $imap->login or die "Could not login: $@\n";
1300 The login method implements the IMAP LOGIN client command to log into
1302 the server. It automatically calls "authenticate" if the Authmechanism
1303 parameter is set to anything except 'LOGIN' otherwise a clear text
1304 LOGIN is attempted.
1305 The User and Password parameters must be set before the login method
1307 can be invoked. On success, a Mail::IMAPClient object with the Status
1308 of Authenticated is returned. On failure, undef is returned and $@ is
1309 set. The methods "new", "connect", and "Socket" may automatically
1310 invoke login see the documentation of each method for details.
1311 See also "proxyauth" and "Proxy" for additional information regarding
1313 ways of authenticating with a server via SASL and/or PROXYAUTH.
1314 proxyauth
1316 Example:
1317 $imap->login("admin", "password");
1319 $imap->proxyauth("someuser");
1320 The proxyauth method implements the IMAP PROXYAUTH client command. The
1322 command is used by Sun/iPlanet/Netscape IMAP servers to allow an
1323 administrative user to masquerade as another user.
1324 logout
1326 Example:
1327 $imap->logout or die "Could not logout: $@\n";
1329 The logout method implements the LOGOUT IMAP client commmand. This
1331 method causes the server to end the connection and the IMAPClient
1332 client enters the Unconnected state. This method does not, destroy the
1333 IMAPClient object, thus the "connect" and "login" methods can be used
1334 to establish a new IMAP session.
1335 Note that RFC2683 section 3.1.2 (Severed connections) makes some
1337 recommendations on how IMAP clients should behave. It is up to the
1338 user of this module to decide on the preferred behavior and code
1339 accordingly.
1340 Version note: documentation (from 2.x through 3.23) claimed that
1342 Mail::IMAPClient would attempt to log out of the server during DESTROY
1343 if the object is in the "Connected" state. This documentation was
1344 apparently incorrect from at least 2.2.2 and possibly earlier versions
1345 on up.
1346 lsub
1348 Example:
1349 $imap->lsub(@args) or die "Could not lsub: $@\n";
1351 The lsub method implements the IMAP LSUB client command. Arguments are
1353 passed to the IMAP server as received, separated from each other by
1354 spaces. If no arguments are supplied then the default lsub command
1355 "tag LSUB "" '*'" is issued.
1356 The lsub method returns an array (or an array reference, if called in a
1358 scalar context). The array is the unaltered output of the LSUB
1359 command. If you want an array of subscribed folders then see the
1360 "subscribed" method, below.
1361 mark
1363 Example:
1364 $imap->mark(@msgs) or die "Could not mark: $@\n";
1366 The mark method accepts a list of one or more messages sequence
1368 numbers, or a single reference to an array of one or more message
1369 sequence numbers, as its argument(s). It then sets the "\Flagged" flag
1370 for those message(s). Of course, if the "Uid" parameter is set to a
1371 true value then those message sequence numbers had better be unique
1372 message id's.
1373 Note that specifying "$imap->see(@msgs)" is just a shortcut for
1375 specifying "$imap->set_flag("Flagged",@msgs)".
1376 Massage
1378 Example:
1379 $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
1381 The Massage method accepts a value as an argument and, optionally, a
1383 second value that, when true, indicates that the first argument is not
1384 the name of an existing folder.
1385 It returns its argument as a correctly quoted string or a literal
1387 string.
1388 Note that you should rarely use this on folder names, since methods
1390 that accept folder names as an argument will call Massage for you. In
1391 fact, it was originally developed as an undocumented helper method
1392 meant for internal Mail::IMAPClient methods only.
1393 You may also want to see the "Quote" method, which is related to this
1395 method.
1396 message_count
1398 Example:
1399 my $msgcount = $imap->message_count($folder);
1401 defined($msgcount) or die "Could not message_count: $@\n";
1402 The message_count method accepts the name of a folder as an argument
1404 and returns the number of messages in that folder. Internally, it
1405 invokes the "status" method (see above) and parses out the results to
1406 obtain the number of messages. If you don't supply an argument to
1407 message_count then it will return the number of messages in the
1408 currently selected folder (assuming of course that you've used the
1409 "select" or "examine" method to select it instead of trying something
1410 funky). Note that RFC2683 contains warnings about the use of the IMAP
1411 STATUS command (and thus the "status" method and therefore the
1412 message_count method) against the currently selected folder. You
1413 should carefully consider this before using message_count on the
1414 currently selected folder. You may be better off using "search" or one
1415 of its variants (especially "messages"), and then counting the results.
1416 On the other hand, I regularly violate this rule on my server without
1417 suffering any dire consequences. Your mileage may vary.
1418 message_string
1420 Example:
1421 my $string = $imap->message_string($msgid)
1423 or die "Could not message_string: $@\n";
1424 The message_string method accepts a message sequence number (or message
1426 UID if "Uid" is true) as an argument and returns the message as a
1427 string. The returned value contains the entire message in one scalar
1428 variable, including the message headers. Note that using this method
1429 will set the message's "\Seen" flag as a side effect, unless Peek is
1430 set to a true value.
1431 message_to_file
1433 Example:
1434 $imap->message_to_file($file,@msgs)
1436 or die "Could not message_to_file: $@\n";
1437 The message_to_file method accepts a filename or file handle and one or
1439 more message sequence numbers (or message UIDs if "Uid" is true) as
1440 arguments and places the message string(s) (including RFC822 headers)
1441 into the file named in the first argument (or prints them to the file
1442 handle, if a file handle is passed). The returned value is true on
1443 success and "undef" on failure.
1444 If the first argument is a reference, it is assumed to be an open file
1446 handle and will not be closed when the method completes, If it is a
1447 file, it is opened in append mode, written to, then closed.
1448 Note that using this method will set the message's "\Seen" flag as a
1450 side effect. But you can use the "deny_seeing" method to set it back,
1451 or set the "Peek" parameter to a true value to prevent setting the
1452 "\Seen" flag at all.
1453 This method currently works by making some basic assumptions about the
1455 server's behavior, notably that the message text will be returned as a
1456 literal string but that nothing else will be. If you have a better
1457 idea then I'd like to hear it.
1458 message_uid
1460 Example:
1461 my $msg_uid = $imap->message_uid($msg_seq_no)
1463 or die "Could not get uid for $msg_seq_no: $@\n";
1464 The message_uid method accepts a message sequence number (or message
1466 UID if "Uid" is true) as an argument and returns the message's UID.
1467 Yes, if "Uid" is true then it will use the IMAP UID FETCH UID client
1468 command to obtain and return the very same argument you supplied. This
1469 is an IMAP feature so don't complain to me about it.
1470 messages
1472 Example:
1473 # Get a list of messages in the current folder:
1475 my @msgs = $imap->messages or die "Could not messages: $@\n";
1476 # Get a reference to an array of messages in the current folder:
1477 my $msgs = $imap->messages or die "Could not messages: $@\n";
1478 If called in list context, the messages method returns a list of all
1480 the messages in the currently selected folder. If called in scalar
1481 context, it returns a reference to an array containing all the messages
1482 in the folder. If you have the "Uid" parameter turned off, then this
1483 is the same as specifying "1 ... $imap->message_count"; if you have UID
1484 set to true then this is the same as specifying
1485 "$imap->"search"("ALL")".
1486 migrate
1488 Example:
1489 $imap_src->migrate( $imap_dest, "ALL", $targetFolder )
1491 or die "Could not migrate: ", $imap_src->LastError;
1492 The migrate method copies the indicated message(s) from the currently
1494 selected folder to another Mail::IMAPClient object's session. It
1495 requires these arguments:
1496 1. a reference to the target Mail::IMAPClient object (not the calling
1498 object, which is connected to the source account);
1499 2. the message(s) to be copied, specified as either a) the message
1501 sequence number (or message UID if the UID parameter is true) of a
1502 single message, b) a reference to an array of message sequence
1503 numbers (or message UID's if the UID parameter is true) or c) the
1504 special string "ALL", which is a shortcut for the results of
1505 ""search"("ALL")".
1506 3. the name of the destination folder on the target mailbox to receive
1508 the message(s). If this argument is not supplied or is undef then
1509 the currently selected folder on the calling object will be used.
1510 The destination folder will be automatically created if necessary.
1511 The target ($imap_dest) Mail::IMAPClient object must not be the same
1513 object as the source ($imap_src).
1514 This method does not attempt to minimize memory usage. In the future
1516 it could be enhanced to (optionaly) write message data to a temporary
1517 file to avoid storing the entire message in memory.
1518 To work around potential network timeouts on large messages, consider
1520 setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
1521 See also "Supportedflags".
1523 move
1525 Example:
1526 my $newUid = $imap->move($newFolder, $oldUid)
1528 or die "Could not move: $@\n";
1529 $imap->expunge;
1530 The move method moves messages from the currently selected folder to
1532 the folder specified in the first argument to move. If the "Uid"
1533 parameter is not true, then the rest of the arguments should be either:
1534 > a message sequence number,
1536 > a comma-separated list of message sequence numbers, or
1538 > a reference to an array of message sequence numbers.
1540 If the "Uid" parameter is true, then the arguments should be:
1542 > a message UID,
1544 > a comma-separated list of message UID's, or
1546 > a reference to an array of message UID's.
1548 If the target folder does not exist then it will be created.
1550 If move is successful, then it returns a true value. Furthermore, if
1552 the Mail::IMAPClient object is connected to a server that has the
1553 UIDPLUS capability, then the true value will be the comma-separated
1554 list of UID's for the newly copied messages. The list will be in the
1555 order in which the messages were moved. (Since move uses the copy
1556 method, the messages will be moved in numerical order.)
1557 If the move is not successful then move returns "undef".
1559 Note that a move really just involves copying the message to the new
1561 folder and then setting the \Deleted flag. To actually delete the
1562 original message you will need to run "expunge" (or "close").
1563 namespace
1565 Example:
1566 my $refs = $imap->namespace
1568 or die "Could not namespace: $@\n";
1569 The namespace method runs the NAMESPACE IMAP command (as defined in RFC
1571 2342). When called in a list context, it returns a list of three
1572 references. Each reference looks like this:
1573 [
1575 [ $prefix_1, $separator_1 ],
1576 [ $prefix_2, $separator_2 ],
1577 [ $prefix_n, $separator_n ],
1578 ]
1579 The first reference provides a list of prefixes and separator
1581 characters for the available personal namespaces. The second reference
1582 provides a list of prefixes and separator characters for the available
1583 shared namespaces. The third reference provides a list of prefixes and
1584 separator characters for the available public namespaces.
1585 If any of the three namespaces are unavailable on the current server
1587 then an 'undef' is returned instead of a reference. So for example if
1588 shared folders were not supported on the server but personal and public
1589 namespaces were both available (with one namespace each), the returned
1590 value might resemble this:
1591 [ [ "", "/" ] , undef, [ "#news", "." ] ];
1593 If the namespace method is called in scalar context, it returns a
1595 reference to the above-mentioned list of three references, thus
1596 creating a single structure that would pretty-print something like
1597 this:
1598 $VAR1 = [
1600 [
1601 [ $user_prefix_1, $user_separator_1 ],
1602 [ $user_prefix_2, $user_separator_2 ],
1603 [ $user_prefix_n, $user_separator_n ],
1604 ], # or undef
1605 [
1606 [ $shared_prefix_1, $shared_separator_1 ],
1607 [ $shared_prefix_2, $shared_separator_2 ],
1608 [ $shared_prefix_n, $shared_separator_n ],
1609 ], # or undef
1610 [
1611 [ $public_prefix_1, $public_separator_1 ],
1612 [ $public_prefix_2, $public_separator_2 ],
1613 [ $public_prefix_n, $public_separator_n ],
1614 ], # or undef
1615 ];
1616 on
1618 Example:
1619 my @msgs = $imap->on($Rfc3501_date)
1621 or warn "Could not find messages sent on $Rfc3501_date: $@\n";
1622 The on method works just like the "since" method, below, except it
1624 returns a list of messages whose internal system dates are the same as
1625 the date supplied as the argument.
1626 parse_headers
1628 Example:
1629 my $hashref = $imap->parse_headers($msg||\@msgs, "Date", "Subject")
1631 or die "Could not parse_headers: $@\n";
1632 The parse_headers method accepts as arguments a message sequence number
1634 and a list of header fields. It returns a hash reference in which the
1635 keys are the header field names (without the colon) and the values are
1636 references to arrays of values. A picture would look something like
1637 this:
1638 $hashref = $imap->parse_headers(1,"Date","Received","Subject","To");
1640 $hashref = {
1641 "Date" => [ "Thu, 09 Sep 1999 09:49:04 -0400" ] ,
1642 "Received" => [ q/
1643 from mailhub ([111.11.111.111]) by mailhost.bigco.com
1644 (Netscape Messaging Server 3.6) with ESMTP id AAA527D for
1645 <bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
1646 /, q/
1647 from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
1648 id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
1649 (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
1650 /, q/
1651 from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
1652 with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
1653 18 Jun 1999 16:29:05 +0000 (GMT)
1654 /] ,
1655 "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
1656 "To" => [ "Big Shot <big.shot@bigco.com> ] ,
1657 };
1658 The text in the example for the "Received" array has been formatted to
1660 make reading the example easier. The actual values returned are just
1661 strings of words separated by spaces and with newlines and carriage
1662 returns stripped off. The Received header is probably the main reason
1663 that the parse_headers method creates a hash of lists rather than a
1664 hash of values.
1665 If the second argument to parse_headers is 'ALL' or if it is
1667 unspecified then all available headers are included in the returned
1668 hash of lists.
1669 If you're not emotionally prepared to deal with a hash of lists then
1671 you can always call the "fetch" method yourself with the appropriate
1672 parameters and parse the data out any way you want to. Also, in the
1673 case of headers whose contents are also reflected in the envelope, you
1674 can use the "get_envelope" method as an alternative to "parse_headers".
1675 If the "Uid" parameter is true then the first argument will be treated
1677 as a message UID. If the first argument is a reference to an array of
1678 message sequence numbers (or UID's if "Uid" is true), then
1679 parse_headers will be run against each message in the array. In this
1680 case the return value is a hash, in which the key is the message
1681 sequence number (or UID) and the value is a reference to a hash as
1682 described above.
1683 An example of using parse_headers to print the date and subject of
1685 every message in your smut folder could look like this:
1686 use Mail::IMAPClient;
1688 my $imap = Mail::IMAPClient->new(
1689 Server => $imaphost, User => $login, Password => $pass, Uid => 1
1690 );
1691 $imap->select("demo");
1693 my $msgs = $imap->search("ALL");
1695 for my $h (
1696 # get the Subject and Date from every message in folder "demo" the
1698 # first arg is a reference to an array listing all messages in the
1699 # folder (which is what gets returned by the $imap->search("ALL")
1700 # method when called in scalar context) and the remaining arguments
1701 # are the fields to parse out The key is the message number, which
1702 # in this case we don't care about:
1703 values %{ $imap->parse_headers( $msgs , "Subject", "Date") } )
1705 {
1706 # $h is the value of each element in the hash ref returned
1707 # from parse_headers, and $h is also a reference to a hash.
1708 # We'll only print the first occurrence of each field because
1709 # we don't expect more than one Date: or Subject: line per
1710 # message.
1711 print map { "$_:\t$h->{$_}[0]\n"} keys %$h;
1712 }
1713 recent
1715 Example:
1716 my @recent = $imap->recent or warn "No recent msgs: $@\n";
1718 The recent method performs an IMAP SEARCH RECENT search against the
1720 selected folder and returns an array of sequence numbers (or UID's, if
1721 the "Uid" parameter is true) of messages that are recent.
1722 recent_count
1724 Example:
1725 my $count = 0;
1727 defined($count = $imap->recent_count($folder))
1728 or die "Could not recent_count: $@\n";
1729 The recent_count method accepts as an argument a folder name. It
1731 returns the number of recent messages in the folder (as returned by the
1732 IMAP client command "STATUS folder RECENT"), or "undef" in the case of
1733 an error. The recent_count method was contributed by Rob Deker
1734 (deker@ikimbo.com).
1735 reconnect
1737 Example:
1738 $imap->noop or $imap->reconnect or die "noop failed: $@\n";
1739 Attempt to reconnect if the IMAP connection unless $imap is already in
1741 the IsConnected state. This method calls "connect" and optionally
1742 "select" if a Folder was previously selected. On success, returns the
1743 (same) $imap object. On failure <undef> is returned and "LastError" is
1744 set.
1745 Version note: method added in Mail::IMAPClient 3.17
1747 rename
1749 Example:
1750 $imap->rename($oldname,$nedwname)
1752 or die "Could not rename: $@\n";
1753 The rename method accepts two arguments: the name of an existing
1755 folder, and a new name for the folder. The existing folder will be
1756 renamed to the new name using the RENAME IMAP client command. rename
1757 will return a true value if successful, or "undef" if unsuccessful.
1758 restore_message
1760 Example:
1761 $imap->restore_message(@msgs) or die "Could not restore_message: $@\n";
1763 The restore_message method is used to undo a previous "delete_message"
1765 operation (but not if there has been an intervening "expunge" or
1766 "close"). The IMAPClient object must be in "Selected" status to use
1767 the restore_message method.
1768 The restore_message method accepts a list of arguments. If the "Uid"
1770 parameter is not set to a true value, then each item in the list should
1771 be either:
1772 > a message sequence number,
1774 > a comma-separated list of message sequence numbers,
1776 > a reference to an array of message sequence numbers, or
1778 If the "Uid" parameter is set to a true value, then each item in the
1780 list should be either:
1781 > a message UID,
1783 > a comma-separated list of UID's, or
1785 > a reference to an array of message UID's.
1787 The messages identified by the sequence numbers or UID's will have
1789 their \Deleted flags cleared, effectively "undeleting" the messages.
1790 restore_message returns the number of messages it was able to restore.
1791 Note that restore_messages is similar to calling
1793 ""unset_flag"("\Deleted",@msgs)", except that restore_messages returns
1794 a (slightly) more meaningful value. Also it's easier to type.
1795 run
1797 Example:
1798 $imap->run(@args) or die "Could not run: $@\n";
1800 The run method is provided to make those uncommon things possible...
1802 however, we would like you to contribute the knowledge of missing
1803 features with us.
1804 The run method excepts one or two arguments. The first argument is a
1806 string containing an IMAP Client command, including a tag and all
1807 required arguments. The optional second argument is a string to look
1808 for that will indicate success. (The default is "/OK.*/"). The run
1809 method returns an array (or arrayref in scalar context) of output lines
1810 from the command, which you are free to parse as you see fit.
1811 The run method does not do any syntax checking, other than rudimentary
1813 checking for a tag.
1814 When run processes the command, it increments the transaction count and
1816 saves the command and responses in the History buffer in the same way
1817 other commands do. However, it also creates a special entry in the
1818 History buffer named after the tag supplied in the string passed as the
1819 first argument. If you supply a numeric value as the tag then you may
1820 risk overwriting a previous transaction's entry in the History buffer.
1821 If you want the control of run but you don't want to worry about tags
1823 then see "tag_and_run", below.
1824 search
1826 Example:
1827 my $msgs1 = $imap->search(@args);
1829 if ($msgs) {
1830 print "search matches: @$msgs1";
1831 }
1832 else {
1833 warn "Error in search: $@\n" if $@;
1834 }
1835 # or note: be sure to quote string properly
1837 my $msgs2 = $imap->search( \( $imap->Quote($msgid), "FROM", q{"me"} ) )
1838 or warn "search failed: $@\n";
1839 # or note: be sure to quote string properly
1841 my $msgs3 = $imap->search('TEXT "string not in mailbox"')
1842 or warn "search failed: $@\n";
1843 The search method implements the SEARCH IMAP client command. Any
1845 arguments supplied to search are prefixed with a space then appended to
1846 the SEARCH IMAP client command. The SEARCH IMAP client command allows
1847 for many options and arguments. See RFC3501 for details.
1848 As of version 3.17 search tries to "DWIM" by automatically quoting
1850 things that likely need quotes when the words do not match any of the
1851 following:
1852 ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED
1854 FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
1855 SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
1856 TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
1857 UNKEYWORD UNSEEN
1858 The following options exist to avoid the automatic quoting (note:
1860 caller is responsible for verifying the data sent in these cases is
1861 properly escaped/quoted):
1862 · specify a single string/argument in the call to search.
1864 · specify args as scalar references (SCALAR) and the values of those
1866 SCALAR refs will be passed along as-is.
1867 The search method returns an array containing sequence numbers of
1869 messages that passed the SEARCH IMAP client command's search criteria.
1870 If the "Uid" parameter is true then the array will contain message
1871 UID's. If search is called in scalar context then a pointer to the
1872 array will be passed, instead of the array itself. If no messages meet
1873 the criteria then search returns an empty list (when in list context)
1874 or "undef" (in scalar context).
1875 Since a valid, successful search can legitimately return zero matches,
1877 you may wish to distinguish between a search that correctly returns
1878 zero hits and a search that has failed for some other reason (i.e.
1879 invalid search parameters). Therefore, the $@ variable will always be
1880 cleared before the SEARCH command is issued to the server, and will
1881 thus remain empty unless the server gives a BAD or NO response to the
1882 SEARCH command.
1883 see
1885 Example:
1886 $imap->see(@msgs) or die "Could not see: $@\n";
1888 The see method accepts a list of one or more messages sequence numbers,
1890 or a single reference to an array of one or more message sequence
1891 numbers, as its argument(s). It then sets the \Seen flag for those
1892 message(s). Of course, if the "Uid" parameter is set to a true value
1893 then those message sequence numbers had better be unique message id's,
1894 but then you already knew that, didn't you?
1895 Note that specifying "$imap->see(@msgs)" is just a shortcut for
1897 specifying "$imap->"set_flag"("Seen",@msgs)".
1898 seen
1900 Example:
1901 my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
1903 The seen method performs an IMAP SEARCH SEEN search against the
1905 selected folder and returns an array of sequence numbers of messages
1906 that have already been seen (ie their \Seen flag is set). If the "Uid"
1907 parameter is true then an array of message UID's will be returned
1908 instead. If called in scalar context than a reference to the array
1909 (rather than the array itself) will be returned.
1910 select
1912 Example:
1913 $imap->select($folder) or die "Could not select: $@\n";
1915 The select method selects a folder and changes the object's state to
1917 Selected. It accepts one argument, which is the name of the folder to
1918 select.
1919 selectable
1921 Example:
1922 foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
1924 $imap->select($f);
1925 }
1926 The selectable method accepts one value, a folder name, and returns
1928 true if the folder is selectable or false if it is not selectable.
1929 sentbefore
1931 Example:
1932 my @msgs = $imap->sentbefore($Rfc3501_date)
1934 or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
1935 The sentbefore method works just like "sentsince", below, except it
1937 searches for messages that were sent before the date supplied as an
1938 argument to the method.
1939 senton
1941 Example:
1942 my @msgs = $imap->senton($Rfc3501_date)
1944 or warn "Could not find any messages sent on $Rfc3501_date: $@\n";
1945 The senton method works just like "sentsince", below, except it
1947 searches for messages that were sent on the exact date supplied as an
1948 argument to the method.
1949 sentsince
1951 Example:
1952 my @msgs = $imap->sentsince($Rfc3501_date)
1954 or warn "Could not find any messages sent since $Rfc3501_date: $@\n";
1955 The sentsince method accepts one argument, a date in either epoch time
1957 format (seconds since 1/1/1970, or as output by time and as accepted by
1958 localtime) or in the date_text format as defined in RFC3501 (dd-Mon-
1959 yyyy, where Mon is the English-language three-letter abbreviation for
1960 the month).
1961 It searches for items in the currently selected folder for messages
1963 sent since the day whose date is provided as the argument. It uses the
1964 RFC822 Date: header to determine the sentsince date. (Actually, it the
1965 server that uses the Date: header; this documentation just assumes that
1966 the date is coming from the Date: header because that's what RFC3501
1967 dictates.)
1968 In the case of arguments supplied as a number of seconds, the returned
1970 result list will include items sent on or after that day, regardless of
1971 whether they arrived before the specified time on that day. The IMAP
1972 protocol does not support searches at a granularity finer than a day,
1973 so neither do I. On the other hand, the only thing I check for in a
1974 date_text argument is that it matches the pattern
1975 "/\d\d-\D\D\D-\d\d\d\d/" (notice the lack of anchors), so if your
1976 server lets you add something extra to a date_text string then so will
1977 Mail::IMAPClient.
1978 If you'd like, you can use the "Rfc3501_date" method to convert from
1980 epoch time (as returned by time) into an RFC3501 date specification.
1981 separator
1983 Example:
1984 my $sepChar = $imap->separator(@args)
1986 or die "Could not get separator: $@\n";
1987 The separator method returns the character used as a separator
1989 character in folder hierarchies. On UNIX-based servers, this is often
1990 but not necessarily a forward slash (/). It accepts one argument, the
1991 name of a folder whose hierarchy's separator should be returned. If no
1992 folder name is supplied then the separator for the INBOX is returned,
1993 which probably is good enough.
1994 If you want your programs to be portable from IMAP server brand X to
1996 IMAP server brand Y, then you should never use hard-coded separator
1997 characters to specify subfolders. (In fact, it's even more complicated
1998 than that, since some server don't allow any subfolders at all, some
1999 only allow subfolders under the "INBOX" folder, and some forbid
2000 subfolders in the inbox but allow them "next" to the inbox.
2001 Furthermore, some server implementations do not allow folders to
2002 contain both subfolders and mail messages; other servers allow this.)
2003 set_flag
2005 Example:
2006 $imap->set_flag("Seen",@msgs)
2008 or die "Could not set flag: $@\n";
2009 The set_flag method accepts the name of a flag as its first argument
2011 and a list of one or more messages sequence numbers, or a single
2012 reference to an array of one or more message sequence numbers, as its
2013 next argument(s). It then sets the flag specified for those
2014 message(s). Of course, if the "Uid" parameter is set to a true value
2015 then those message sequence numbers had better be unique message id's,
2016 just as you'd expect.
2017 Note that when specifying the flag in question, the preceding backslash
2019 (\) is entirely optional. (For you, that is. Mail::IMAPClient still
2020 has remember to stick it in there before passing the command to the
2021 server if the flag is one of the reserved flags specified in RFC3501.
2022 This is in fact so important that the method checks its argument and
2023 adds the backslash when necessary, which is why you don't have to worry
2024 about it overly much.)
2025 setacl
2027 Example:
2028 $imap->setacl($folder,$userid,$authstring)
2030 or die "Could not set acl: $@\n";
2031 The setacl method accepts three input arguments, a folder name, a user
2033 id (or authentication identifier, to use the terminology of RFC2086),
2034 and an access rights modification string. See RFC2086 for more
2035 information. (This is somewhat experimental and its implementation may
2036 change.)
2037 since
2039 Example:
2040 my @msgs = $imap->since($date)
2042 or warn "Could not find any messages since $date: $@\n";
2043 The since method accepts a date in either epoch format (seconds since
2045 1/1/1970, or as output by "time" in perlfunc and as accepted by
2046 "localtime" in perlfunc) or in the date_text format as defined in
2047 RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter
2048 abbreviation for the month). It searches for items in the currently
2049 selected folder for messages whose internal dates are on or after the
2050 day whose date is provided as the argument. It uses the internal
2051 system date for a message to determine if that message was sent since
2052 the given date.
2053 In the case of arguments supplied as a number of seconds, the returned
2055 result list will include items whose internal date is on or after that
2056 day, regardless of whether they arrived before the specified time on
2057 that day.
2058 If since is called in a list context then it will return a list of
2060 messages meeting the SEARCH SINCE criterion, or an empty list if no
2061 messages meet the criterion.
2062 If since is called in a scalar context then it will return a reference
2064 to an array of messages meeting the SEARCH SINCE criterion, or "undef"
2065 if no messages meet the criterion.
2066 Since since is a front-end to "search", some of the same rules apply.
2068 For example, the $@ variable will always be cleared before the SEARCH
2069 command is issued to the server, and will thus remain empty unless the
2070 server gives a BAD or NO response to the SEARCH command.
2071 size
2073 Example:
2074 my $size = $imap->size($msgId)
2076 or die "Could not find size of message $msgId: $@\n";
2077 The size method accepts one input argument, a sequence number (or
2079 message UID if the "Uid" parameter is true). It returns the size of
2080 the message in the currently selected folder with the supplied sequence
2081 number (or UID). The IMAPClient object must be in a Selected state in
2082 order to use this method.
2083 sort
2085 Example:
2086 my @msgs = $imap->sort(@args);
2088 warn "Error in sort: $@\n" if $@;
2089 The sort method is just like the "search" method, only different. It
2091 implements the SORT extension as described in
2092 http://search.ietf.org/internet-drafts/draft-ietf-imapext-sort-10.txt.
2093 It would be wise to use the "has_capability" method to verify that the
2094 SORT capability is available on your server before trying to use the
2095 sort method. If you forget to check and you're connecting to a server
2096 that doesn't have the SORT capability then sort will return undef.
2097 "LastError" will then say you are "BAD". If your server doesn't
2098 support the SORT capability then you'll have to use "search" and then
2099 sort the results yourself.
2100 The first argument to sort is a space-delimited list of sorting
2102 criteria. The Internet Draft that describes SORT requires that this
2103 list be wrapped in parentheses, even if there is only one sort
2104 criterion. If you forget the parentheses then the sort method will add
2105 them. But you have to forget both of them, or none. This isn't CMS
2106 running under VM!
2107 The second argument is a character set to use for sorting. Different
2109 character sets use different sorting orders, so this argument is
2110 important. Since all servers must support UTF-8 and US-ASCII if they
2111 support the SORT capability at all, you can use one of those if you
2112 don't have some other preferred character set in mind.
2113 The rest of the arguments are searching criteria, just as you would
2115 supply to the "search" method. These are all documented in RFC3501.
2116 If you just want all of the messages in the currently selected folder
2117 returned to you in sorted order, use ALL as your only search criterion.
2118 The sort method returns an array containing sequence numbers of
2120 messages that passed the SORT IMAP client command's search criteria.
2121 If the "Uid" parameter is true then the array will contain message
2122 UID's. If sort is called in scalar context then a pointer to the array
2123 will be passed, instead of the array itself. The message sequence
2124 numbers or unique identifiers are ordered according to the sort
2125 criteria specified. The sort criteria are nested in the order
2126 specified; that is, items are sorted first by the first criterion, and
2127 within the first criterion they are sorted by the second criterion, and
2128 so on.
2129 The sort method will clear $@ before attempting the SORT operation just
2131 as the "search" method does.
2132 starttls
2134 Example:
2135 $imap->starttls() or die "starttls failed: $@\n";
2137 The starttls method accepts no arguments. This method is used to
2139 upgrade an exiting connection which is not authenticated to a TLS/SSL
2140 connection by using the IMAP STARTTLS command followed by using the
2141 start_SSL class method from IO::Socket::SSL to do the necessary TLS
2142 negotiation. The negotiation is done in a blocking fashion with a
2143 default Timeout of 30 seconds. The arguments used in the call to
2144 start_SSL can be controlled by setting the Mail::IMAPClient "Starttls"
2145 attribute to an ARRAY reference containing the desired arguments.
2146 Version note: method added in Mail::IMAPClient 3.22
2148 status
2150 Example:
2151 my @rawdata = $imap->status($folder,qw/(Messages)/)
2153 or die "Error obtaining status: $@\n";
2154 The status method accepts one argument, the name of a folder (or
2156 mailbox, to use RFC3501's terminology), and returns an array containing
2157 the results of running the IMAP STATUS client command against that
2158 folder. If additional arguments are supplied then they are appended to
2159 the IMAP STATUS client command string, separated from the rest of the
2160 string and each other with spaces.
2161 If status is not called in an array context then it returns a reference
2163 to an array rather than the array itself.
2164 The status method should not be confused with the Status method (with
2166 an uppercase 'S'), which returns information about the IMAPClient
2167 object. (See the section labeled "Status Methods", below).
2168 store
2170 Example:
2171 $imap->store(@args) or die "Could not store: $@\n";
2173 The store method accepts a message sequence number or comma-separated
2175 list of message sequence numbers as a first argument, a message data
2176 item name, and a value for the message data item. Currently, data
2177 items are the word "FLAGS" followed by a space and a list of flags (in
2178 parens). The word "FLAGS" can be modified by prefixing it with either
2179 a "+" or a "-" (to indicate "add these flags" or "remove these flags")
2180 and by suffixing it with ".SILENT" (which reduces the amount of output
2181 from the server; very useful with large message sets). Normally you
2182 won't need to call store because there are oodles of methods that will
2183 invoke store for you with the correct arguments. Furthermore, these
2184 methods are friendlier and more flexible with regards to how you
2185 specify your arguments. See for example "see", "deny_seeing",
2186 "delete_message", and "restore_message". Or "mark", "unmark",
2187 "set_flag", and "unset_flag".
2188 subject
2190 Example:
2191 my $subject = $imap->subject($msg);
2193 The subject method accepts one argument, a message sequence number (or
2195 a message UID, if the Uid parameter is true). The text in the
2196 "Subject" header of that message is returned (without the "Subject: "
2197 prefix). This method is a short-cut for:
2198 my $subject = $imap->get_header($msg, "Subject");
2200 subscribed
2202 Example:
2203 my @subscribedFolders = $imap->subscribed
2205 or warn "Could not find subscribed folders: $@\n";
2206 The subscribed method works like the folders method, above, except that
2208 the returned list (or array reference, if called in scalar context)
2209 contains only the subscribed folders.
2210 Like "folders", you can optionally provide a prefix argument to the
2212 subscribed method.
2213 tag_and_run
2215 Example:
2216 my $output = $imap->tag_and_run(@args)
2218 or die "Could not tag_and_run: $@\n";
2219 The tag_and_run method accepts one or two arguments. The first
2221 argument is a string containing an IMAP Client command, without a tag
2222 but with all required arguments. The optional second argument is a
2223 string to look for that will indicate success (without pattern
2224 delimiters). The default is "OK.*".
2225 The tag_and_run method will prefix your string (from the first
2227 argument) with the next transaction number and run the command. It
2228 returns an array of output lines from the command, which you are free
2229 to parse as you see fit. Using this method instead of run (above) will
2230 free you from having to worry about handling the tags (and from
2231 worrying about the side affects of naming your own tags).
2232 uidexpunge
2234 Example:
2235 $imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";
2237 The uidexpunge method implements the UID EXPUNGE IMAP (RFC4315 UIDPLUS
2239 ext) client command to permanently remove all messages that have the
2240 \Deleted flag set and have a UID that is included in the list of UIDs.
2241 uidexpunge returns an array or arrayref (scalar context) of output
2243 lines returned from the UID EXPUNGE command.
2244 uidexpunge returns undef on failure.
2246 If the server does not support the UIDPLUS extension, this method
2248 returns undef.
2249 uidnext
2251 Example:
2252 my $nextUid = $imap->uidnext($folder) or die "Could not uidnext: $@\n";
2254 The uidnext method accepts one argument, the name of a folder, and
2256 returns the numeric string that is the next available message UID for
2257 that folder.
2258 thread
2260 Example:
2261 my $thread = $imap->thread($algorithm, $charset, @search_args );
2263 The thread method accepts zero to three arguments. The first argument
2265 is the threading algorithm to use, generally either ORDEREDSUBJECT or
2266 REFERENCES. The second argument is the character set to use, and the
2267 third argument is the set of search arguments to use.
2268 If the algorithm is not supplied, it defaults to REFERENCES if
2270 available, or ORDEREDSUBJECT if available. If neither of these is
2271 available then the thread method returns undef.
2272 If the character set is not specified it will default to UTF-8.
2274 If the search arguments are not specified, the default is ALL.
2276 If thread is called for an object connected to a server that does not
2278 support the THREADS extension then the thread method will return
2279 "undef".
2280 The threads method will issue the THREAD command as defined in
2282 http://www.ietf.org/internet-drafts/draft-ietf-imapext-thread-11.txt.
2283 It returns an array of threads. Each element in the array is either a
2284 message id or a reference to another array of (sub)threads.
2285 If the "Uid" parameter is set to a true value then the message id's
2287 returned in the thread structure will be message UID's. Otherwise they
2288 will be message sequence numbers.
2289 uidvalidity
2291 Example:
2292 my $validity = $imap->uidvalidity($folder)
2294 or die "Could not uidvalidity: $@\n";
2295 The uidvalidity method accepts one argument, the name of a folder, and
2297 returns the numeric string that is the unique identifier validity value
2298 for the folder.
2299 unmark
2301 Example:
2302 $imap->unmark(@msgs) or die "Could not unmark: $@\n";
2304 The unmark method accepts a list of one or more messages sequence
2306 numbers, or a single reference to an array of one or more message
2307 sequence numbers, as its argument(s). It then unsets the \Flagged flag
2308 for those message(s). Of course, if the "Uid" parameter is set to a
2309 true value then those message sequence numbers should really be unique
2310 message id's.
2311 Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
2313 specifying "$imap->unset_flag("Flagged",@msgs)".
2314 Note also that the \Flagged flag is just one of many possible flags.
2316 This is a little confusing, but you'll have to get used to the idea
2317 that among the reserved flags specified in RFC3501 is one name
2318 \Flagged. There is no specific meaning for this flag; it means
2319 whatever the mailbox owner (or delegate) wants it to mean when it is
2320 turned on.
2321 unseen
2323 Example:
2324 my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
2326 The unseen method performs an IMAP SEARCH UNSEEN search against the
2328 selected folder and returns an array of sequence numbers of messages
2329 that have not yet been seen (ie their \Seen flag is not set). If the
2330 "Uid" parameter is true then an array of message UID's will be returned
2331 instead. If called in scalar context than a pointer to the array
2332 (rather than the array itself) will be returned.
2333 Note that when specifying the flag in question, the preceding backslash
2335 (\) is entirely optional.
2336 unseen_count
2338 Example:
2339 foreach my $f ($imap->folders) {
2341 print "The $f folder has ",
2342 $imap->unseen_count($f)||0, " unseen messages.\n";
2343 }
2344 The unseen_count method accepts the name of a folder as an argument and
2346 returns the number of unseen messages in that folder. If no folder
2347 argument is provided then it returns the number of unseen messages in
2348 the currently selected Folder.
2349 unset_flag
2351 Example:
2352 $imap->unset_flag("\Seen",@msgs)
2354 or die "Could not unset_flag: $@\n";
2355 The unset_flag method accepts the name of a flag as its first argument
2357 and a list of one or more messages sequence numbers, or a single
2358 reference to an array of one or more message sequence numbers, as its
2359 next argument(s). It then unsets the flag specified for those
2360 message(s). Of course, if the "Uid" parameter is set to a true value
2361 then those message sequence numbers had better be unique message id's,
2362 just as you'd expect.
2363
2365 Until release 2.99, when you called a method which did not exist, they
2366 where automatically translated into an IMAP call with the same name via
2367 an AUTOLOAD hack. This "feature" was removed for various reasons:
2368 people made typos in the capitalization of method names, and the
2369 program still seemed to work correctly. Besides, it blocked further
2370 development of this module, because people did not contribute their
2371 private extensions to the protocol implementation.
2372 copy($msg, $folder)
2374 Copy a message from the currently selected folder in the the folder
2375 whose name is in $folder
2376 subscribe($folder)
2378 Subscribe to a folder
2379 CAUTION: Once again, remember to quote your quotes (or use the "Quote"
2381 method) if you want quotes to be part of the IMAP command string.
2382 You can also use the default method to override the behavior of
2384 implemented IMAP methods by changing the case of the method name,
2385 preferably to all-uppercase so as not to conflict with the Class method
2386 and accessor method namespace. For example, if you don't want the
2387 "search" method's behavior (which returns a list of message numbers)
2388 but would rather have an array of raw data returned from your "search"
2389 operation, you can issue the following snippet:
2390 my @raw = $imap->SEARCH("SUBJECT","Whatever...");
2392 which is slightly more efficient than the equivalent:
2394 $imap->search("SUBJECT","Whatever...");
2396 my @raw = $imap->Results;
2397 Of course you probably want the search results tucked nicely into a
2399 list for you anyway, in which case you might as well use the "search"
2400 method.
2401
2403 There are several parameters that influence the behavior of an
2404 IMAPClient object. Each is set by specifying a named value pair during
2405 new method invocation as follows:
2406 my $imap = Mail::IMAPClient->new ( parameter => "value",
2408 parameter2 => "value",
2409 ...
2410 );
2411 Parameters can also be set after an object has been instantiated by
2413 using the parameter's eponymous accessor method like this:
2414 my $imap = Mail::IMAPClient->new;
2416 $imap->parameter( "value");
2417 $imap->parameter2("value");
2418 The eponymous accessor methods can also be used without arguments to
2420 obtain the current value of the parameter as follows:
2421 my $imap = Mail::IMAPClient->new;
2423 $imap->parameter( "value");
2424 $imap->parameter2("value");
2425 ... # A whole bunch of awesome Perl code, omitted for brevity
2427 my $forgot = $imap->parameter;
2429 my $forgot2 = $imap->parameter2;
2430 Note that in these examples I'm using 'parameter' and 'parameter2' as
2432 generic parameter names. The IMAPClient object doesn't actually have
2433 parameters named 'parameter' and 'parameter2'. On the contrary, the
2434 available parameters are:
2435 Authmechanism
2437 Example:
2438 $imap->Authmechanism("CRAM-MD5");
2440 # or
2441 my $authmech = $imap->Authmechanism();
2442 If specified, the Authmechanism causes the specified authentication
2444 mechanism to be used whenever Mail::IMAPClient would otherwise invoke
2445 login. If the value specified for the Authmechanism parameter is not a
2446 valid authentication mechanism for your server then you will never ever
2447 be able to log in again for the rest of your Perl script, probably. So
2448 you might want to check, like this:
2449 my $authmech = "CRAM-MD5";
2451 $imap->has_capability($authmech) and $imap->Authmechanism($authmech);
2452 Of course if you know your server supports your favorite authentication
2454 mechanism then you know, so you can then include your Authmechanism
2455 with your new call, as in:
2456 my $imap = Mail::IMAPClient->new(
2458 User => $user,
2459 Passord => $passord,
2460 Server => $server,
2461 Authmechanism => $authmech,
2462 %etc
2463 );
2464 If Authmechanism is supplied but Authcallback is not then you had
2466 better be supporting one of the authentication mechanisms that
2467 Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2468 Authcallback
2470 Example:
2471 $imap->Authcallback( \&callback );
2473 This specifies a default callback to the default authentication
2475 mechanism (see "Authmechanism", above). Together, these two methods
2476 replace automatic calls to login with automatic calls that look like
2477 this (sort of):
2478 $imap->authenticate($imap->Authmechanism,$imap->Authcallback);
2480 If Authmechanism is supplied but Authcallback is not then you had
2482 better be supporting one of the authentication mechanisms that
2483 Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
2484 Authuser
2486 The Authuser parameter is used by the DIGEST-MD5 "Authmechanism".
2487 Typically when you authenticate the username specified in the User
2489 parameter is used. However, when using the DIGEST-MD5 Authmechanism
2490 the Authuser can be used to specify a different username for the login.
2491 This can be useful to mark messages as seen for the Authuser if you
2493 don't know the password of the user as the seen state is often a per-
2494 user state.
2495 Buffer
2497 Example:
2498 $Buffer = $imap->Buffer();
2500 # or:
2501 $imap->Buffer($new_value);
2502 The Buffer parameter sets the size of a block of I/O. It is ignored
2504 unless "Fast_io", below, is set to a true value (the default), or
2505 unless you are using the "migrate" method. It's value should be the
2506 number of bytes to attempt to read in one I/O operation. The default
2507 value is 4096.
2508 When using the "migrate" method, you can often achieve dramatic
2510 improvements in throughput by adjusting this number upward. However,
2511 doing so also entails a memory cost, so if set too high you risk losing
2512 all the benefits of the "migrate" method's chunking algorithm. Your
2513 program can thus terminate with an "out of memory" error and you'll
2514 have no one but yourself to blame.
2515 Note that, as hinted above, the Buffer parameter affects the behavior
2517 of the "migrate" method regardless of whether you have "Fast_io" turned
2518 on. Believe me, you don't want to go around migrating tons of mail
2519 without using buffered I/O!
2520 Clear
2522 Example:
2523 $Clear = $imap->Clear();
2525 # or:
2526 $imap->Clear($integer);
2527 The name of this parameter, for historical reasons, is somewhat
2529 misleading. It should be named Wrap, because it specifies how many
2530 transactions are stored in the wrapped history buffer. But it didn't
2531 always work that way; the buffer used to actually get cleared. The
2532 name though remains the same in the interests of backwards
2533 compatibility.
2534 Clear specifies that the object's history buffer should be wrapped
2536 after every n transactions, where n is the value specified for the
2537 Clear parameter. Calling the eponymous Clear method without an
2538 argument will return the current value of the Clear parameter but will
2539 not cause clear the history buffer to wrap.
2540 Setting Clear to 0 turns off automatic history buffer wrapping, and
2542 setting it to 1 turns off the history buffer facility (except for the
2543 last transaction, which cannot be disabled without breaking the
2544 IMAPClient module). Setting Clear to 0 will not cause an immediate
2545 clearing of the history buffer; setting it to 1 (or any other number)
2546 will (except of course for that inevitable last transaction).
2547 The default Clear value is set to five (5) in order to conserve memory.
2549 Debug
2551 Example:
2552 $Debug = $imap->Debug();
2554 # or:
2555 $imap->Debug($true_or_false);
2556 Sets the debugging flag to either a true or false value. Can be
2558 supplied with the "new" method call or separately by calling the Debug
2559 object method. Use of this parameter is strongly recommended when
2560 debugging scripts and required when reporting bugs.
2561 Debug_fh
2563 Example:
2564 $Debug_fh = $imap->Debug_fh();
2566 # or:
2567 $imap->Debug_fh($fileHandle);
2568 Specifies the file handle to which debugging information should be
2570 printed. It can either a file handle object reference or a file handle
2571 glob. The default is to print debugging info to STDERR.
2572 For example, you can:
2574 use Mail::IMAPClient;
2576 use IO::File;
2577 # set $user, $pass, and $server here
2578 my $dh = IO::File->new(">debugging.output")
2579 or die "Can't open debugging.output: $!\n";
2580 my $imap = Mail::IMAPClient->new(
2581 User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh
2582 );
2583 which is the same as:
2585 use Mail::IMAPClient;
2587 use IO::File;
2588 # set $user, $pass, and $server here
2589 my $imap = Mail::IMAPClient->new(
2590 User => $user,
2591 Password => $pass,
2592 Server => $server,
2593 Debug => "yes, please",
2594 Debug_fh => IO::File->new(">debugging.output")
2595 || die "Can't open debugging.output: $!\n"
2596 );
2597 You can also:
2599 use Mail::IMAPClient;
2601 # set $user, $pass, and $server here
2602 open(DBG,">debugging.output")
2603 or die "Can't open debugging.output: $!\n";
2604 my $imap = Mail::IMAPClient->new(
2605 User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG
2606 );
2607 Specifying this parameter is not very useful unless "Debug" is set to a
2609 true value.
2610 Domain
2612 The Domain parameter is used by the NTLM "Authmechanism". The domain
2613 is an optional parameter for NTLM authentication.
2614 EnableServerResponseInLiteral
2616 Removed in 2.99_01 (now autodetect)
2617 Fast_io
2619 Example:
2620 $Fast_io = $imap->Fast_io();
2622 # or:
2623 $imap->Fast_io($true_or_false);
2624 The Fast_io parameter controls whether or not your Mail::IMAPClient
2626 object will attempt to use buffered (i.e. "Fast") I/O. It is turned on
2627 by default. If you turn it off you will definitely slow down your
2628 program, often to a painful degree. However, if you are experience
2629 problems you may want to try this just to see if it helps. If it does
2630 then that means you have found a bug and should report it immediately
2631 (by following the instructions in the section on "REPORTING BUGS").
2632 Even if it doesn't fix the problem, testing with both Fast_io turned on
2633 and with it turned off will often aid in identifying the source of the
2634 problem. (If it doesn't help you, it may help me when you report it!)
2635 Lately there have not been any bugs associated with Fast_io so this
2637 parameter may become deprecated in the future.
2638 Folder
2640 Example:
2641 $Folder = $imap->Folder();
2643 # or:
2644 $imap->Folder($new_value);
2645 The Folder parameter returns the name of the currently-selected folder
2647 (in case you forgot). It can also be used to set the name of the
2648 currently selected folder, which is completely unnecessary if you used
2649 the "select" method (or "select"'s read-only equivalent, the "examine"
2650 method) to select it.
2651 Note that setting the Folder parameter does not automatically select a
2653 new folder; you use the "select" or "examine" object methods for that.
2654 Generally, the Folder parameter should only be queried (by using the
2655 no-argument form of the Folder method). You will only need to set the
2656 Folder parameter if you use some mysterious technique of your own for
2657 selecting a folder, which you probably won't do.
2658 Ignoresizeerrors
2660 Certain (caching) servers, like Exchange 2007, often report the wrong
2661 message size. Instead of chopping the message into a size that it fits
2662 the specified size, the reported size will be simply ignored when this
2663 parameter is set to 1.
2664 Keepalive
2666 Some firewalls and network gear like to timeout connections prematurely
2667 if the connection sits idle. The Keepalive parameter, when set to a
2668 true value, affects the behavior of "new" and "Socket" by enabling
2669 SO_KEEPALIVE on the socket.
2670 Version note: attribute added in Mail::IMAPClient 3.17
2672 Maxcommandlength
2674 The Maxcommandlength attribute is used by fetch() to limit length of
2675 commands sent to a server. The default is 1000 chars, following the
2676 recommendation of RFC2683 section 3.2.1.5.
2677 Note: this attribute should also be used for several other methods but
2679 this has not yet been implemented please feel free to file bugs for
2680 methods where you run into problems with this.
2681 This attribute should remove the need for utilities like imapsync to
2683 create their own split() functions and instead allows Mail::IMAPClient
2684 to DWIM.
2685 In practice, this parameter has proven to be useful to overcome a limit
2687 of 8000 octets for UW-IMAPD and 16384 octets for Courier/Cyrus IMAP
2688 servers.
2689 Version note: attribute added in Mail::IMAPClient 3.17
2691 Maxtemperrors
2693 Example:
2694 $Maxtemperrors = $imap->Maxtemperrors();
2696 # or:
2697 $imap->Maxtemperrors($number);
2698 The Maxtemperrors parameter specifies the number of times a read or
2700 write operation is allowed to fail on a "Resource Temporarily
2701 Available" (e.g. EAGAIN) error. The default setting is undef which
2702 means there is no limit.
2703 Setting this parameter to the string "unlimited" (instead of undef) to
2705 ignore "Resource Temporarily Unavailable" errors is deprecated.
2706 Note: This setting should be used with caution and may be removed in a
2708 future release. Setting this can cause methods to return to the caller
2709 before data is received (and then handled) properly thereby possibly
2710 then leaving the module in a bad state. In the future, this behavior
2711 may be changed in an attempt to avoid this situation.
2712 Password
2714 Example:
2715 $Password = $imap->Password();
2717 # or:
2718 $imap->Password($new_value);
2719 Specifies the password to use when logging into the IMAP service on the
2721 host specified in the Server parameter as the user specified in the
2722 User parameter. Can be supplied with the new method call or separately
2723 by calling the Password object method.
2724 If Server, User, and Password are all provided to the "new" method,
2726 then the newly instantiated object will be connected to the host
2727 specified in Server (at either the port specified in Port or the
2728 default port 143) and then logged on as the user specified in the User
2729 parameter (using the password provided in the Password parameter). See
2730 the discussion of the "new" method, below.
2731 Peek
2733 Example:
2734 $Peek = $imap->Peek();
2736 # or:
2737 $imap->Peek($true_or_false);
2738 Setting Peek to a true value will prevent the "body_string",
2740 "message_string" and "message_to_file" methods from automatically
2741 setting the \Seen flag. Setting "Peek" to 0 (zero) will force
2742 "body_string", "message_string", "message_to_file", and "parse_headers"
2743 to always set the \Seen flag.
2744 The default is to set the seen flag whenever you fetch the body of a
2746 message but not when you just fetch the headers. Passing undef to the
2747 eponymous Peek method will reset the Peek parameter to its pristine,
2748 default state.
2749 Port
2751 Example:
2752 $Port = $imap->Port();
2754 # or:
2755 $imap->Port($new_value);
2756 Specifies the port on which the IMAP server is listening. The default
2758 is 143, which is the standard IMAP port. Can be supplied with the
2759 "new" method call or separately by calling the "Port" object method.
2760 Prewritemethod
2762 Prewritemethod parameter should contain a reference to a subroutine
2763 that will do "special things" to data before it is sent to the IMAP
2764 server (such as encryption or signing).
2765 This method will be called immediately prior to sending an IMAP client
2767 command to the server. Its first argument is a reference to the
2768 Mail::IMAPClient object and the second argument is a string containing
2769 the command that will be sent to the server. Your Prewritemethod
2770 should return a string that has been signed or encrypted or whatever;
2771 this returned string is what will actually be sent to the server.
2772 Your Prewritemethod will probably need to know more than this to do
2774 whatever it does. It is recommended that you tuck all other pertinent
2775 information into a hash, and store a reference to this hash somewhere
2776 where your method can get to it, possibly in the Mail::IMAPClient
2777 object itself.
2778 Note that this method should not actually send anything over the socket
2780 connection to the server; it merely converts data prior to sending.
2781 See also "Readmethod".
2783 Ranges
2785 Example:
2786 $imap->Ranges(1);
2788 # or:
2789 my $search = $imap->search(@search_args);
2790 if ( $imap->Ranges) { # $search is a MessageSet object
2791 print "This is my condensed search result: $search\n";
2792 print "This is every message in the search result: ",
2793 join(",",@$search),"\n;
2794 }
2795 If set to a true value, then the "search" method will return a
2797 Mail::IMAPClient::MessageSet object if called in a scalar context,
2798 instead of the array reference that fetch normally returns when called
2799 in a scalar context. If set to zero or if undefined, then search will
2800 continue to return an array reference when called in scalar context.
2801 This parameter has no affect on the search method when search is called
2803 in a list context.
2804 RawSocket
2806 Example:
2807 $socket = $imap->RawSocket;
2808 # or:
2809 $imap->RawSocket($socketh);
2810 The RawSocket method can be used to obtain the socket handle of the
2812 current connection (say, to do I/O on the connection that is not
2813 otherwise supported by Mail::IMAPClient) or to replace the current
2814 socket with a new handle (for instance an SSL handle, see
2815 IO::Socket::SSL, but be sure to see the "Socket" method as well).
2816 If you supply a socket handle yourself, either by doing something like:
2818 $imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
2820 or by doing something like:
2822 $imap = Mail::IMAPClient->new(User => $user,
2824 Password => $pass, Server => $host);
2825 # blah blah blah
2826 $imap->RawSocket($ssl);
2827 then it will be up to you to establish the connection AND to
2829 authenticate, either via the "login" method, or the fancier
2830 "authenticate", or, since you know so much anyway, by just doing raw
2831 I/O against the socket until you're logged in. If you do any of this
2832 then you should also set the "State" parameter yourself to reflect the
2833 current state of the object (i.e. Connected, Authenticated, etc).
2834 Note that no operation will be attempted on the socket when this method
2836 is called. In particular, after the TCP connections towards the IMAP
2837 server is established, the protocol mandates the server to send an
2838 initial greeting message, and you will have to explicitly cope with
2839 this message before doing any other operation, e.g. trying to call
2840 "login". Caveat emptor.
2841 For a more DWIM approach to setting the socket see "Socket".
2843 Readmethod
2845 Example:
2846 $imap->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET
2848 sub {
2849 my ( $self, $handle, $buffer, $count, $offset ) = @_;
2850 my $rc = sysread( $handle, $$buffer, $count, $offset );
2851 # do something useful here...
2852 }
2853 );
2854 Readmethod should contain a reference to a subroutine that will replace
2856 sysread. The subroutine will be passed the following arguments: first
2857 the used Mail::IMAPClient object. Second, a reference to a socket.
2858 Third, a reference to a scalar variable into which data is read
2859 (BUFFER). The data placed here should be "finished data", so if you are
2860 decrypting or removing signatures then be sure to do that before you
2861 place data into this buffer. Fourth, the number of bytes requested to
2862 be read; the LENGTH of the request. Lastly, the OFFSET into the BUFFER
2863 where the data should be read. If not supplied it should default to
2864 zero.
2865 Note that this method completely replaces reads from the connection to
2867 the server, so if you define one of these then your subroutine will
2868 have to actually do the read. It is for things like this that we have
2869 the "Socket" parameter and eponymous accessor method.
2870 Your Readmethod will probably need to know more than this to do
2872 whatever it does. It is recommended that you tuck all other pertinent
2873 information into a hash, and store a reference to this hash somewhere
2874 where your method can get to it, possibly in the Mail::IMAPClient
2875 object itself.
2876 See also "Prewritemethod".
2878 Reconnectretry
2880 If an IMAP connection sits idle too long, the connection may be closed
2881 by the server or firewall, etc. The Reconnectretry parameter, when
2882 given a positive integer value, will cause Mail::IMAPClient to retrying
2883 IMAP commands up to X times when an EPIPE or ECONNRESET error occurs.
2884 This is disabled (0) by default.
2885 See also "Keepalive"
2887 Version note: attribute added in Mail::IMAPClient 3.17
2889 Server
2891 Example:
2892 $Server = $imap->Server();
2894 # or:
2895 $imap->Server($hostname);
2896 Specifies the hostname or IP address of the host running the IMAP
2898 server. If provided as part of the "new" method call, then the new
2899 IMAP object will automatically be connected at the time of
2900 instantiation. (See the "new" method, below.) Can be supplied with the
2901 "new" method call or separately by calling the Server object method.
2902 Showcredentials
2904 Normally debugging output will mask the login credentials when the
2905 plain text login mechanism is used. Setting Showcredentials to a true
2906 value will suppress this, so that you can see the string being passed
2907 back and forth during plain text login. Only set this to true when you
2908 are debugging problems with the IMAP LOGIN command, and then turn it
2909 off right away when you're finished working on that problem.
2910 Example:
2912 print "This is very risky!\n" if $imap->Showcredentials();
2914 # or:
2915 $imap->Showcredentials(0); # mask credentials again
2916 Socket
2918 PLEASE NOTE The semantics of this method has changed as of version
2919 2.99_04 of this module. If you need the old semantics use "RawSocket".
2920 Example:
2922 $Socket = $imap->Socket();
2924 # or:
2925 $imap->Socket($socket_fh);
2926 The Socket method can be used to obtain the socket handle of the
2928 current connection. This may be necessary to do I/O on the connection
2929 that is not otherwise supported by Mail::IMAPClient) or to replace the
2930 current socket with a new handle (for instance an SSL handle, see
2931 IO::Socket::SSL).
2932 If you supply a socket handle yourself, either by doing something like:
2934 $imap = Mail::IMAPClient->new( Socket => $sock, User => ... );
2936 or by doing something like:
2938 $imap = Mail::IMAPClient->new(
2940 User => $user, Password => $pass, Server => $host
2941 );
2942 $imap->Socket($ssl);
2943 then you are responsible for establishing the connection, i.e. make
2945 sure that $ssl in the example is a valid and connected socket.
2946 This method is primarily used to provide a drop-in replacement for
2948 IO::Socket::INET, used by "connect" by default. In fact, this method
2949 is called by "connect" itself after having established a suitable
2950 IO::Socket::INET socket connection towards the target server; for this
2951 reason, this method also carries the normal operations associated with
2952 "connect", namely:
2953 · read the initial greeting message from the server;
2955 · call "login" if the conditions apply (see "connect" for details);
2957 · leave the Mail::IMAPClient object in a suitable state.
2959 For these reasons, the following example will work "out of the box":
2961 use IO::Socket::SSL;
2963 my $imap = Mail::IMAPClient->new
2964 ( User => 'your-username',
2965 Password => 'your-password',
2966 Socket => IO::Socket::SSL->new
2967 ( Proto => 'tcp',
2968 PeerAddr => 'some.imap.server',
2969 PeerPort => 993, # IMAP over SSL standard port
2970 ),
2971 );
2972 If you need more control over the socket, e.g. you have to implement a
2974 fancier authentication method, see "RawSocket".
2975 Starttls
2977 If an IMAP connection must start TLS/SSL after connecting to a server
2978 then set this attribute. If the value is set to an arrayref then they
2979 will be used as arguments to IO::Socket::SSL::start_SSL. By default
2980 this connection is set to blocking while establishing the connection
2981 with a timeout of 30 seconds. The socket will be reset to the original
2982 blocking/non-blocking value after a successful TLS negotiation has
2983 occured.
2984 Version note: attribute added in Mail::IMAPClient 3.22
2986 Ssl
2988 If an IMAP connection requires SSL you can set the Ssl attribute to '1'
2989 and Mail::IMAPClient will automatically use IO::Socket::SSL instead of
2990 IO::Socket::INET to connect to the server. This attribute is used in
2991 the "connect" method.
2992 See also "connect" for details on connection initiatiation and "Socket"
2994 and "Rawsocket" if you need to take more control of connection
2995 management.
2996 Version note: attribute added in Mail::IMAPClient 3.18
2998 Supportedflags
3000 Especially when "migrate()" is used, the receiving peer may need to be
3001 configured explicitly with the list of supported flags; that may be
3002 different from the source IMAP server.
3003 The names are to be specified as an ARRAY. Black-slashes and casing
3005 will be ignored.
3006 You may also specify a CODE reference, which will be called for each of
3008 the flags separately. In this case, the flags are not (yet)
3009 normalized. The returned lists of the CODE calls are shape the
3010 resulting flag list.
3011 Timeout
3013 Example:
3014 $Timeout = $imap->Timeout();
3016 # or:
3017 $imap->Timeout($seconds);
3018 Specifies the timeout value in seconds for reads (default is 600).
3020 Specifying a Timeout will prevent Mail::IMAPClient from blocking in a
3021 read.
3022 Since timeouts are implemented via the Perl select operator, the
3024 Timeout parameter may be set to a fractional number of seconds.
3025 Setting Timeout to 0 (zero) disables the timeout feature.
3026 Uid
3028 Example:
3029 $Uid = $imap->Uid();
3031 # or:
3032 $imap->Uid($true_or_false);
3033 If "Uid" is set to a true value (i.e. 1) then the behavior of the
3035 "fetch", "search", "copy", and "store" methods (and their derivatives)
3036 is changed so that arguments that would otherwise be message sequence
3037 numbers are treated as message UID's and so that return values (in the
3038 case of the "search" method and its derivatives) that would normally be
3039 message sequence numbers are instead message UID's.
3040 Internally this is implemented as a switch that, if turned on, causes
3042 methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or
3043 COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH,
3044 or UID COPY, respectively. The main difference between message
3045 sequence numbers and message UID's is that, according to RFC3501, UID's
3046 must not change during a session and should not change between
3047 sessions, and must never be reused. Sequence numbers do not have that
3048 same guarantee and in fact may be reused right away.
3049 Since folder names also have a unique identifier (UIDVALIDITY), which
3051 is provided when the folder is "select"ed or "examine"d or by doing
3052 something like "$imap->status($folder,"UIDVALIDITY"), it is possible to
3053 uniquely identify every message on the server, although normally you
3054 won't need to bother.
3055 The methods currently affected by turning on the "Uid" flag are:
3057 copy fetch
3059 search store
3060 message_string message_uid
3061 body_string flags
3062 move size
3063 parse_headers thread
3064 Note that if for some reason you only want the "Uid" parameter turned
3066 on for one command, then you can choose between the following two
3067 snippets, which are equivalent:
3068 Example 1:
3070 $imap->Uid(1);
3072 my @uids = $imap->search('SUBJECT',"Just a silly test"); #
3073 $imap->Uid(0);
3074 Example 2:
3076 my @uids;
3078 foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
3079 chomp $r;
3080 $r =~ s/\r$//;
3081 $r =~ s/^\*\s+SEARCH\s+// or next;
3082 push @uids, grep(/\d/,(split(/\s+/,$r)));
3083 }
3084 In the second example, we used the default method to issue the UID IMAP
3086 Client command, being careful to use an all-uppercase method name so as
3087 not to inadvertently call the "Uid" accessor method. Then we parsed
3088 out the message UIDs manually, since we don't have the benefit of the
3089 built-in "search" method doing it for us.
3090 Please be very careful when turning the "Uid" parameter on and off
3092 throughout a script. If you loose track of whether you've got the
3093 "Uid" parameter turned on you might do something sad, like deleting the
3094 wrong message. Remember, like all eponymous accessor methods, the Uid
3095 method without arguments will return the current value for the "Uid"
3096 parameter, so do yourself a favor and check. The safest approach is
3097 probably to turn it on at the beginning (or just let it default to
3098 being on) and then leave it on. (Remember that leaving it turned off
3099 can lead to problems if changes to a folder's contents cause
3100 resequencing.)
3101 By default, the "Uid" parameter is turned on.
3103 User
3105 Example:
3106 $User = $imap->User();
3108 # or:
3109 $imap->User($userid);
3110 Specifies the userid to use when logging into the IMAP service. Can be
3112 supplied with the "new" method call or separately by calling the User
3113 object method.
3114 Parameters can be set during "new" method invocation by passing named
3116 parameter/value pairs to the method, or later by calling the
3117 parameter's eponymous object method.
3118
3120 There are several object methods that return the status of the object.
3121 They can be used at any time to check the status of an IMAPClient
3122 object, but are particularly useful for determining the cause of
3123 failure when a connection and login are attempted as part of a single
3124 "new" method invocation. The status methods are:
3125 Escaped_results
3127 Example:
3128 my @results = $imap->Escaped_results;
3130 The Escaped_results method is almost identical to the History method.
3132 Unlike the History method, however, server output transmitted literally
3133 will be wrapped in double quotes, with all of the parentheses, double
3134 quotes, backslashes, newlines, and carriage returns escaped. If called
3135 in a scalar context, Escaped_results returns an array reference rather
3136 than an array.
3137 Escaped_results is useful if you are retrieving output and processing
3139 it manually, and you are depending on the above special characters to
3140 delimit the data. It is not useful when retrieving message contents;
3141 use message_string or body_string for that.
3142 History
3144 Example:
3145 my @history = $imap->History;
3147 The History method is almost identical to the "Results" method. Unlike
3149 the "Results" method, however, the IMAP command that was issued to
3150 create the results being returned is not included in the returned
3151 results. If called in a scalar context, History returns an array
3152 reference rather than an array.
3153 IsUnconnected
3155 returns a true value if the object is currently in an "Unconnected"
3156 state.
3157 IsConnected
3159 returns a true value if the object is currently in either a
3160 "Connected", "Authenticated", or "Selected" state.
3161 IsAuthenticated
3163 returns a true value if the object is currently in either an
3164 "Authenticated" or "Selected" state.
3165 IsSelected
3167 returns a true value if the object is currently in a "Selected" state.
3168 LastError
3170 Internally LastError is implemented just like a parameter (as described
3171 in "Parameters", above). There is a LastError attribute and an
3172 eponymous accessor method which returns the LastError text string
3173 describing the last error condition encountered by the server.
3174 Note that some errors are more serious than others, so LastError's
3176 value is only meaningful if you encounter an error condition that you
3177 don't like. For example, if you use the "exists" method to see if a
3178 folder exists and the folder does not exist, then an error message will
3179 be recorded in LastError even though this is not a particularly serious
3180 error. On the other hand, if you didn't use "exists" and just tried to
3181 "select" a non-existing folder, then "select" would return "undef"
3182 after setting LastError to something like "NO SELECT failed: Can't open
3183 mailbox "mailbox": no such mailbox". At this point it would be useful
3184 to print out the contents of LastError as you die.
3185 LastIMAPCommand
3187 New in version 2.0.4, LastIMAPCommand returns the exact IMAP command
3188 string to be sent to the server. Useful mainly in constructing error
3189 messages when "LastError" just isn't enough.
3190 Report
3192 The Report method returns an array containing a history of the IMAP
3193 session up to the point that Report was called. It is primarily meant
3194 to assist in debugging but can also be used to retrieve raw output for
3195 manual parsing. The value of the "Clear" parameter controls how many
3196 transactions are in the report.
3197 Results
3199 The Results method returns an array containing the results of one IMAP
3200 client command. It accepts one argument, the transaction number of the
3201 command whose results are to be returned. If transaction number is
3202 unspecified then Results returns the results of the last IMAP client
3203 command issued. If called in a scalar context, Results returns an
3204 array reference rather than an array.
3205 State
3207 The State method returns a numerical value that indicates the current
3208 status of the IMAPClient object. If invoked with an argument, it will
3209 set the object's state to that value. If invoked without an argument,
3210 it behaves just like "Status", below.
3211 Normally you will not have to invoke this function. An exception is if
3213 you are bypassing the Mail::IMAPClient module's "connect" and/or
3214 "login" modules to set up your own connection (say, for example, over a
3215 secure socket), in which case you must manually do what the "connect"
3216 and "login" methods would otherwise do for you.
3217 Status
3219 The Status method returns a numerical value that indicates the current
3220 status of the IMAPClient object. (Not to be confused with the "status"
3221 method, all lower-case, which is the implementation of the STATUS IMAP
3222 client command.)
3223 Transaction
3225 The Transaction method returns the tag value (or transaction number) of
3226 the last IMAP client command.
3227
3229 If you just want to use plain text authentication or any of the
3230 supported "Advanced Authentication Mechanisms" then there is no need to
3231 read this section.
3232 There are a number of methods and parameters that you can use to build
3234 your own authentication mechanism. All of the methods and parameters
3235 discussed in this section are described in more detail elsewhere in
3236 this document. This section provides a starting point for building
3237 your own authentication mechanism.
3238 There are many authentication mechanisms out there, if your preferred
3240 mechanism is not currently supported but you manage to get it working
3241 please consider donating them to this module. Patches and suggestions
3242 are always welcome.
3243 Support for add-on authentication mechanisms in Mail::IMAPClient is
3245 pretty straight forward. You create a callback to be used to provide
3246 the response to the server's challenge. The "Authcallback" parameter
3247 contains a reference to the callback, which can be an anonymous
3248 subroutine or a named subroutine. Then, you identify your
3249 authentication mechanism, either via the "Authmechanism" parameter or
3250 as an argument to "authenticate".
3251 You may also need to provide a subroutine to encrypt (or whatever) data
3253 before it is sent to the server. The "Prewritemethod" parameter must
3254 contain a reference to this subroutine. And, you will need to decrypt
3255 data from the server; a reference to the subroutine that does this must
3256 be stored in the "Readmethod" parameter.
3257 This framework is based on the assumptions that a) the mechanism you
3259 are using requires a challenge-response exchange, and b) the mechanism
3260 does not fundamentally alter the exchange between client and server but
3261 merely wraps the exchange in a layer of encryption. It also assumes
3262 that the line-oriented nature of the IMAP conversation is preserved;
3263 authentication mechanisms that break up messages into blocks of a
3264 predetermined size may still be possible but will certainly be more
3265 difficult to implement.
3266 Alternatively, if you have access to imtest, a utility included in the
3268 Cyrus IMAP distribution, you can use that utility to broker your
3269 communications with the IMAP server. This is quite easy to implement.
3270 An example, examples/imtestExample.pl, can be found in the "examples"
3271 subdirectory of the source distribution.
3272 The following list summarizes the methods and parameters that you may
3274 find useful in implementing advanced authentication:
3275 The authenticate method
3277 The "authenticate" method uses the "Authmechanism" parameter to
3278 determine how to authenticate with the server see the method
3279 documentation for details.
3280 Socket and RawSocket
3282 The "Socket" and "RawSocket" methods provide access to the socket
3283 connection. The socket is typically automatically created by the
3284 "connect" method, but if you are implementing an advanced
3285 authentication technique you may choose to set up your own socket
3286 connection and then set this parameter manually, bypassing the
3287 connect method completely. This is also useful if you want to use
3288 IO::Socket::INET alternatives like IO::Socket::SSL and need full
3289 control.
3290 "RawSocket" simply gets/sets the socket without attempting any
3292 interaction on it. In this case, you have to be sure to handle all
3293 the preliminary operations and manually set the Mail::IMAPClient
3294 object in sync with its actual status with respect to this socket
3295 (see below for additional parameters regarding this, especially the
3296 "State" parameter).
3297 Unlike "RawSocket", "Socket" attempts to carry on preliminary
3299 connection phases if the conditions apply. If both parameters are
3300 present, this takes the precedence over "RawSocket". If "Starttls"
3301 is set, then the "starttls" method will be called by "Socket".
3302 PLEASE NOTE As of version 2.99_04 of this module, semantics for
3304 "Socket" have changed to make it more "DWIM". "RawSocket" was
3305 introduced as a replacement for the "Socket" parameter in older
3306 version.
3307 State, Server, User, Password, Proxy and Domain Parameters
3309 If you need to make your own connection to the server and perform
3310 your authentication manually, then you can set these parameters to
3311 keep your Mail::IMAPClient object in sync with its actual status.
3312 Of these, only the "State" parameter is always necessary. The
3313 others need to be set only if you think your program will need them
3314 later.
3315 Authmechanism
3317 Set this to the value that AUTHENTICATE should send to the server
3318 as the authentication mechanism. If you are brokering your own
3319 authentication then this parameter may be less useful. It exists
3320 primarily so that you can set it when you call "new" to instantiate
3321 your object. The "new" method will call "connect", which will call
3322 "login". If "login" sees that you have set an Authmechanism then
3323 it will call authenticate, using your Authmechanism and
3324 Authcallback parameters as arguments.
3325 Authcallback
3327 The "Authcallback", if set, holds a pointer to a subroutine
3328 (CODEREF). The "login" method will use this as the callback
3329 argument to the authenticate method if the Authmechanism and
3330 Authcallback parameters are both set. If you set Authmechanism but
3331 not Authcallback then the default callback for your mechanism will
3332 be used. All supported authentication mechanisms have a default
3333 callback; in every other case not supplying the callback results in
3334 an error.
3335 Most advanced authentication mechanisms require a challenge-
3337 response exchange. After the "authenticate" method sends "<tag>
3338 AUTHENTICATE <Authmechanism>\015\012" to the IMAP server, the
3339 server replies with a challenge. The "authenticate" method then
3340 invokes the code whose reference is stored in the Authcallback
3341 parameter as follows:
3342 $Authcallback->($challenge, $imap)
3344 where $Authcallback is the code reference stored in the
3346 Authcallback parameter, $challenge is the challenge received from
3347 the IMAP server, and $imap is a pointer to the Mail::IMAPClient
3348 object. The return value from the Authcallback routine should be
3349 the response to the challenge, and that return value will be sent
3350 by the "authenticate" method to the server.
3351 Prewritemethod/Readmethod
3353 The Prewritemethod can hold a subroutine that will do whatever
3354 encryption is necessary and then return the result to the caller so
3355 it in turn can be sent to the server.
3356 The Readmethod can hold a subroutine to be used to replace sysread
3358 usually performed by Mail::IMAPClient.
3359 See "Prewritemethod" and "Readmethod" for details.
3361
3363 Please send bug reports to "bug-Mail-IMAPClient@rt.cpan.org" or
3364 http://rt.cpan.org/Public/Dist/Display.html?Name=Mail-IMAPClient
3365
3367 Copyright (C) 1999-2003 The Kernen Group, Inc.
3368 Copyright (C) 2007-2009 Mark Overmeer
3369 Copyright (C) 2010-2011 Phil Pearl (Lobbes)
3370 All rights reserved.
3371 This library is free software; you can redistribute it and/or modify it
3373 under the same terms as Perl itself, either Perl version 5.8.0 or, at
3374 your option, any later version of Perl 5 you may have available.
3375 This program is distributed in the hope that it will be useful, but
3377 WITHOUT ANY WARRANTY; without even the implied warranty of
3378 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
3379 GNU General Public License or the Artistic License for more details.
3380perl v5.12.3 2011-03-04 Mail::IMAPClient(3)