1IMAPClient(3) User Contributed Perl Documentation IMAPClient(3)
2
6 Mail::IMAPClient - An IMAP Client API
7
9 This module provides methods implementing the IMAP protocol. It allows
10 perl scripts to interact with IMAP message stores.
11 The module is used by constructing or instantiating a new IMAPClient
13 object via the new constructor method. Once the object has been instan‐
14 tiated, the connect method is either implicitly or explicitly called.
15 At that point methods are available that implement the IMAP client com‐
16 mands as specified in RFC2060. When processing is complete, the logoff
17 object method should be called.
18 This documentation is not meant to be a replacement for RFC2060, and
20 the wily programmer will have a copy of that document handy when coding
21 IMAP clients.
22 Note that this documentation uses the term folder in place of RFC2060's
24 use of mailbox. This documentation reserves the use of the term mailbox
25 to refer to the set of folders owned by a specific IMAP id.
26 RFC2060 defines four possible states for an IMAP connection: not
28 authenticated, authenticated, selected, and logged out. These corre‐
29 spond to the IMAPClient constants "Connected", "Authenticated",
30 "Selected", and "Unconnected", respectively. These constants are imple‐
31 mented as class methods, and can be used in conjunction with the Status
32 method to determine the status of an IMAPClient object and its underly‐
33 ing IMAP session. Note that an IMAPClient object can be in the "Uncon‐
34 nected" state both before a server connection is made and after it has
35 ended. This differs slightly from RFC2060, which does not define a pre-
36 connection status. For a discussion of the methods available for exam‐
37 ining the IMAPClient object's status, see the section labeled "Status
38 Methods", below.
39 Advanced Authentication Mechanisms
41 RFC2060 defines two commands for authenticating to an IMAP server:
43 LOGIN for plain text authentication and AUTHENTICATE for more secure
44 authentication mechanisms. Currently Mail::IMAPClient supports CRAM-MD5
45 and plain text authentication. There are also a number of methods and
46 parameters that you can use to build your own authentication mechanism.
47 Since this topic is a source of many questions, I will provide a quick
48 overview here. All of the methods and parameters discussed here are
49 described in more detail elsewhere in this document; this section is
50 meant to help you get started.
51 First of all, if you just want to do plain text authentication and your
53 server is okay with that idea then you don't even need to read this
54 section.
55 Second of all, the intent of this section is to help you implement the
57 authentication mechanism of your choice, but you will have to under‐
58 stand how that mechanism works. There are lots of authentication mech‐
59 anisms and most of them are not available to me to test with for one
60 reason or another. Even if this section does not answer all of your
61 authentication questions it does contain all the answers that I have,
62 which I admit are scant.
63 Third of all, if you manage to get any advanced authentication mecha‐
65 nisms to work then please consider donating them to this module. I
66 don't quite have a framework visualized for how different authentica‐
67 tion mechanisms could "plug in" to this module but I would like to
68 eventually see this module distributed with a number of helper modules
69 to implement various authentication schemes.
70 The Mail::IMAPClient's support for add-on authentication mechanisms is
72 pretty straight forward and is built upon several assumptions. Basi‐
73 cally you create a callback to be used to provide the response to the
74 server's challenge. The Authcallback parameter contains a reference to
75 the callback, which can be an anonymous subroutine or a named subrou‐
76 tine. Then, you identify your authentication mechanism, either via the
77 Authmechanism parameter or as an argument to authenticate.
78 You may also need to provide a subroutine to encrypt (or whatever) data
80 before it is sent to the server. The Prewritemethod parameter must con‐
81 tain a reference to this subroutine. And, you will need to decrypt
82 data from the server; a reference to the subroutine that does this must
83 be stored in the Readmethod parameter.
84 This framework is based on the assumptions that a) the mechanism you
86 are using requires a challenge-response exchange, and b) the mechanism
87 does not fundamentally alter the exchange between client and server but
88 merely wraps the exchange in a layer of encryption. It particularly
89 assumes that the line-oriented nature of the IMAP conversation is pre‐
90 served; authentication mechanisms that break up messages into blocks of
91 a predetermined size may still be possible but will certainly be more
92 difficult to implement.
93 Alternatively, if you have access to imtest, a utility included in the
95 Cyrus IMAP distribution, you can use that utility to broker your commu‐
96 nications with the IMAP server. This is quite easy to implement. An
97 example, "imtestExample.pl" in examples, can be found in the "examples"
98 subdirectory of the source distribution.
99 The following list summarizes the methods and parameters that you may
101 find useful in implementing advanced autentication:
102 authenticate method
104 This method implements the AUTHENTICATE IMAP client command as doc‐
105 umented in RFC2060. If you have set the Authmechanism parameter
106 then the login method will call authenticate instead of doing a
107 clear text login, which is its normal behavior. If you don't want
108 login to call authenticate on your behalf then you can call it
109 yourself. Instead of setting an Authmechanism you can just pass the
110 authmechanism as the first argument to AUTHENTICATE.
111 Socket Parameter
113 The Socket parameter holds a reference to the socket connection.
114 Normally this is set for you by the connect method, but if you are
115 implementing an advanced authentication technique you may choose to
116 set up your own socket connection and then set this parameter manu‐
117 ally, bypassing the connect method completely.
118 State, Server, Password, and User Parameters
120 If you need to make your own connection to the server and perform
121 your authentication manually, then you can set these parameters to
122 keep your Mail::IMAPClient object in sync with its actual status.
123 Of these, only the State parameter is always necessary. The others
124 need to be set only if you think your program will need them later.
125 Authmechanism
127 Set this to the value that AUTHENTICATE should send to the server
128 as the authentication mechanism. If you are brokering your own
129 authentication then this parameter may be less useful. It is also
130 not needed by the authenticate method. It exists solely so that you
131 can set it when you call new to instantiate your object. The new
132 method will call connect, who will call login. If login sees that
133 you've set an Authmechanism then it will call authenticate, using
134 your Authmechanism and Authcallback parameters as arguments.
135 Authcallback
137 The Authcallback parameter, if set, should contain a pointer to a
138 subroutine. The login method will use this as the callback argument
139 to the authenticate method if the Authmechanism and Authcallback
140 parameters are both set. If you set Authmechanism but not Authcall‐
141 back then the default callback for your mechanism will be used.
142 Unfortunately only the CRAM-MD5 authentication mechanism has a
143 default callback; in every other case not supplying the callback
144 results in an error.
145 Most advanced authentication mechanisms require a challenge-
147 response exchange. After the authenticate method sends "<tag>
148 AUTHENTICATE <Authmechanism>\r\n" to the IMAP server, the server
149 replies with a challenge. The authenticate method then invokes the
150 code whose reference is stored in the Authcallback parameter as
151 follows:
152 $Authcallback->($challenge,$imap)
154 where $Authcallback is the code reference stored in the Authcall‐
156 back parameter, $challenge is the challenge received from the IMAP
157 server, and $imap is a pointer to the Mail::IMAPClient object. The
158 return value from the Authcallback routine should be the response
159 to the challenge, and that return value will be sent by the authen‐
160 ticate method to the server.
161 Readmethod
163 The Readmethod parameter points to a routine that will read data
164 from the socket connection. This read method will replace the sys‐
165 read that would otherwise be performed by Mail::IMAPClient. The
166 replacement method is called with five arguments. The first is a
167 pointer to the Mail::IMAPClient object; the rest are the four argu‐
168 ments required by the sysread function. Note the third argument
169 (which corresponds to the second argument to sysread) is a buffer
170 to read into; this will be a pointer to a scalar. So for example if
171 your Readmethod were just going to replace sysread without any
172 intervening processing (which would be silly but this is just an
173 example after all) then you would set your Readmethod like this:
174 $imap->Readmethod(
176 sub {
177 my($self) = shift;
178 my($handle,$buffer,$count,$offset) = @_;
179 return sysread( $handle, $$buffer, $count, $offset);
180 }
181 );
182 Note particularly the double dollar signs in $$buffer in the sys‐
184 read call; this is not a typo!
185 Prewritemethod
187 The Prewritemethod, if defined, should contain a pointer to a sub‐
188 routine. It is called immediately prior to writing to the socket
189 connection. It is called by Mail::IMAPClient with two arguments: a
190 reference to the Mail::IMAPClient object and the ASCII text string
191 to be written. It should return another string that will be the
192 actual string sent to the IMAP server. The idea here is that your
193 Prewritemethod will do whatever encryption is necessary and then
194 return the result to the caller so it in turn can be sent to the
195 server.
196 Errors
198 If you attempt an operation that results in an error, then you can
200 retrieve the text of the error message by using the LastError method.
201 However, since the LastError method is an object method (and not a
202 class method) you will only be able to use this method if you've suc‐
203 cessfully created your object. Errors in the new method can prevent
204 your object from ever being created. Additionally, if you supply the
205 Server, User, and Password parameters to new, it will attempt to call
206 connect and login, either of which could fail and cause your new method
207 call to return "undef" (in which case your object will have been cre‐
208 ated but its reference will have been discarded before ever having been
209 returned to you).
210 If this happens to you, you can always check $@. Mail::IMAPClient will
212 populate that variable with something useful if either of the new, con‐
213 nect, or login methods fail. In fact, as of version 2, the $@ variable
214 will always contain error info from the last error, so you can print
215 that instead of calling LastError if you wish.
216 If you run your script with warnings turned on (which I'm sure you'll
218 do at some point because it's such a good idea) then any error message
219 that gets placed into the LastError slot (and/or in $@) will automati‐
220 cally generate a warning.
221 Transactions
223 RFC2060 requires that each line in an IMAP conversation be prefixed
225 with a tag. A typical conversation consists of the client issuing a
226 tag-prefixed command string, and the server replying with one of more
227 lines of output. Those lines of output will include a command comple‐
228 tion status code prefixed by the same tag as the original command
229 string.
230 The IMAPClient module uses a simple counter to ensure that each client
232 command is issued with a unique tag value. This tag value is referred
233 to by the IMAPClient module as the transaction number. A history is
234 maintained by the IMAPClient object documenting each transaction. The
235 Transaction method returns the number of the last transaction, and can
236 be used to retrieve lines of text from the object's history.
237 The Clear parameter is used to control the size of the session history
239 so that long-running sessions do not eat up unreasonable amounts of
240 memory. See the discussion of Clear under "Parameters" for more infor‐
241 mation.
242 The Report transaction returns the history of the entire IMAP session
244 since the initial connection or for the last Clear transactions. This
245 provides a record of the entire conversation, including client command
246 strings and server responses, and is a wonderful debugging tool as well
247 as a useful source of raw data for custom parsing.
248
250 There are a couple of methods that can be invoked as class methods.
251 Generally they can be invoked as an object method as well, as a conve‐
252 nience to the programmer. (That is, as a convenience to the programmer
253 who wrote this module, as well as the programmers using it. It's eas‐
254 ier not to enforce a class method's classiness.) Note that if the new
255 method is called as an object method, the object returned is identical
256 to what have would been returned if new had been called as a class
257 method. It doesn't give you a copy of the original object or anything
258 like that.
259 new
261 Example:
263 Mail::IMAPClient->new(%args) or die "Could not new: $@\n";
265 The new method creates a new instance of an IMAPClient object. If the
267 Server parameter is passed as an argument to new, then new will implic‐
268 itly call the connect method, placing the new object in the Connected
269 state. If User and Password values are also provided, then connect will
270 in turn call login, and the resulting object will be returned from new
271 in the Authenticated state.
272 If the Server parameter is not supplied then the IMAPClient object is
274 created in the Unconnected state.
275 If the new method is passed arguments then those arguments will be
277 treated as a list of key=>value pairs. The key should be one of the
278 parameters as documented under "Parameters", below.
279 Here are some examples:
281 use Mail::IMAPClient;
283 # returns an unconnected Mail::IMAPClient object:
285 my $imap = Mail::IMAPClient->new;
286 # ...
287 # intervening code using the 1st object, then:
288 # (returns a new, authenticated Mail::IMAPClient object)
289 $imap = Mail::IMAPClient->new(
290 Server => $host,
291 User => $id,
292 Password=> $pass,
293 Clear => 5, # Unnecessary since '5' is the default
294 # ... # Other key=>value pairs go here
295 ) or die "Cannot connect to $host as $id: $@";
296 See also "Parameters", below, and "connect" and "login" for information
298 on how to manually connect and login after new.
299 Authenticated
301 Example:
303 $Authenticated = $imap->Authenticated();
305 # or:
306 $imap->Authenticated($new_value); # But you'll probably never need to do this
307 returns a value equal to the numerical value associated with an object
309 in the Authenticated state. This value is normally maintained by the
310 Mail::IMAPClient module, so you typically will only query it and won't
311 need to set it.
312 NOTE: For a more programmer-friendly idiom, see the IsUnconnected,
314 IsConnected, IsAuthenticated, and IsSelected object methods. You will
315 usually want to use those methods instead of one of the above.
316 Connected
318 Example:
320 $Connected = $imap->Connected();
322 # or:
323 $imap->Connected($new_value); # But you'll probably never need to do this
324 returns a value equal to the numerical value associated with an object
326 in the Connected state. This value is normally maintained by the
327 Mail::IMAPClient module, so you typically will only query it and won't
328 need to set it.
329 NOTE: For a more programmer-friendly idiom, see the IsUnconnected,
331 IsConnected, IsAuthenticated, and IsSelected object methods. You will
332 usually want to use those methods instead of one of the above.
333 Quote
335 Example:
337 $imap->search(HEADER => 'Message-id' => $imap->Quote($msg_id));
339 The Quote method accepts a value as an argument. It returns its argu‐
341 ment as a correctly quoted string or a literal string.
342 Note that you should not use this on folder names, since methods that
344 accept folder names as an argument will quote the folder name arguments
345 appropriately for you. (Exceptions to this rule are methods that come
346 with IMAP extensions that are not explicitly supported by Mail::IMAP‐
347 Client.)
348 If you are getting unexpected results when running methods with values
350 that have (or might have) embedded spaces, double quotes, braces, or
351 parentheses, then you may wish to call Quote to quote these values. You
352 should not use this method with foldernames or with arguments that are
353 wrapped in quotes or parens if those quotes or parens are there because
354 the RFC2060 spec requires them. So, for example, if RFC requires an
355 argument in this format:
356 ( argument )
358 and your argument is (or might be) "pennies (from heaven)", then you
360 could just use:
361 $argument = "(" . $imap->Quote($argument) . ")"
363 and be done with it.
365 Of course, the fact that sometimes these characters are sometimes
367 required delimiters is precisely the reason you must quote them when
368 they are not delimiting. For example:
369 $imap->Search('SUBJECT',"(no subject)");
371 # WRONG! Sends this to imap server:
372 #<TAG> Search SUBJECT (no subject)\r\n
373 $imap->Search('SUBJECT',$imap->Quote("(no subject)"));
375 # Correct! Sends this to imap server:
376 #<TAG> Search SUBJECT "(no subject)"\r\n
377 On the other hand:
379 $imap->store('+FLAGS',$imap->Quote("(\Deleted)"));
381 # WRONG! Sends this to imap server:
382 #<TAG> [UID] STORE +FLAGS "(\Deleted)"\r\n
383 $imap->store($imap->Quota('+FLAGS'),"(\Deleted)");
385 # CORRECT! Sends this to imap server:
386 #<TAG> [UID] STORE +FLAGS (\Deleted)\r\n
387 In the above, I had to abandon the many methods available to
389 Mail::IMAPClient programmers (such as delete_message and all-lowercase
390 search) for the sake of coming up with an example. However, there are
391 times when unexpected values in certain places will force you to Quote.
392 An example is RFC822 Message-id's, which usually don't contain quotes
393 or parens. So you don't worry about it, until suddenly searches for
394 certain message-id's fail for no apparent reason. (A failed search is
395 not simply a search that returns no hits; it's a search that flat out
396 didn't happen.) This normally happens to me at about 5:00 pm on the
397 one day when I was hoping to leave on time. (By the way, my experience
398 is that any character that can possibly find its way into a Message-Id
399 eventually will, so when dealing with these values take proactive,
400 defensive measures from the very start. In fact, as I was typing the
401 above, a buddy of mine came in to ask advice about a logfile parsing
402 routine he was writing in which the fields were delimited by colons.
403 One of the fields was a Message Id, and, you guessed it, some of the
404 message id's in the log had (unescaped!) colons embedded in them and
405 were screwing up his "split()". So there you have it, it's not just
406 me. This is everyone's problem.)
407 Range
409 Example:
411 my %parsed = $imap->parse_headers(
413 $imap->Range($imap->messages),
414 "Date",
415 "Subject"
416 );
417 The Range method will condense a list of message sequence numbers or
419 message UID's into the most compact format supported by RFC2060. It
420 accepts one or more arguments, each of which can be:
421 a) a message number,
423 b) a comma-separated list of message numbers,
424 c) a colon-separated range of message numbers (i.e. "$begin:$end")
425 d) a combination of messages and message ranges, separated by commas
426 (i.e. 1,3,5:8,10), or
427 e) a reference to an array whose elements are like a) through d).
428 The Range method returns a reference to a Mail::IMAPClient::MessageSet
430 object. The object has all kinds of magic properties, one of which
431 being that if you treat it as if it were just a string it will act like
432 it's just a string. This means you can ignore its objectivity and just
433 treat it like a string whose value is your message set expressed in
434 compact format.
435 You may want to use this method if you find that fetch operations on
437 large message sets seem to take a really long time, or if your server
438 rejects these requests with the claim that the input line is too long.
439 You may also want to use this if you need to add or remove messages to
440 your message set and want an easy way to manage this.
441 For more information on the capabilities of the returned object refer‐
443 ence, see Mail::IMAPClient::MessageSet.
444 Rfc2060_date
446 Example:
448 $Rfc2060_date = $imap->Rfc2060_date($seconds);
450 # or:
451 $Rfc2060_date = Mail::IMAPClient->Rfc2060_date($seconds);
452 The Rfc2060_date method accepts one input argument, a number of seconds
454 since the epoch date. It returns an RFC2060 compliant date string for
455 that date (as required in date-related arguments to SEARCH, such as
456 "since", "before", etc.).
457 Rfc822_date
459 Example:
461 $Rfc822_date = $imap->Rfc822_date($seconds);
463 # or:
464 $Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
465 The Rfc822_date method accepts one input argument, a number of seconds
467 since the epoch date. It returns an RFC822 compliant date string for
468 that date (without the 'Date:' prefix). Useful for putting dates in
469 message strings before calling append, search, etcetera.
470 Selected
472 Example:
474 $Selected = $imap->Selected();
476 # or:
477 $imap->Selected($new_value); # But you'll probably never need to do this
478 returns a value equal to the numerical value associated with an object
480 in the Selected state. This value is normally maintained by the
481 Mail::IMAPClient module, so you typically will only query it and won't
482 need to set it.
483 NOTE: For a more programmer-friendly idiom, see the IsUnconnected,
485 IsConnected, IsAuthenticated, and IsSelected object methods. You will
486 usually want to use those methods instead of one of the above.
487 Strip_cr
489 Example:
491 $Strip_cr = $imap->Strip_cr();
493 # or:
494 $imap->Strip_cr($new_value);
495 The Strip_cr method strips carriage returns from IMAP client command
497 output. Although RFC2060 specifies that lines in an IMAP conversation
498 end with <CR><LF>, it is often cumbersome to have the carriage returns
499 in the returned data. This method accepts one or more lines of text as
500 arguments, and returns those lines with all <CR><LF> sequences changed
501 to <LF>. Any input argument with no carriage returns is returned
502 unchanged. If the first argument (not counting the class name or object
503 reference) is an array reference, then members of that array are pro‐
504 cessed as above and subsequent arguments are ignored. If the method is
505 called in scalar context then an array reference is returned instead of
506 an array of results.
507 Taken together, these last two lines mean that you can do something
509 like:
510 my @list = $imap->some_imap_method ;
512 @list = $imap->Strip_cr(@list) ;
513 # or:
514 my $list = [ $imap->some_imap_method ] ; # returns an array ref
515 $list = $imap->Strip_cr($list);
516 NOTE: Strip_cr does not remove new line characters.
518 Unconnected
520 Example:
522 $Unconnected = $imap->Unconnected();
524 # or:
525 $imap->Unconnected($new_value);
526 returns a value equal to the numerical value associated with an object
528 in the Unconnected state. This value is normally maintained by the
529 Mail::IMAPClient module, so you typically will only query it and won't
530 need to set it.
531 NOTE: For a more programmer-friendly idiom, see the IsUnconnected,
533 IsConnected, IsAuthenticated, and IsSelected object methods. You will
534 usually want to use those methods instead of one of the above.
535
537 Object methods must be invoked against objects created via the new
538 method. They cannot be invoked as class methods, which is why they are
539 called "object methods" and not "class methods".
540 There are basically two types of object methods--mailbox methods, which
542 participate in the IMAP session's conversation (i.e. they issue IMAP
543 client commands) and object control methods, which do not result in
544 IMAP commands but which may affect later commands or provide details of
545 previous ones. This latter group can be further broken down into two
546 types, Parameter accessor methods, which affect the behavior of future
547 mailbox methods, and Status methods, which report on the affects of
548 previous mailbox methods.
549 Methods that do not result in new IMAP client commands being issued
551 (such as the Transaction, Status, and History methods) all begin with
552 an uppercase letter, to distinguish them from methods that do corre‐
553 spond to IMAP client commands. Class methods and eponymous parameter
554 methods likewise begin with an uppercase letter because they also do
555 not correspond to an IMAP client command.
556 As a general rule, mailbox control methods return "undef" on failure
558 and something besides "undef" when they succeed. This rule is modified
559 in the case of methods that return search results. When called in a
560 list context, searches that do not find matching results return an
561 empty list. When called in a scalar context, searches with no hits
562 return 'undef' instead of an array reference. If you want to know why
563 you received no hits, you should check $@, which will be empty if the
564 search was successful but had no matching results but populated with an
565 error message if the search encountered a problem (such as invalid
566 parameters).
567 A number of IMAP commands do not have corresponding Mail::IMAPClient
569 methods. Instead, they are implemented via a default method and Perl's
570 AUTOLOAD facility. If you are looking for a specific IMAP client com‐
571 mand (or IMAP extension) and do not see it documented in this pod, then
572 that does not necessarily mean you can not use Mail::IMAPClient to
573 issue the command. In fact, you can issue almost any IMAP client com‐
574 mand simply by pretending that there is a corresponding Mail::IMAP‐
575 Client method. See the section on "Other IMAP Client Commands and the
576 Default Object Method" below for details on the default method.
577
579 append
580 Example:
582 my $uid = $imap->append($folder,$msg_text)
584 or die "Could not append: $@\n";
585 The append method adds a message to the specified folder. It takes two
587 arguments, the name of the folder to append the message to, and the
588 text of the message (including headers). Additional arguments are added
589 to the message text, separated with <CR><LF>.
590 The append method returns the UID of the new message (a true value) if
592 successful, or "undef" if not, if the IMAP server has the UIDPLUS capa‐
593 bility. If it doesn't then you just get true on success and undef on
594 failure.
595 Note that many servers will get really ticked off if you try to append
597 a message that contains "bare newlines", which is the titillating term
598 given to newlines that are not preceded by a carrage return. To protect
599 against this, append will insert a carrage return before any newline
600 that is "bare". If you don't like this behavior then you can avoid it
601 by not passing naked newlines to append.
602 Note that append does not allow you to specify the internal date or
604 initial flags of an appended message. If you need this capability then
605 use append_string, below.
606 append_file
608 Example:
610 my $new_msg_uid = $imap->append_file(
612 $folder,
613 $filename
614 [ , $input_record_separator ] # optional (not arrayref)
615 ) or die "Could not append_file: $@\n";
616 The append_file method adds a message to the specified folder. It takes
618 two arguments, the name of the folder to append the message to, and the
619 file name of an RFC822-formatted message.
620 An optional third argument is the value to use for "input_record_sepa‐
622 rator". The default is to use "" for the first read (to get the head‐
623 ers) and "\n" for the rest. Any valid value for $/ is acceptable, even
624 the funky stuff, like "\1024". (See perlvar for more information on
625 $/). (The brackets in the example indicate that this argument is
626 optional; they do not mean that the argument should be an array refer‐
627 ence.)
628 The append_file method returns the UID of the new message (a true
630 value) if successful, or "undef" if not, if the IMAP server has the
631 UIDPLUS capability. If it doesn't then you just get true on success and
632 undef on failure. If you supply a filename that doesn't exist then you
633 get an automatic "undef". The LastError method will remind you of this
634 if you forget that your file doesn't exist but somehow manage to remem‐
635 ber to check LastError.
636 In case you're wondering, append_file is provided mostly as a way to
638 allow large messages to be appended without having to have the whole
639 file in memory. It uses the "-s" operator to obtain the size of the
640 file and then reads and sends the contents line by line (or not,
641 depending on whether you supplied that optional third argument).
642 append_string
644 Example:
646 # brackets indicate optional arguments (not array refs):
648 my $uid = $imap->append_string( $folder, $text [ , $flags [ , $date ] ])
650 or die "Could not append_string: $@\n";
651 The append_string method adds a message to the specified folder. It
653 requires two arguments, the name of the folder to append the message
654 to, and the text of the message (including headers). The message text
655 must be included in a single string (unlike append, above).
656 You can optionally specify a third and fourth argument to
658 append_string. The third argument, if supplied, is the list of flags to
659 set for the appended message. The list must be specified as a space-
660 separated list of flags, including any backslashes that may be neces‐
661 sary. The enclosing parentheses that are required by RFC2060 are
662 optional for append_string. The fourth argument, if specified, is the
663 date to set as the internal date. It should be in the format described
664 for date_time fields in RFC2060, i.e. "dd-Mon-yyyy hh:mm:ss +0000".
665 If you want to specify a date/time but you don't want any flags then
667 specify undef as the third argument.
668 The append_string method returns the UID of the new message (a true
670 value) if successful, or "undef" if not, if the IMAP server has the
671 UIDPLUS capability. If it doesn't then you just get true on success and
672 undef on failure.
673 Note that many servers will get really ticked off if you try to append
675 a message that contains "bare newlines", which is the titillating term
676 given to newlines that are not preceded by a carrage return. To protect
677 against this, append_string will insert a carrage return before any
678 newline that is "bare". If you don't like this behavior then you can
679 avoid it by not passing naked newlines to append_string.
680 authenticate
682 Example:
684 $imap->authenticate($authentication_mechanism, $coderef)
686 or die "Could not authenticate: $@\n";
687 The authenticate method accepts two arguments, an authentication type
689 to be used (ie CRAM-MD5) and a code or subroutine reference to execute
690 to obtain a response. The authenticate method assumes that the authen‐
691 tication type specified in the first argument follows a challenge-
692 response flow. The authenticate method issues the IMAP Client AUTHENTI‐
693 CATE command and receives a challenge from the server. That challenge
694 (minus any tag prefix or enclosing '+' characters but still in the
695 original base64 encoding) is passed as the only argument to the code or
696 subroutine referenced in the second argument. The return value from the
697 2nd argument's code is written to the server as is, except that a
698 <CR><NL> sequence is appended if neccessary.
699 If one or both of the arguments are not specified in the call to
701 authenticate but their corresponding parameters have been set (Auth‐
702 mechanism and Authcallback, respectively) then the parameter values are
703 used. Arguments provided to the method call however will override
704 parameter settings.
705 If you do not specify a second argument and you have not set the Auth‐
707 callback parameter, then the first argument must be one of the authen‐
708 tication mechanisms for which Mail::IMAPClient has built in support.
709 Currently there is only built in support for CRAM-MD5, but I hope to
710 add more in future releases.
711 If you are interested in doing NTLM authentication then please see Mark
713 Bush's Authen::NTLM, which can work with Mail::IMAPClient to provide
714 NTLM authentication.
715 See also the login method, which is the simplest form of authentication
717 defined by RFC2060.
718 before
720 Example:
722 my @msgs = $imap->before($Rfc2060_date)
724 or warn "No messages found before $Rfc2060_date.\n";
725 The before method works just like the "since" method, below, except it
727 returns a list of messages whose internal system dates are before the
728 date supplied as the argument to the before method.
729 body_string
731 Example:
733 my $string = $imap->body_string($msgId)
735 or die "Could not body_string: $@\n";
736 The body_string method accepts a message sequence number (or a message
738 UID, if the Uid parameter is set to true) as an argument and returns
739 the message body as a string. The returned value contains the entire
740 message in one scalar variable, without the message headers.
741 bodypart_string
743 Example:
745 my $string=$imap->bodypart_string( $msgid, $part_number ,
747 $length ,$offset
748 ) or die "Could not get bodypart string: $@\n";
749 The bodypart_string method accepts a message sequence number (or a mes‐
751 sage UID, if the Uid parameter is set to true) and a body part as argu‐
752 ments and returns the message part as a string. The returned value con‐
753 tains the entire message part (or, optionally, a portion of the part)
754 in one scalar variable.
755 If an optional third argument is provided, that argument is the number
757 of bytes to fetch. (The default is the whole message part.) If an
758 optional fourth argument is provided then that fourth argument is the
759 offset into the part at which the fetch should begin. The default is
760 offset zero, or the beginning of the message part.
761 If you specify an offset without specifying a length then the offset
763 will be ignored and the entire part will be returned.
764 bodypart_string will return "undef" if it encounters an error.
766 capability
768 Example:
770 my @features = $imap->capability
772 or die "Could not determine capability: $@\n";
773 The capability method returns an array of capabilities as returned by
775 the CAPABILITY IMAP Client command, or a reference to an array of capa‐
776 bilities if called in scalar context. If the CAPABILITY IMAP Client
777 command fails for any reason then the capability method will return
778 "undef".
779 close
781 Example:
783 $imap->close or die "Could not close: $@\n";
785 The close method is implemented via the default method and is used to
787 close the currently selected folder via the CLOSE IMAP client command.
788 According to RFC2060, the CLOSE command performs an implicit EXPUNGE,
789 which means that any messages that you've flagged as \Deleted (say,
790 with the delete_message method) will now be deleted. If you haven't
791 deleted any messages then close can be thought of as an "unselect".
792 Note again that this closes the currently selected folder, not the IMAP
794 session.
795 See also delete_message, expunge, and your tattered copy of RFC2060.
797 connect
799 Example:
801 $imap->connect or die "Could not connect: $@\n";
803 The connect method connects an imap object to the server. It returns
805 "undef" if it fails to connect for any reason. If values are available
806 for the User and Password parameters at the time that connect is
807 invoked, then connect will call the login method after connecting and
808 return the result of the login method to connect's caller. If either or
809 both of the User and Password parameters are unavailable but the con‐
810 nection to the server succeeds then connect returns a pointer to the
811 IMAPClient object.
812 The Server parameter must be set (either during new method invocation
814 or via the Server object method) before invoking connect. If the Server
815 parameter is supplied to the new method then connect is implicitly
816 called during object construction.
817 The connect method sets the state of the object to "connected" if it
819 successfully connects to the server. It returns "undef" on failure.
820 copy
822 Example:
824 # Here brackets indicate optional arguments:
826 my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
827 or die "Could not copy: $@\n";
828 Or:
830 # Now brackets indicate an array ref!
832 my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
833 or die "Could not copy: $@\n";
834 The copy method requires a folder name as the first argument, and a
836 list of one or more messages sequence numbers (or messages UID's, if
837 the UID parameter is set to a true value). The message sequence numbers
838 or UID's should refer to messages in the currenly selected folder.
839 Those messages will be copied into the folder named in the first argu‐
840 ment.
841 The copy method returns "undef" on failure and a true value if success‐
843 ful. If the server to which the current Mail::IMAPClient object is con‐
844 nected supports the UIDPLUS capability then the true value returned by
845 copy will be a comma separated list of UID's, which are the UID's of
846 the newly copied messages in the target folder.
847 create
849 Example:
851 $imap->create($new_folder)
853 or die "Could not create $new_folder: $@\n";
854 The create method accepts one argument, the name of a folder (or what
856 RFC2060 calls a "mailbox") to create. If you specifiy additional argu‐
857 ments to the create method and your server allows additional arguments
858 to the CREATE IMAP client command then the extra argument(s) will be
859 passed to your server.
860 If you specifiy additional arguments to the create method and your
862 server does not allow additional arguments to the CREATE IMAP client
863 command then the extra argument(s) will still be passed to your server
864 and the create will fail, so don't do that.
865 create returns a true value on success and "undef" on failure, as
867 you've probably guessed.
868 date
870 Example:
872 my $date = $imap->date($msg);
874 The date method accepts one argument, a message sequence number (or a
876 message UID if the Uid parameter is set to a true value). It returns
877 the date of message as specified in the message's RFC822 "Date: "
878 header, without the "Date: " prefix.
879 The date method is a short-cut for:
881 my $date = $imap->get_header($msg,"Date");
883 delete
885 Example:
887 $imap->delete($folder) or die "Could not delete $folder: $@\n";
889 The delete method accepts a single argument, the name of a folder to
891 delete. It returns a true value on success and "undef" on failure.
892 delete_message
894 Example:
896 my @msgs = $imap->seen;
898 scalar(@msgs) and $imap->delete_message(\@msgs)
899 or die "Could not delete_message: $@\n";
900 The above could also be rewritten like this:
902 # scalar context returns array ref
904 my $msgs = scalar($imap->seen);
905 scalar(@$msgs) and $imap->delete_message($msgs)
907 or die "Could not delete_message: $@\n";
908 Or, as a one-liner:
910 $imap->delete_message( scalar($imap->seen) )
912 or warn "Could not delete_message: $@\n";
913 # just give warning in case failure is
914 # due to having no 'seen' msgs in the 1st place!
915 The delete_message method accepts a list of arguments. If the Uid
917 parameter is not set to a true value, then each item in the list should
918 be either:
919 > a message sequence number,
921 > a comma-separated list of message sequence numbers,
922 > a reference to an array of message sequence numbers, or
923 If the Uid parameter is set to a true value, then each item in the list
925 should be either:
926 > a message UID,
928 > a comma-separated list of UID's, or
929 > a reference to an array of message UID's.
930 The messages identified by the sequence numbers or UID's will be
932 deleted. If successful, delete_message returns the number of messages
933 it was told to delete. However, since the delete is done by issuing the
934 +FLAGS.SILENT option of the STORE IMAP client command, there is no
935 guarantee that the delete was successful for every message. In this
936 manner the delete_message method sacrifices accuracy for speed. Gener‐
937 ally, though, if a single message in a list of messages fails to be
938 deleted it's because it was already deleted, which is what you wanted
939 anyway so why worry about it? If there is a more severe error, i.e. the
940 server replies "NO", "BAD", or, banish the thought, "BYE", then
941 delete_message will return "undef".
942 If you must have guaranteed results then use the IMAP STORE client com‐
944 mand (via the default method) and use the +FLAGS (\Deleted) option, and
945 then parse your results manually.
946 Eg:
948 $imap->store($msg_id,'+FLAGS (\Deleted)');
950 my @results = $imap->History($imap->Transaction);
951 ... # code to parse output goes here
952 (Frankly I see no reason to bother with any of that; if a message
954 doesn't get deleted it's almost always because it's already not there,
955 which is what you want anyway. But 'your milage may vary' and all
956 that.)
957 The IMAPClient object must be in "Selected" status to use the
959 delete_message method.
960 NOTE: All the messages identified in the input argument(s) must be in
962 the currently selected folder. Failure to comply with this requirement
963 will almost certainly result in the wrong message(s) being deleted.
964 This would be a crying shame.
965 NOTE SOME MORE: In the grand tradition of the IMAP protocol, deleting a
967 message doesn't actually delete the message. Really. If you want to
968 make sure the message has been deleted, you need to expunge the folder
969 (via the expunge method, which is implemented via the default method).
970 Or at least close it. This is generally considered a feature, since
971 after deleting a message, you can change your mind and undelete it at
972 any time before your expunge or close.
973 See also: The delete method, to delete a folder, the expunge method, to
975 expunge a folder, the restore_message method to undelete a message, and
976 the close method (implemented here via the default method) to close a
977 folder. Oh, and don't forget about RFC2060.
978 deny_seeing
980 Example:
982 # Reset all read msgs to unread
984 # (produces error if there are no seen msgs):
985 $imap->deny_seeing( scalar($imap->seen) )
986 or die "Could not deny_seeing: $@\n" ;
987 The deny_seeing method accepts a list of one or more message sequence
989 numbers, or a single reference to an array of one or more message
990 sequence numbers, as its argument(s). It then unsets the "\Seen" flag
991 for those messages (so that you can "deny" that you ever saw them). Of
992 course, if the Uid parameter is set to a true value then those message
993 sequence numbers should be unique message id's.
994 Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
996 specifying "$imap->unset_flag("Seen",@msgs)".
997 disconnect
999 Example:
1001 $imap->disconnect or warn "Could not disconnect: $@\n";
1003 Disconnects the IMAPClient object from the server. Functionally equiva‐
1005 lent to the logout method. (In fact it's actually a synonym for
1006 logout.)
1007 done
1009 Example:
1011 my $idle = $imap->idle or warn "Couldn't idle: $@\n";
1013 &goDoOtherThings;
1014 $imap->done($idle) or warn "Error from done: $@\n";
1015 The done method tells the IMAP server that the connection is finished
1017 idling. See idle for more information. It accepts one argument, which
1018 is the transaction number you received from the previous call to idle.
1019 If you pass the wrong transaction number to done then your perl program
1021 will probably hang. If you don't pass any transaction number to done
1022 then it will try to guess, and if it guesses wrong it will hang.
1023 If you call done without previously having called idle then your server
1025 will mysteriously respond with * BAD Invalid tag.
1026 If you try to run any other mailbox method after calling idle but
1028 before calling done, then that method will not only fail but also take
1029 you out of the IDLE state. This means that when you eventually remember
1030 to call done you will just get that * BAD Invalid tag thing again.
1031 examine
1033 Example:
1035 $imap->examine($folder) or die "Could not examine: $@\n";
1037 The examine method selects a folder in read-only mode and changes the
1039 object's state to "Selected". The folder selected via the examine
1040 method can be examined but no changes can be made unless it is first
1041 selected via the select method.
1042 The examine method accepts one argument, which is the name of the
1044 folder to select.
1045 exists
1047 Example:
1049 $imap->exists($folder) or warn "$folder not found: $@\n";
1051 Accepts one argument, a folder name. Returns true if the folder exists
1053 or false if it does not exist.
1054 expunge
1056 Example:
1058 $imap->expunge($folder) or die "Could not expunge: $@\n";
1060 The expunge method accepts one optional argument, a folder name. It
1062 expunges the folder specified as the argument, or the currently
1063 selected folder if no argument is supplied.
1064 Although RFC2060 does not permit optional arguments (like a folder
1066 name) to the EXPUNGE client command, the expunge method does, which is
1067 especially interesting given that the expunge method doesn't techni‐
1068 cally exist. In case you're curious, expunging a folder deletes the
1069 messages that you thought were already deleted via delete_message but
1070 really weren't, which means you have to use a method that doesn't exist
1071 to delete messages that you thought didn't exist. (Seriously, I'm not
1072 making any of this stuff up.)
1073 Or you could use the close method, which de-selects as well as expunges
1075 and which likewise doesn't technically exist. As with any IMAP client
1076 command, that fact that these methods don't exist will not stop them
1077 from working anyway. This is a feature of the Mail::IMAPClient module.
1078 (See "Other IMAP Client Commands and the Default Object Method" if you
1079 still don't believe me.)
1080 fetch
1082 Example:
1084 my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
1086 The fetch method implements the FETCH IMAP client command. It accepts a
1088 list of arguments, which will be converted into a space-delimited list
1089 of arguments to the FETCH IMAP client command. If no arguments are sup‐
1090 plied then fetch does a FETCH ALL. If the Uid parameter is set to a
1091 true value then the first argument will be treated as a UID or list of
1092 UID's, which means that the UID FETCH IMAP client command will be run
1093 instead of FETCH. (It would really be a good idea at this point to
1094 review RFC2060.)
1095 If called in array context, fetch will return an array of output lines.
1097 The output lines will be returned just as they were received from the
1098 server, so your script will have to be prepared to parse out the bits
1099 you want. The only exception to this is literal strings, which will be
1100 inserted into the output line at the point at which they were encoun‐
1101 tered (without the {nnn} literal field indicator). See RFC2060 for a
1102 description of literal fields.
1103 If fetch is called in a scalar context, then a reference to an array
1105 (as described above) is returned instead of the entire array.
1106 fetch returns "undef" on failure. Inspect LastError or $@ for an expla‐
1108 nation of your error.
1109 fetch_hash
1111 Example: my $hashref = {} ;
1113 $imap->fetch_hash("RFC822.SIZE",$hashref) ; print "Msg #$m is
1114 $hashref->{$m} bytes\n" foreach my $m (keys %$hashref);
1115 The fetch_hash method accepts a list of message attributes to be
1117 fetched (as described in RFC2060). It returns a hash whose keys are all
1118 the messages in the currently selected folder and whose values are key-
1119 value pairs of fetch keywords and the message's value for that keyword
1120 (see sample output below).
1121 If fetch_hash is called in scalar context, it returns a reference to
1123 the hash instead of the hash itself. If the last argument is a hash
1124 reference, then that hash reference will be used as the place where
1125 results are stored (and that reference will be returned upon successful
1126 completion). If the last argument is not a reference then it will be
1127 treated as one of the FETCH attributes and a new hash will be created
1128 and returned (either by value or by reference, depending on the context
1129 in which fetch_hash was called).
1130 For example, if you have a folder with 3 messages and want the size and
1132 internal date for each of them, you could do the following:
1133 use Mail::IMAPClient;
1135 use Data::Dumper;
1136 # ... other code goes here
1137 $imap->select($folder);
1138 my $hash = $imap->fetch_hash("RFC822.SIZE","INTERNALDATE");
1139 # (Same as:
1140 # my $hash = $imap->fetch_hash("RFC822.SIZE");
1141 # $imap->fetch_hash("INTERNALDATE",$hash);
1142 # ).
1143 print Data::Dumper->Dumpxs([$hash],['$hash']);
1144 This would result in Data::Dumper output similar to the following:
1146 $hash = {
1148 '1' => {
1149 'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
1150 'RFC822.SIZE' => '1586',
1151 },
1152 '2' => {
1153 'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
1154 'RFC822.SIZE' => '1945',
1155 },
1156 '3' => {
1157 'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
1158 'RFC822.SIZE' => '134314',
1159 }
1160 };
1161 You can specify BODY[HEADER.FIELDS ($fieldlist) as an argument, but you
1163 should keep the following in mind if you do:
1164 1. You can only specify one argument of this type per call. If you
1166 need multiple fields, then you'll have to call fetch_hashref multiple
1167 times, each time specifying a different FETCH attribute but the same.
1168 2. Fetch operations that return RFC822 message headers return the
1170 whole header line, including the field name and the colon. For example,
1171 if you do a "$imap->fetch_hash("BODY[HEADER.FIELDS (Subject)]")", you
1172 will get back subject lines that start with "Subject: ".
1173 By itself this method may be useful for, say, speeding up programs that
1175 want the size of every message in a folder. It issues one command and
1176 receives one (possibly long!) response from the server. However, it's
1177 true power lies in the as-yet-unwritten methods that will rely on this
1178 method to deliver even more powerful result hashes (and which may even
1179 remove the restrictions mentioned in 1 and 2, above). Look for more new
1180 function in later releases.
1181 This method is new with version 2.2.3 and is thus still experimental.
1183 If you decide to try this method and run into problems, please see the
1184 section on "REPORTING BUGS".
1185 flags
1187 Example:
1189 my @flags = $imap->flags($msgid)
1191 or die "Could not flags: $@\n";
1192 The flags method implements the FETCH IMAP client command to list a
1194 single message's flags. It accepts one argument, a message sequence
1195 number (or a message UID, if the Uid parameter is true), and returns an
1196 array (or a reference to an array, if called in scalar context) listing
1197 the flags that have been set. Flag names are provided with leading
1198 backslashes.
1199 As of version 1.11, you can supply either a list of message id's or a
1201 reference to an array of of message id's (which means either sequence
1202 number, if the Uid parameter is false, or message UID's, if the Uid
1203 parameter is true) instead of supplying a single message sequence num‐
1204 ber or UID. If you do, then the return value will not be an array or
1205 array reference; instead, it will be a hash reference, with each key
1206 being a message sequence number (or UID) and each value being a refer‐
1207 ence to an array of flags set for that message.
1208 For example, if you want to display the flags for every message in the
1210 folder where you store e-mail related to your plans for world domina‐
1211 tion, you could do something like this:
1212 use Mail::IMAPClient;
1214 my $imap = Mail::IMAPClient->new( Server => $imaphost,
1215 User => $login,
1216 Password=> $pass,
1217 Uid => 1, # optional
1218 );
1219 $imap->select("World Domination");
1221 # get the flags for every message in my 'World Domination' folder
1222 $flaghash = $imap->flags( scalar($imap->search("ALL"))) ;
1223 # pump through sorted hash keys to print results:
1225 for my $k (sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash) {
1226 # print: Message 1: \Flag1, \Flag2, \Flag3
1227 print "Message $k:\t",join(", ",@{$flaghash->{$k}}),"\n";
1228 }
1229 folders
1231 Example:
1233 $imap->folders or die "Could not list folders: $@\n";
1235 The folders method returns an array listing the available folders. It
1237 will only be successful if the object is in the Authenticated or
1238 Selected states.
1239 The folders argument accepts one optional argument, which is a prefix.
1241 If a prefix is supplied to the folders method, then only folders begin‐
1242 ning with the prefix will be returned.
1243 For example:
1245 print join(", ",$imap->folders),".\n";
1247 # Prints:
1248 # INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1249 print join(", ",$imap->folders("Projects"),".\n";
1250 # Prints:
1251 # Projects, Projects/Completed, Projects/Ongoing, Projects Software.
1252 print join(", ",$imap->folders("Projects" . $imap->separator),".\n";
1253 # Prints:
1254 # Projects/Completed, Projects/Ongoing
1255 Notice that if you just want to list a folder's subfolders (and not the
1257 folder itself), then you need to include the hierarchy separator char‐
1258 acter (as returned by the separator method).
1259 has_capability
1261 Example:
1263 my $has_feature = $imap->has_capability($feature)
1265 or die "Could not do has_capability($feature): $@\n";
1266 Returns true if the IMAP server to which the IMAPClient object is con‐
1268 nected has the capability specified as an argument to has_capability.
1269 idle
1271 Example:
1273 my $idle = $imap->idle or warn "Couldn't idle: $@\n";
1275 &goDoOtherThings;
1276 $imap->done($idle) or warn "Error from done: $@\n";
1277 The idle method places the IMAP connection in an IDLE state. Your
1279 server must support the IMAP IDLE extension to use this method. (See
1280 RFC2177 for a discussion of the IDLE IMAP extension.) The idle method
1281 accepts no arguments and returns a transaction number. This transaction
1282 number must be supplied as the argument for done when the done method
1283 is later called.
1284 Use the done method to tell the IMAP server that the connection is fin‐
1286 ished idling.
1287 If you attempt to use the idle method against a server that does not
1289 have the IDLE capability then the idle method will return "undef". If
1290 you then attempt to use the idle method a second time the idle method
1291 will return "undef" again.
1292 If you successfully run the idle method, then you must use the done
1294 method to stop idling (or to continue, in the parlance of RFC2177).
1295 Failure to do so will only encourage your server to call you BAD and to
1296 rant about a Bogus IDLE continuation.
1297 If you try to run any other mailbox method after calling idle but
1299 before calling done, then that method will not only fail but also take
1300 you out of the IDLE state. This means that when you eventually remember
1301 to call done you will just get an * BAD Invalid tag message.
1302 imap4rev1
1304 Example:
1306 $imap->imap4rev1 or die "Could not imap4rev1: $@\n";
1308 Returns true if the IMAP server to which the IMAPClient object is con‐
1310 nected has the IMAP4REV1 capability.
1311 internaldate
1313 Example:
1315 my $msg_internal_date = $imap->internaldate($msgid)
1317 or die "Could not internaldate: $@\n";
1318 internaldate accepts one argument, a message id (or UID if the Uid
1320 parameter is true), and returns that message's internal date.
1321 get_bodystructure
1323 Example:
1325 my $bodyStructObject = $imap->get_bodystructure($msgid)
1327 or die "Could not get_bodystructure: $@\n";
1328 The get_bodystructure method accepts one argument, a message sequence
1330 number or, if Uid is true, a message UID. It obtains the message's body
1331 structure and returns a parsed Mail::IMAPClient::BodyStructure object
1332 for the message.
1333 get_envelope
1335 Example:
1337 my $envObject = $imap->get_envelope(@args)
1339 or die "Could not get_envelope: $@\n";
1340 The get_envelope method accepts one argument, a message sequence number
1342 or, if Uid is true, a message UID. It obtains the message's envelope
1343 and returns a Mail::IMAPClient::BodyStructure::Envelope object for the
1344 envelope, which is just a version of the envelope that's been parsed
1345 into a perl object.
1346 For more information on how to use this object once you've gotten it,
1348 see the Mail::IMAPClient::BodyStructure documention. (As of this writ‐
1349 ing there is no separate pod document for Mail::IMAPClient::BodyStruc‐
1350 ture::Envelope.)
1351 getacl
1353 Example:
1355 my $hash = $imap->getacl($folder)
1357 or die "Could not getacl for $folder: $@\n";
1358 getacl accepts one argument, the name of a folder. If no argument is
1360 provided then the currently selected folder is used as the default. It
1361 returns a reference to a hash. The keys of the hash are userids that
1362 have access to the folder, and the value of each element are the per‐
1363 missions for that user. The permissions are listed in a string in the
1364 order returned from the server with no whitespace or punctuation
1365 between them.
1366 get_header
1368 Example:
1370 my $messageId = $imap->get_header($msg, "Message-Id") ;
1372 The get_header method accepts two arguments, a message sequence number
1374 or UID and the name of an RFC822 header (without the trailing colon).
1375 It returns the value for that header in the message whose sequence num‐
1376 ber or UID was passed as the first argument. If no value can be found
1377 it returns "undef"; if multiple values are found it returns the first
1378 one. Its return value is always a scalar. get_header uses case insensi‐
1379 tive matching to get the value, so you do not have to worry about the
1380 case of your second argument.
1381 The get_header method is a short-cut for:
1383 my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
1385 is_parent
1387 Example:
1389 my $hasKids = $imap->is_parent($folder) ;
1391 The is_parent method accepts one argument, the name of a folder. It
1393 returns a value that indicates whether or not the folder has children.
1394 The value it returns is either 1) a true value (indicating that the
1395 folder has children), 2) 0 if the folder has no children at this time,
1396 or 3) "undef" if the folder is not permitted to have children.
1397 Eg:
1399 my $parenthood = $imap->is_parent($folder);
1401 if (defined($parenthood)) {
1402 if ($parenthood) {
1403 print "$folder has children.\n" ;
1404 } else {
1405 print "$folder is permitted children, but has none.\n";
1406 }
1407 } else {
1408 print "$folder is not permitted to have children.\n";
1409 }
1410 list
1412 Example:
1414 my @raw_output = $imap->list(@args)
1416 or die "Could not list: $@\n";
1417 The list method implements the IMAP LIST client command. Arguments are
1419 passed to the IMAP server as received, separated from each other by
1420 spaces. If no arguments are supplied then the default list command "tag
1421 LIST "" '*'" is issued.
1422 The list method returns an array (or an array reference, if called in a
1424 scalar context). The array is the unadulterated output of the LIST com‐
1425 mand. (If you want your output adulterated then see the folders method,
1426 above.)
1427 listrights
1429 Example:
1431 $imap->listrights($folder,$user)
1433 or die "Could not listrights: $@\n";
1434 The listrights method implements the IMAP LISTRIGHTS client command
1436 (RFC2086). It accepts two arguments, the foldername and a user id. It
1437 returns the rights the specified user has for the specified folder. If
1438 called in a scalar context then the rights are returned a strings, with
1439 no punction or whitespace or any nonsense like that. If called in array
1440 context then listrights returns an array in which each element is one
1441 right.
1442 login
1444 Example:
1446 $imap->login or die "Could not login: $@\n";
1448 The login method uses the IMAP LOGIN client command (as defined in
1450 RFC2060) to log into the server. The User and Password parameters must
1451 be set before the login method can be invoked. If successful, the login
1452 method returns a pointer to the IMAPClient object and sets the object
1453 status to Authenticated. If unsuccessful, it returns undef. See the new
1454 method for more information on how login can be called automatically
1455 from new.
1456 login is sometimes called automatically by connect, which in turn is
1458 sometimes called automatically by new. You can predict this behavior
1459 once you've read the section on the new method.
1460 logout
1462 Example:
1464 $imap->logout or die "Could not logout: $@\n";
1466 The logout method issues the LOGOUT IMAP client commmand. Since the
1468 LOGOUT IMAP client command causes the server to end the connection,
1469 this also results in the IMAPClient client entering the Unconnected
1470 state. This method does not, however, destroy the IMAPClient object, so
1471 a program can re-invoke the connect and login methods if it wishes to
1472 reestablish a session later in the program.
1473 According to the standard, a well-behaved client should log out before
1475 closing the socket connection. Therefore, Mail::IMAPClient will attempt
1476 to log out of the server during DESTROY processing if the object being
1477 destroyed is in the Connected state.
1478 lsub
1480 Example:
1482 $imap->lsub(@args) or die "Could not lsub: $@\n";
1484 The lsub method implements the IMAP LSUB client command. Arguments are
1486 passed to the IMAP server as received, separated from each other by
1487 spaces. If no arguments are supplied then the default lsub command "tag
1488 LSUB "" '*'" is issued.
1489 The lsub method returns an array (or an array reference, if called in a
1491 scalar context). The array is the unaltered output of the LSUB command.
1492 If you want an array of subscribed folders then see the subscribed
1493 method, below.
1494 mark
1496 Example:
1498 $imap->mark(@msgs) or die "Could not mark: $@\n";
1500 The mark method accepts a list of one or more messages sequence num‐
1502 bers, or a single reference to an array of one or more message sequence
1503 numbers, as its argument(s). It then sets the "\Flagged" flag for those
1504 message(s). Of course, if the Uid parameter is set to a true value then
1505 those message sequence numbers had better be unique message id's.
1506 Note that specifying "$imap->see(@msgs)" is just a shortcut for speci‐
1508 fying "$imap->set_flag("Flagged",@msgs)".
1509 Massage
1511 Example:
1513 $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
1515 The Massage method accepts a value as an argument and, optionally, a
1517 second value that, when true, indicates that the first argument is not
1518 the name of an existing folder.
1519 It returns its argument as a correctly quoted string or a literal
1521 string.
1522 Note that you should rarely use this on folder names, since methods
1524 that accept folder names as an argument will call Massage for you. In
1525 fact, it was originally developed as an undocumented helper method
1526 meant for internal Mail::IMAPClient methods only.
1527 You may also want to see the Quote method, which is related to this
1529 method.
1530 message_count
1532 Example:
1534 my $msgcount = $imap->message_count($folder);
1536 defined($msgcount) or die "Could not message_count: $@\n";
1537 The message_count method accepts the name of a folder as an argument
1539 and returns the number of messages in that folder. Internally, it
1540 invokes the status method (see above) and parses out the results to
1541 obtain the number of messages. If you don't supply an argument to mes‐
1542 sage_count then it will return the number of messages in the currently
1543 selected folder (assuming of course that you've used the select or
1544 examine method to select it instead of trying something funky). Note
1545 that RFC2683 contains warnings about the use of the IMAP STATUS command
1546 (and thus the status method and therefore the message_count method)
1547 against the currenlty selected folder. You should carefully consider
1548 this before using message_count on the currently selected folder. You
1549 may be better off using search or one of its variants (especially mes‐
1550 sages), and then counting the results. On the other hand, I regularly
1551 violate this rule on my server without suffering any dire consequences.
1552 Your milage may vary.
1553 message_string
1555 Example:
1557 my $string = $imap->message_string($msgid)
1559 or die "Could not message_string: $@\n";
1560 The message_string method accepts a message sequence number (or message
1562 UID if Uid is true) as an argument and returns the message as a string.
1563 The returned value contains the entire message in one scalar variable,
1564 including the message headers. Note that using this method will set the
1565 message's "\Seen" flag as a side effect, unless Peek is set to a true
1566 value.
1567 message_to_file
1569 Example:
1571 $imap->message_to_file($file,@msgs)
1573 or die "Could not message_to_file: $@\n";
1574 The message_to_file method accepts a filename or file handle and one or
1576 more message sequence numbers (or message UIDs if Uid is true) as argu‐
1577 ments and places the message string(s) (including RFC822 headers) into
1578 the file named in the first argument (or prints them to the filehandle,
1579 if a filehandle is passed). The returned value is true on succes and
1580 "undef" on failure.
1581 If the first argument is a reference, it is assumed to be an open file‐
1583 handle and will not be closed when the method completes, If it is a
1584 file, it is opened in append mode, written to, then closed.
1585 Note that using this method will set the message's "\Seen" flag as a
1587 side effect. But you can use the deny_seeing method to set it back, or
1588 set the Peek parameter to a true value to prevent setting the "\Seen"
1589 flag at all.
1590 This method currently works by making some basic assumptions about the
1592 server's behavior, notably that the message text will be returned as a
1593 literal string but that nothing else will be. If you have a better idea
1594 then I'd like to hear it.
1595 message_uid
1597 Example:
1599 my $msg_uid = $imap->message_uid($msg_seq_no)
1601 or die "Could not get uid for $msg_seq_no: $@\n";
1602 The message_uid method accepts a message sequence number (or message
1604 UID if Uid is true) as an argument and returns the message's UID. Yes,
1605 if Uid is true then it will use the IMAP UID FETCH UID client command
1606 to obtain and return the very same argument you supplied. This is an
1607 IMAP feature so don't complain to me about it.
1608 messages
1610 Example:
1612 # Get a list of messages in the current folder:
1614 my @msgs = $imap->messages or die "Could not messages: $@\n";
1615 # Get a reference to an array of messages in the current folder:
1616 my $msgs = $imap->messages or die "Could not messages: $@\n";
1617 If called in list context, the messages method returns a list of all
1619 the messages in the currenlty selected folder. If called in scalar con‐
1620 text, it returns a reference to an array containing all the messages in
1621 the folder. If you have the Uid parameter turned off, then this is the
1622 same as specifying "1 ... $imap->message_count"; if you have UID set to
1623 true then this is the same as specifying "$imap->search("ALL")".
1624 migrate
1626 Example:
1628 $imap->migrate($imap_2, "ALL", $targetFolder )
1630 or die "Could not migrate: $@\n";
1631 The migrate method copies the indicated messages from the currently
1633 selected folder to another Mail::IMAPClient object's session. It
1634 requires these arguments:
1635 1. a reference to the target Mail::IMAPClient object (not the calling
1637 object, which is connected to the source account);
1638 2. the message(s) to be copied, specified as either a) the message
1640 sequence number (or message UID if the UID parameter is true) of a
1641 single message, b) a reference to an array of message sequence num‐
1642 bers (or message UID's if the UID parameter is true) or c) the spe‐
1643 cial string "ALL", which is a shortcut for the results of
1644 "search("ALL")".
1645 3. the folder name of a folder on the target mailbox to receive the
1647 message(s). If this argument is not supplied or if undef is sup‐
1648 plied then a folder with the same name as the currently selected
1649 folder on the calling object will be created if necessary and used.
1650 If you specify something other then undef for this argument, even
1651 if it's '$imap1->Folder' or the name of the currently selected
1652 folder, then that folder will only be used if it exists on the tar‐
1653 get object's mailbox; if it does not exist then migrate will fail.
1654 The target Mail::IMAPClient object should not be the same as the
1656 source. The source object is the calling object, i.e. the one whose
1657 migrate method will be used. It cannot be the same object as the one
1658 specified as the target, even if you are for some reason migrating
1659 between folders on the same account (which would be silly anyway, since
1660 copy can do that much more efficiently). If you try to use the same
1661 Mail::IMAPClient object for both the caller and the reciever then
1662 they'll both get all screwed up and it will be your fault because I
1663 just warned you and you didn't listen.
1664 migrate will download messages from the source in chunks to minimize
1666 memory usage. The size of the chunks can be controlled by changing the
1667 source Mail::IMAPClient object's the Buffer parameter. The higher the
1668 Buffer value, the faster the migration, but the more memory your pro‐
1669 gram will require. TANSTAAFL. (See the Buffer parameter and eponymous
1670 accessor method, described above under the "Parameters" section.)
1671 The migrate method uses Black Magic to hardwire the I/O between the two
1673 Mail::IMAPClient objects in order to minimize resource consumption. If
1674 you have older scripts that used message_to_file and append_file to
1675 move large messages between IMAP mailboxes then you may want to try
1676 this method as a possible replacement.
1677 move
1679 Example:
1681 my $newUid = $imap->move($newFolder, $oldUid)
1683 or die "Could not move: $@\n";
1684 $imap->expunge;
1685 The move method moves messages from the currently selected folder to
1687 the folder specified in the first argument to move. If the Uid parame‐
1688 ter is not true, then the rest of the arguments should be either:
1689 > a message sequence number,
1691 > a comma-separated list of message sequence numbers, or
1693 > a reference to an array of message sequence numbers.
1695 If the Uid parameter is true, then the arguments should be:
1697 > a message UID,
1699 > a comma-separated list of message UID's, or
1701 > a reference to an array of message UID's.
1703 If the target folder does not exist then it will be created.
1705 If move is sucessful, then it returns a true value. Furthermore, if the
1707 Mail::IMAPClient object is connected to a server that has the UIDPLUS
1708 capability, then the true value will be the comma-separated list of
1709 UID's for the newly copied messages. The list will be in the order in
1710 which the messages were moved. (Since move uses the copy method, the
1711 messages will be moved in numerical order.)
1712 If the move is not successful then move returns "undef".
1714 Note that a move really just involves copying the message to the new
1716 folder and then setting the \Deleted flag. To actually delete the orig‐
1717 inal message you will need to run expunge (or close).
1718 namespace
1720 Example:
1722 my @refs = $imap->namespace
1724 or die "Could not namespace: $@\n";
1725 The namespace method runs the NAMESPACE IMAP command (as defined in RFC
1727 2342). When called in a list context, it returns a list of three refer‐
1728 ences. Each reference looks like this:
1729 [ [ $prefix_1, $separator_1 ] ,
1731 [ $prefix_2, $separator_2 ],
1732 [ $prefix_n , $separator_n]
1733 ]
1734 The first reference provides a list of prefices and separator charac‐
1736 tors for the available personal namespaces. The second reference pro‐
1737 vides a list of prefices and separator charactors for the available
1738 shared namespaces. The third reference provides a list of prefices and
1739 separator charactors for the available public namespaces.
1740 If any of the three namespaces are unavailable on the current server
1742 then an 'undef' is returned instead of a reference. So for example if
1743 shared folders were not supported on the server but personal and public
1744 namespaces were both available (with one namespace each), the returned
1745 value might resemble this:
1746 ( [ "", "/" ] , undef, [ "#news", "." ] ) ;
1748 If the namespace method is called in scalar context, it returns a ref‐
1750 erence to the above-mentioned list of three references, thus creating a
1751 single structure that would pretty-print something like this:
1752 $VAR1 = [
1754 [
1755 [ $user_prefix_1, $user_separator_1 ] ,
1756 [ $user_prefix_2, $user_separator_2],
1757 [ $user_prefix_n , $user_separator_n]
1758 ] , # or undef
1759 [
1760 [ $shared_prefix_1, $shared_separator_1 ] ,
1761 [ $shared_prefix_2, $shared_separator_2],
1762 [ $shared_prefix_n , $shared_separator_n]
1763 ] , # or undef
1764 [
1765 [ $public_prefix_1, $public_separator_1 ] ,
1766 [ $public_prefix_2, $public_separator_2],
1767 [ $public_prefix_n , $public_separator_n]
1768 ] , # or undef
1769 ];
1770 Or, to look at our previous example (where shared folders are unsup‐
1772 ported) called in scalar context:
1773 $VAR1 = [
1775 [
1776 [
1777 "" ,
1778 "/",
1779 ],
1780 ],
1781 undef,
1783 [
1785 [
1786 "#news",
1787 "."
1788 ],
1789 ],
1790 ];
1791 on
1793 Example:
1795 my @msgs = $imap->on($Rfc2060_date)
1797 or warn "Could not find messages sent on $Rfc2060_date: $@\n";
1798 The on method works just like the since method, below, except it
1800 returns a list of messages whose internal system dates are the same as
1801 the date supplied as the argument.
1802 parse_headers
1804 Example:
1806 my $hashref = $imap->parse_headers($msg⎪⎪@msgs, "Date", "Subject")
1808 or die "Could not parse_headers: $@\n";
1809 The parse_headers method accepts as arguments a message sequence number
1811 and a list of header fields. It returns a hash reference in which the
1812 keys are the header field names (without the colon) and the values are
1813 references to arrays of values. A picture would look something like
1814 this:
1815 $hashref = $imap->parse_headers(1,"Date","Received","Subject","To");
1817 $hashref = {
1818 "Date" => [ "Thu, 09 Sep 1999 09:49:04 -0400" ] ,
1819 "Received" => [ q/
1820 from mailhub ([111.11.111.111]) by mailhost.bigco.com
1821 (Netscape Messaging Server 3.6) with ESMTP id AAA527D for
1822 <bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
1823 /, q/
1824 from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
1825 id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
1826 (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
1827 /, q/
1828 from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
1829 with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
1830 18 Jun 1999 16:29:05 +0000 (GMT)
1831 /] ,
1832 "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
1833 "To" => [ "Big Shot <big.shot@bigco.com> ] ,
1834 } ;
1835 The text in the example for the "Received" array has been formated to
1837 make reading the example easier. The actual values returned are just
1838 strings of words separated by spaces and with newlines and carriage
1839 returns stripped off. The Received header is probably the main reason
1840 that the parse_headers method creates a hash of lists rather than a
1841 hash of values.
1842 If the second argument to parse_headers is 'ALL' or if it is unspeci‐
1844 fied then all available headers are included in the returned hash of
1845 lists.
1846 If you're not emotionally prepared to deal with a hash of lists then
1848 you can always call the fetch method yourself with the appropriate
1849 parameters and parse the data out any way you want to. Also, in the
1850 case of headers whose contents are also reflected in the envelope, you
1851 can use the get_envelope method as an alternative to parse_headers.
1852 If the Uid parameter is true then the first argument will be treated as
1854 a message UID. If the first argument is a reference to an array of mes‐
1855 sage sequence numbers (or UID's if Uid is true), then parse_headers
1856 will be run against each message in the array. In this case the return
1857 value is a hash, in which the key is the message sequence number (or
1858 UID) and the value is a reference to a hash as described above.
1859 An example of using parse_headers to print the date and subject of
1861 every message in your smut folder could look like this:
1862 use Mail::IMAPClient;
1864 my $imap = Mail::IMAPClient->new( Server => $imaphost,
1865 User => $login,
1866 Password=> $pass,
1867 Uid => 1, # optional
1868 );
1869 $imap->select("smut");
1871 for my $h (
1873 # grab the Subject and Date from every message in my (fictional!) smut folder;
1875 # the first argument is a reference to an array listing all messages in the folder
1876 # (which is what gets returned by the $imap->search("ALL") method when called in
1877 # scalar context) and the remaining arguments are the fields to parse out
1878 # The key is the message number, which in this case we don't care about:
1880 values %{$imap->parse_headers( scalar($imap->search("ALL")) , "Subject", "Date")}
1881 ) {
1882 # $h is the value of each element in the hash ref returned from parse_headers,
1883 # and $h is also a reference to a hash.
1884 # We'll only print the first occurance of each field because we don't expect more
1885 # than one Date: or Subject: line per message.
1886 print map { "$_:\t$h->{$_}[0]\n"} keys %$h ;
1887 }
1888 recent
1890 Example:
1892 my @recent = $imap->recent or warn "No recent msgs: $@\n";
1894 The recent method performs an IMAP SEARCH RECENT search against the
1896 selected folder and returns an array of sequence numbers (or UID's, if
1897 the Uid parameter is true) of messages that are recent.
1898 recent_count
1900 Example:
1902 my $count = 0;
1904 defined($count = $imap->recent_count($folder))
1905 or die "Could not recent_count: $@\n";
1906 The recent_count method accepts as an argument a folder name. It
1908 returns the number of recent messages in the folder (as returned by the
1909 IMAP client command "STATUS folder RECENT"), or "undef" in the case of
1910 an error. The recent_count method was contributed by Rob Deker
1911 (deker@ikimbo.com).
1912 rename
1914 Example:
1916 $imap->rename($oldname,$nedwname)
1918 or die "Could not rename: $@\n";
1919 The rename method accepts two arguments: the name of an existing
1921 folder, and a new name for the folder. The existing folder will be
1922 renamed to the new name using the RENAME IMAP client command. rename
1923 will return a true value if successful, or "undef" if unsuccessful.
1924 restore_message
1926 Example:
1928 $imap->restore_message(@msgs) or die "Could not restore_message: $@\n";
1930 The restore_message method is used to undo a previous delete_message
1932 operation (but not if there has been an intervening expunge or close).
1933 The IMAPClient object must be in Selected status to use the
1934 restore_message method.
1935 The restore_message method accepts a list of arguments. If the Uid
1937 parameter is not set to a true value, then each item in the list should
1938 be either:
1939 > a message sequence number,
1941 > a comma-separated list of message sequence numbers,
1943 > a reference to an array of message sequence numbers, or
1945 If the Uid parameter is set to a true value, then each item in the list
1947 should be either:
1948 > a message UID,
1950 > a comma-separated list of UID's, or
1952 > a reference to an array of message UID's.
1954 The messages identified by the sequence numbers or UID's will have
1956 their \Deleted flags cleared, effectively "undeleting" the messages.
1957 restore_message returns the number of messages it was able to restore.
1958 Note that restore_messages is similar to calling
1960 "unset_flag("\Deleted",@msgs)", except that restore_messages returns a
1961 (slightly) more meaningful value. Also it's easier to type.
1962 run
1964 Example:
1966 $imap->run(@args) or die "Could not run: $@\n";
1968 Like Perl itself, the Mail::IMAPClient module is designed to make com‐
1970 mon things easy and uncommon things possible. The run method is pro‐
1971 vided to make those uncommon things possible.
1972 The run method excepts one or two arguments. The first argument is a
1974 string containing an IMAP Client command, including a tag and all
1975 required arguments. The optional second argument is a string to look
1976 for that will indicate success. (The default is "/OK.*/"). The run
1977 method returns an array of output lines from the command, which you are
1978 free to parse as you see fit.
1979 The run method does not do any syntax checking, other than rudimentary
1981 checking for a tag.
1982 When run processes the command, it increments the transaction count and
1984 saves the command and responses in the History buffer in the same way
1985 other commands do. However, it also creates a special entry in the His‐
1986 tory buffer named after the tag supplied in the string passed as the
1987 first argument. If you supply a numeric value as the tag then you may
1988 risk overwriting a previous transaction's entry in the History buffer.
1989 If you want the control of run but you don't want to worry about the
1991 damn tags then see "tag_and_run", below.
1992 search
1994 Example:
1996 my @msgs = $imap->search(@args) or warn "search: None found\n";
1998 if ($@) {
1999 warn "Error in search: $@\n";
2000 }
2001 The search method implements the SEARCH IMAP client command. Any argu‐
2003 ment supplied to search is prefixed with a space and appended to the
2004 SEARCH IMAP client command. This method is another one of those situa‐
2005 tions where it will really help to have your copy of RFC2060 handy,
2006 since the SEARCH IMAP client command contains a plethora of options and
2007 possible arguments. I'm not going to repeat them here.
2008 Remember that if your argument needs quotes around it then you must
2010 make sure that the quotes will be preserved when passing the argument.
2011 I.e. use "qq/"$arg"/" instead of "$arg". When in doubt, use the Quote
2012 method.
2013 The search method returns an array containing sequence numbers of mes‐
2015 sages that passed the SEARCH IMAP client command's search criteria. If
2016 the Uid parameter is true then the array will contain message UID's. If
2017 search is called in scalar context then a pointer to the array will be
2018 passed, instead of the array itself. If no messages meet the criteria
2019 then search returns an empty list (when in list context) or "undef" (in
2020 scalar context).
2021 Since a valid, successful search can legitimately return zero matches,
2023 you may wish to distinguish between a search that correctly returns
2024 zero hits and a search that has failed for some other reason (i.e.
2025 invalid search parameters). Therefore, the $@ variable will always be
2026 cleared before the SEARCH command is issued to the server, and will
2027 thus remain empty unless the server gives a BAD or NO response to the
2028 SEARCH command.
2029 see
2031 Example:
2033 $imap->see(@msgs) or die "Could not see: $@\n";
2035 The see method accepts a list of one or more messages sequence numbers,
2037 or a single reference to an array of one or more message sequence num‐
2038 bers, as its argument(s). It then sets the \Seen flag for those mes‐
2039 sage(s). Of course, if the Uid parameter is set to a true value then
2040 those message sequence numbers had better be unique message id's, but
2041 then you already knew that, didn't you?
2042 Note that specifying "$imap->see(@msgs)" is just a shortcut for speci‐
2044 fying "$imap->set_flag("Seen",@msgs)".
2045 seen
2047 Example:
2049 my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
2051 The seen method performs an IMAP SEARCH SEEN search against the
2053 selected folder and returns an array of sequence numbers of messages
2054 that have already been seen (ie their \Seen flag is set). If the Uid
2055 parameter is true then an array of message UID's will be returned
2056 instead. If called in scalar context than a reference to the array
2057 (rather than the array itself) will be returned.
2058 select
2060 Example:
2062 $imap->select($folder) or die "Could not select: $@\n";
2064 The select method selects a folder and changes the object's state to
2066 Selected. It accepts one argument, which is the name of the folder to
2067 select.
2068 selectable
2070 Example:
2072 foreach my $f ( grep($imap->selectable($_),$imap->folders ) ) {
2074 $imap->select($f) ;
2075 }
2076 The selectable method accepts one value, a folder name, and returns
2078 true if the folder is selectable or false if it is not selectable.
2079 sentbefore
2081 Example:
2083 my @msgs = $imap->sentbefore($Rfc2060_date)
2085 or warn "Could not find any msgs sent before $Rfc2060_date: $@\n";
2086 The sentbefore method works just like "sentsince", below, except it
2088 searches for messages that were sent before the date supplied as an
2089 argument to the method.
2090 senton
2092 Example:
2094 my @msgs = $imap->senton($Rfc2060_date)
2096 or warn "Could not find any messages sent on $Rfc2060_date: $@\n";
2097 The senton method works just like "sentsince", below, except it
2099 searches for messages that were sent on the exact date supplied as an
2100 argument to the method.
2101 sentsince
2103 Example:
2105 my @msgs = $imap->sentsince($Rfc2060_date)
2107 or warn "Could not find any messages sent since $Rfc2060_date: $@\n";
2108 The sentsince method accepts one argument, a date in either epoch time
2110 format (seconds since 1/1/1970, or as output by time and as accepted by
2111 localtime) or in the date_text format as defined in RFC2060
2112 (dd-Mon-yyyy, where Mon is the English-language three-letter abbrevia‐
2113 tion for the month).
2114 It searches for items in the currently selected folder for messages
2116 sent since the day whose date is provided as the argument. It uses the
2117 RFC822 Date: header to determine the sentsince date. (Actually, it the
2118 server that uses the Date: header; this documentation just assumes that
2119 the date is coming from the Date: header because that's what RFC2060
2120 dictates.)
2121 In the case of arguments supplied as a number of seconds, the returned
2123 result list will include items sent on or after that day, regardless of
2124 whether they arrived before the specified time on that day. The IMAP
2125 protocol does not support searches at a granularity finer than a day,
2126 so neither do I. On the other hand, the only thing I check for in a
2127 date_text argument is that it matches the pattern
2128 "/\d\d-\D\D\D-\d\d\d\d/" (notice the lack of anchors), so if your
2129 server lets you add something extra to a date_text string then so will
2130 Mail::IMAPClient.
2131 If you'd like, you can use the Rfc2060_date method to convert from
2133 epoch time (as returned by time) into an RFC2060 date specification.
2134 separator
2136 Example:
2138 my $sepChar = $imap->separator(@args)
2140 or die "Could not get separator: $@\n";
2141 The separator method returns the character used as a separator charac‐
2143 ter in folder hierarchies. On unix-based servers, this is often but not
2144 necessarily a forward slash (/). It accepts one argument, the name of a
2145 folder whose hierarchy's separator should be returned. If no folder
2146 name is supplied then the separator for the INBOX is returned, which
2147 probably is good enough.
2148 If you want your programs to be portable from IMAP server brand X to
2150 IMAP server brand Y, then you should never use hard-coded separator
2151 characters to specify subfolders. (In fact, it's even more complicated
2152 than that, since some server don't allow any subfolders at all, some
2153 only allow subfolders under the "INBOX" folder, and some forbid sub‐
2154 folders in the inbox but allow them "next" to the inbox. Furthermore,
2155 some server implementations do not allow folders to contain both sub‐
2156 folders and mail messages; other servers allow this.)
2157 set_flag
2159 Example:
2161 $imap->set_flag("Seen",@msgs)
2163 or die "Could not set flag: $@\n";
2164 The set_flag method accepts the name of a flag as its first argument
2166 and a list of one or more messages sequence numbers, or a single refer‐
2167 ence to an array of one or more message sequence numbers, as its next
2168 argument(s). It then sets the flag specified for those message(s). Of
2169 course, if the Uid parameter is set to a true value then those message
2170 sequence numbers had better be unique message id's, just as you'd
2171 expect.
2172 Note that when specifying the flag in question, the preceding backslash
2174 (\) is entirely optional. (For you, that is. Mail::IMAPClient still has
2175 remember to stick it in there before passing the command to the server
2176 if the flag is one of the reserved flags specified in RFC2060. This is
2177 in fact so important that the method checks its argument and adds the
2178 backslash when necessary, which is why you don't have to worry about it
2179 overly much.)
2180 setacl
2182 Example:
2184 $imap->setacl($folder,$userid,$authstring)
2186 or die "Could not set acl: $@\n";
2187 The setacl method accepts three input arguments, a folder name, a user
2189 id (or authentication identifier, to use the terminology of RFC2086),
2190 and an access rights modification string. See RFC2086 for more informa‐
2191 tion. (This is somewhat experimental and its implementation may
2192 change.)
2193 since
2195 Example:
2197 my @msgs = $imap->since($date)
2199 or warn "Could not find any messages since $date: $@\n";
2200 The since method accepts a date in either epoch format (seconds since
2202 1/1/1970, or as output by "time" in perlfunc and as accepted by "local‐
2203 time" in perlfunc) or in the date_text format as defined in RFC2060
2204 (dd-Mon-yyyy, where Mon is the English-language three-letter abbrevia‐
2205 tion for the month). It searches for items in the currently selected
2206 folder for messages whose internal dates are on or after the day whose
2207 date is provided as the argument. It uses the internal system date for
2208 a message to determine if that message was sent since the given date.
2209 In the case of arguments supplied as a number of seconds, the returned
2211 result list will include items whose internal date is on or after that
2212 day, regardless of whether they arrived before the specified time on
2213 that day.
2214 If since is called in a list context then it will return a list of mes‐
2216 sages meeting the SEARCH SINCE criterion, or an empty list if no mes‐
2217 sages meet the criterion.
2218 If since is called in a scalar context then it will return a reference
2220 to an array of messages meeting the SEARCH SINCE criterion, or "undef"
2221 if no messages meet the criterion.
2222 Since since is a front-end to search, some of the same rules apply.
2224 For example, the $@ variable will always be cleared before the SEARCH
2225 command is issued to the server, and will thus remain empty unless the
2226 server gives a BAD or NO response to the SEARCH command.
2227 size
2229 Example:
2231 my $size = $imap->size($msgId)
2233 or die "Could not find size of message $msgId: $@\n";
2234 The size method accepts one input argument, a sequence number (or mes‐
2236 sage UID if the Uid parameter is true). It returns the size of the mes‐
2237 sage in the currently selected folder with the supplied sequence number
2238 (or UID). The IMAPClient object must be in a Selected state in order to
2239 use this method.
2240 sort
2242 Example:
2244 my @msgs = $imap->sort(@args) ;
2246 if ($@ ) {
2247 warn "Error in sort: $@\n";
2248 }
2249 The sort method is just like the search method, only different. It
2251 implements the SORT extension as described in
2252 <http://search.ietf.org/inter‐
2253 net-drafts/draft-ietf-imapext-sort-10.txt>. It would be wise to use
2254 the has_capability method to verify that the SORT capability is avail‐
2255 able on your server before trying to use the sort method. If you forget
2256 to check and you're connecting to a server that doesn't have the SORT
2257 capability then sort will return undef. LastError will then say you are
2258 "BAD". If your server doesn't support the SORT capability then you'll
2259 have to use search and then sort the results yourself.
2260 The first argument to sort is a space-delimited list of sorting crite‐
2262 ria. The Internet Draft that describes SORT requires that this list be
2263 wrapped in parentheses, even if there is only one sort criterion. If
2264 you forget the parentheses then the sort method will add them. But you
2265 have to forget both of them, or none. This isn't CMS running under VM!
2266 The second argument is a character set to use for sorting. Different
2268 character sets use different sorting orders, so this argument is impor‐
2269 tant. Since all servers must support UTF-8 and US-ASCII if they support
2270 the SORT capability at all, you can use one of those if you don't have
2271 some other preferred character set in mind.
2272 The rest of the arguments are searching criteria, just as you would
2274 supply to the search method. These are all documented in RFC2060. If
2275 you just want all of the messages in the currently selected folder
2276 returned to you in sorted order, use ALL as your only search criterion.
2277 The sort method returns an array containing sequence numbers of mes‐
2279 sages that passed the SORT IMAP client command's search criteria. If
2280 the Uid parameter is true then the array will contain message UID's.
2281 If sort is called in scalar context then a pointer to the array will be
2282 passed, instead of the array itself. The message sequence numbers or
2283 unique identifiers are ordered according to the sort criteria speci‐
2284 fied. The sort criteria are nested in the order specified; that is,
2285 items are sorted first by the first criterion, and within the first
2286 criterion they are sorted by the second criterion, and so on.
2287 The sort method will clear $@ before attempting the SORT operation just
2289 as the search method does.
2290 status
2292 Example:
2294 my @rawdata = $imap->status($folder,qw/(Messages)/)
2296 or die "Error obtaining status: $@\n";
2297 The status method accepts one argument, the name of a folder (or mail‐
2299 box, to use RFC2060's terminology), and returns an array containing the
2300 results of running the IMAP STATUS client command against that folder.
2301 If additional arguments are supplied then they are appended to the IMAP
2302 STATUS client command string, separated from the rest of the string and
2303 each other with spaces.
2304 If status is not called in an array context then it returns a reference
2306 to an array rather than the array itself.
2307 The status method should not be confused with the Status method (with
2309 an uppercase 'S'), which returns information about the IMAPClient
2310 object. (See the section labeled "Status Methods", below).
2311 store
2313 Example:
2315 $imap->store(@args) or die "Could not store: $@\n";
2317 The store method accepts a message sequence number or comma-separated
2319 list of message sequence numbers as a first argument, a message data
2320 item name, and a value for the message data item. Currently, data
2321 items are the word "FLAGS" followed by a space and a list of flags (in
2322 parens). The word "FLAGS" can be modified by prefixing it with either a
2323 "+" or a "-" (to indicate "add these flags" or "remove these flags")
2324 and by suffixing it with ".SILENT" (which reduces the amount of output
2325 from the server; very useful with large message sets). Normally you
2326 won't need to call store because there are oodles of methods that will
2327 invoke store for you with the correct arguments. Furthermore, these
2328 methods are friendlier and more flexible with regards to how you spec‐
2329 ify your arguments. See for example see, deny_seeing, delete_message,
2330 and restore_message. Or mark, unmark, set_flag, and unset_flag.
2331 subject
2333 Example:
2335 my $subject = $imap->subject($msg);
2337 The subject method accepts one argument, a message sequence number (or
2339 a message UID, if the Uid parameter is true). The text in the "Subject"
2340 header of that message is returned (without the "Subject: " prefix).
2341 This method is a short-cut for:
2342 my $subject = $imap->get_header($msg, "Subject");
2344 subscribed
2346 Example:
2348 my @subscribedFolders = $imap->subscribed
2350 or warn "Could not find subscribed folders: $@\n";
2351 The subscribed method works like the folders method, above, except that
2353 the returned list (or array reference, if called in scalar context)
2354 contains only the subscribed folders.
2355 Like folders, you can optionally provide a prefix argument to the sub‐
2357 scribed method.
2358 tag_and_run
2360 Example:
2362 my @output = $imap->tag_and_run(@args)
2364 or die "Could not tag_and_run: $@\n";
2365 The tag_and_run method accepts one or two arguments. The first argument
2367 is a string containing an IMAP Client command, without a tag but with
2368 all required arguments. The optional second argument is a string to
2369 look for that will indicate success (without pattern delimiters). The
2370 default is "OK.*".
2371 The tag_and_run method will prefix your string (from the first argu‐
2373 ment) with the next transaction number and run the command. It returns
2374 an array of output lines from the command, which you are free to parse
2375 as you see fit. Using this method instead of run (above) will free you
2376 from having to worry about handling the tags (and from worrying about
2377 the side affects of naming your own tags).
2378 uidnext
2380 Example:
2382 my $nextUid = $imap->uidnext($folder) or die "Could not uidnext: $@\n";
2384 The uidnext method accepts one argument, the name of a folder, and
2386 returns the numeric string that is the next available message UID for
2387 that folder.
2388 thread
2390 Example:
2392 my $thread = $imap->thread($algorythm, $charset, @search_args ) ;
2394 The thread method accepts zero to three arguments. The first argument
2396 is the threading algorythm to use, generally either ORDEREDSUBJECT or
2397 REFERENCES. The second argument is the character set to use, and the
2398 third argument is the set of search arguments to use.
2399 If the algorythm is not supplied, it defaults to REFERENCES if avail‐
2401 able, or ORDEREDSUBJECT if available. If neither of these is available
2402 then the thread method returns undef.
2403 If the character set is not specified it will default to UTF-8.
2405 If the search arguments are not specified, the default is ALL.
2407 If thread is called for an object connected to a server that does not
2409 support the THREADS extension then the thread method will return
2410 "undef".
2411 The threads method will issue the THREAD command as defined in
2413 <http://www.ietf.org/internet-drafts/draft-ietf-imapext-thread-11.txt>.
2414 It returns an array of threads. Each element in the array is either a
2415 message id or a reference to another array of (sub)threads.
2416 If the Uid parameter is set to a true value then the message id's
2418 returned in the thread structure will be message UID's. Otherwise they
2419 will be message sequence numbers.
2420 uidvalidity
2422 Example:
2424 my $validity = $imap->uidvalidity($folder)
2426 or die "Could not uidvalidity: $@\n";
2427 The uidvalidity method accepts one argument, the name of a folder, and
2429 returns the numeric string that is the unique identifier validity value
2430 for the folder.
2431 unmark
2433 Example:
2435 $imap->unmark(@msgs) or die "Could not unmark: $@\n";
2437 The unmark method accepts a list of one or more messages sequence num‐
2439 bers, or a single reference to an array of one or more message sequence
2440 numbers, as its argument(s). It then unsets the \Flagged flag for those
2441 message(s). Of course, if the Uid parameter is set to a true value then
2442 those message sequence numbers should really be unique message id's.
2443 Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
2445 specifying "$imap->unset_flag("Flagged",@msgs)".
2446 Note also that the \Flagged flag is just one of many possible flags.
2448 This is a little confusing, but you'll have to get used to the idea
2449 that among the reserved flags specified in RFC2060 is one name
2450 \Flagged. There is no specific meaning for this flag; it means whatever
2451 the mailbox owner (or delegate) wants it to mean when it is turned on.
2452 unseen
2454 Example:
2456 my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
2458 The unseen method performs an IMAP SEARCH UNSEEN search against the
2460 selected folder and returns an array of sequence numbers of messages
2461 that have not yet been seen (ie their \Seen flag is not set). If the
2462 Uid parameter is true then an array of message UID's will be returned
2463 instead. If called in scalar context than a pointer to the array
2464 (rather than the array itself) will be returned.
2465 Note that when specifying the flag in question, the preceding backslash
2467 (\) is entirely optional.
2468 unseen_count
2470 Example:
2472 foreach my $f ($imap->folders) {
2474 print "The $f folder has ",
2475 $imap->unseen_count($f)⎪⎪0,
2476 " unseen messages.\n";
2477 }
2478 The unseen_count method accepts the name of a folder as an argument and
2480 returns the number of unseen messages in that folder. If no folder
2481 argument is provided then it returns the number of unseen messages in
2482 the currently selected Folder.
2483 unset_flag
2485 Example:
2487 $imap->unset_flag("\Seen",@msgs)
2489 or die "Could not unset_flag: $@\n";
2490 The unset_flag method accepts the name of a flag as its first argument
2492 and a list of one or more messages sequence numbers, or a single refer‐
2493 ence to an array of one or more message sequence numbers, as its next
2494 argument(s). It then unsets the flag specified for those message(s). Of
2495 course, if the Uid parameter is set to a true value then those message
2496 sequence numbers had better be unique message id's, just as you'd
2497 expect.
2498
2500 IMAP Client Commands not otherwise documented have been implemented via
2501 an AUTOLOAD hack and use a default method.
2502 If a program calls a method that is not defined (or inherited) by the
2504 IMAPClient module then the IMAPClient module will assume that it is an
2505 IMAP client command. It will prefix the command with the next available
2506 transaction number (or tag value), and append to it the space-delimited
2507 list of arguments supplied to the unimplemented method (if any). It
2508 will then read lines of output from the imap session until it finds a
2509 line containing the strings "OK" and "Completed", and return an array
2510 containing all of the lines of output (or, if called in scalar context,
2511 an array reference). If it finds "BAD" or "NO" instead of "OK" it
2512 returns "undef".
2513 Eg:
2515 my @results = $imap->FOO("bar","an example","of the default");
2517 results in:
2519 99 FOO bar an example of the default\r\n
2521 being sent to the IMAP server (assuming that 99 is the current transac‐
2523 tion number).
2524 Notice that we used an uppercase method name "FOO" so as not to con‐
2526 flict with future implementations of that IMAP command. If you run your
2527 script with warnings turned on (always a good idea, at least during
2528 testing), then you will receive warnings whenever you use a lowercase
2529 method name that has not been implemented. An exception to this is when
2530 you use certain common (yet unimplemented) methods that, if ever
2531 explicitly implemented, are guaranteed to behave just like the default
2532 method. To date, those methods are either documented in the section
2533 labeled "OBJECT METHODS", above, or listed here:
2534 Mail::IMAPClient's default method adds enormous flexibility and built-
2536 in extensibility but it is not psychic. It can handle almost any exten‐
2537 sion and truthfully tell you if the server successfully performed your
2538 request. But it cannot predict how the command's output should be han‐
2539 dled, beyond returning a true value on success and "undef" on failure.
2540 So if you are running a command because you want the output then you
2541 may need to parse that output yourself. If you develop code that
2542 extends Mail::IMAPClient in a way that you feel may be useful to others
2543 then please consider donating the code. Many of the methods in
2544 Mail::IMAPClient were contributed by other programmers such as your‐
2545 self. Their contributions are listed in the Changes file as they occur.
2546 copy($msg,$folder)
2548 Copy a message from the currently selected folder in the the folder
2550 whose name is in $folder
2551 subscribe($folder)
2553 Subscribe to a folder
2555 CAUTION: Once again, remember to quote your quotes (or use the Quote
2557 method) if you want quotes to be part of the IMAP command string.
2558 You can also use the default method to override the behavior of imple‐
2560 mented IMAP methods by changing the case of the method name, preferably
2561 to all-uppercase so as not to conflict with the Class method and acces‐
2562 sor method namespace. For example, if you don't want the search
2563 method's behavior (which returns a list of message numbers) but would
2564 rather have an array of raw data returned from your search operation,
2565 you can issue the following snippet:
2566 my @raw = $imap->SEARCH("SUBJECT","Whatever...");
2568 which is slightly more efficient than the equivalent:
2570 $imap->search("SUBJECT","Whatever...");
2572 my @raw = $imap->Results;
2574 Of course you probably want the search results tucked nicely into a
2576 list for you anyway, in which case you might as well use the search
2577 method.
2578
2580 There are several parameters that influence the behavior of an IMAP‐
2581 Client object. Each is set by specifying a named value pair during new
2582 method invocation as follows:
2583 my $imap = Mail::IMAPClient->new ( parameter => "value",
2585 parameter2 => "value",
2586 ...
2587 );
2588 Parameters can also be set after an object has been instantiated by
2590 using the parameter's eponymous accessor method like this:
2591 my $imap = Mail::IMAPClient->new;
2593 $imap->parameter( "value");
2594 $imap->parameter2("value");
2595 The eponymous accessor methods can also be used without arguments to
2597 obtain the current value of the parameter as follows:
2598 my $imap = Mail::IMAPClient->new;
2600 $imap->parameter( "value");
2601 $imap->parameter2("value");
2602 ... # A whole bunch of awesome perl code,
2604 # omitted for brevity
2605 my $forgot = $imap->parameter;
2607 my $forgot2 = $imap->parameter2;
2608 Note that in these examples I'm using 'parameter' and 'parameter2' as
2610 generic parameter names. The IMAPClient object doesn't actually have
2611 parameters named 'parameter' and 'parameter2'. On the contrary, the
2612 available parameters are:
2613 Authmechanism
2615 Example:
2617 $imap->Authmechanism("CRAM-MD5");
2619 # or
2620 my $authmech = $imap->Authmechanism();
2621 If specified, the Authmechanism causes the specified authentication
2623 mechanism to be used whenever Mail::IMAPClient would otherwise invoke
2624 login. If the value specified for the Authmechanism parameter is not a
2625 valid authentication mechanism for your server then you will never ever
2626 be able to log in again for the rest of your perl script, probably. So
2627 you might want to check, like this:
2628 my $authmech = "CRAM-MD5";
2630 $imap->has_capability($authmech) and $imap->Authmechanism($authmech);
2631 Of course if you know your server supports your favorite authentication
2633 mechanism then you know, so you can then include your Authmechanism
2634 with your new call, as in:
2635 my $imap = Mail::IMAPClient->new(
2637 User => $user,
2638 Passord => $passord,
2639 Server => $server,
2640 Authmechanism => $authmech,
2641 %etc
2642 );
2643 If Authmechanism is supplied but Authcallback is not then you had bet‐
2645 ter be supporting one of the authentication mechanisms that Mail::IMAP‐
2646 Client supports "out of the box" (such as CRAM-MD5).
2647 Authcallback
2649 Example:
2651 $imap->Authcallback( \&callback );
2653 This specifies a default callback to the default authentication mecha‐
2655 nism (see Authmechanism, above). Together, these two methods replace
2656 automatic calls to login with automatic calls that look like this (sort
2657 of):
2658 $imap->authenticate($imap->Authmechanism,$imap->Authcallback) ;
2660 If Authmechanism is supplied but Authcallback is not then you had bet‐
2662 ter be supporting one of the authentication mechanisms that Mail::IMAP‐
2663 Client supports "out of the box" (such as CRAM-MD5).
2664 Buffer
2666 Example:
2668 $Buffer = $imap->Buffer();
2670 # or:
2671 $imap->Buffer($new_value);
2672 The Buffer parameter sets the size of a block of I/O. It is ignored
2674 unless Fast_io, below, is set to a true value (the default), or unless
2675 you are using the migrate method. It's value should be the number of
2676 bytes to attempt to read in one I/O operation. The default value is
2677 4096.
2678 When using the migrate method, you can often achieve dramatic improve‐
2680 ments in throughput by adjusting this number upward. However, doing so
2681 also entails a memory cost, so if set too high you risk losing all the
2682 benefits of the migrate method's chunking algorythm. Your program can
2683 thus terminate with an "out of memory" error and you'll have no one but
2684 yourself to blame.
2685 Note that, as hinted above, the Buffer parameter affects the behavior
2687 of the migrate method regardless of whether you have Fast_io turned on.
2688 Believe me, you don't want to go around migrating tons of mail without
2689 using buffered I/O!
2690 Clear
2692 Example:
2694 $Clear = $imap->Clear();
2696 # or:
2697 $imap->Clear($new_value);
2698 The name of this parameter, for historical reasons, is somewhat mis‐
2700 leading. It should be named Wrap, because it specifies how many trans‐
2701 actions are stored in the wrapped history buffer. But it didn't always
2702 work that way; the buffer used to actually get cleared. The name though
2703 remains the same in the interests of backwards compatibility. Also I'm
2704 too lazy to change it.
2705 Clear specifies that the object's history buffer should be wrapped
2707 after every n transactions, where n is the value specified for the
2708 Clear parameter. Calling the eponymous Clear method without an argument
2709 will return the current value of the Clear parameter but will not cause
2710 clear the history buffer to wrap.
2711 Setting Clear to 0 turns off automatic history buffer wrapping, and
2713 setting it to 1 turns off the history buffer facility (except for the
2714 last transaction, which cannot be disabled without breaking the IMAP‐
2715 Client module). Setting Clear to 0 will not cause an immediate clearing
2716 of the history buffer; setting it to 1 (or any other number) will
2717 (except of course for that inevitable last transaction).
2718 The default Clear value is set to five in order to conserve memory.
2720 Debug
2722 Example:
2724 $Debug = $imap->Debug();
2726 # or:
2727 $imap->Debug($true_or_false);
2728 Sets the debugging flag to either a true or false value. Can be sup‐
2730 plied with the new method call or separately by calling the Debug
2731 object method. Use of this parameter is strongly recommended when
2732 debugging scripts and required when reporting bugs.
2733 Debug_fh
2735 Example:
2737 $Debug_fh = $imap->Debug_fh();
2739 # or:
2740 $imap->Debug_fh($fileHandle);
2741 Specifies the filehandle to which debugging information should be
2743 printed. It can either a filehandle object reference or a filehandle
2744 glob. The default is to print debugging info to STDERR.
2745 For example, you can:
2747 use Mail::IMAPClient;
2749 use IO::File;
2750 # set $user, $pass, and $server here
2751 my $dh = IO::File->new(">debugging.output")
2752 or die "Can't open debugging.output: $!\n";
2753 my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass,
2754 Server=>$server, Debug=> "yes, please",
2755 Debug_fh => $dh
2756 );
2757 which is the same as:
2759 use Mail::IMAPClient;
2761 use IO::File;
2762 # set $user, $pass, and $server here
2763 my $imap = Mail::IMAPClient->new( User =>$user,
2764 Password=>$pass,
2765 Server =>$server,
2766 Debug => "yes, please",
2767 Debug_fh=> IO::File->new(">debugging.output") ⎪⎪
2768 die "Can't open debugging.output: $!\n"
2769 );
2770 You can also:
2772 use Mail::IMAPClient;
2774 # set $user, $pass, and $server here
2775 open(DBG,">debugging.output")
2776 or die "Can't open debugging.output: $!\n";
2777 my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass,
2778 Server=>$server, Debug=> 1,
2779 Debug_fh => *DBG
2780 );
2781 Specifying this parameter is not very useful unless Debug is set to a
2783 true value.
2784 EnableServerResponseInLiteral
2786 Example:
2788 $EnableServerResponseInLiteral = $imap->EnableServerResponseInLiteral();
2790 # or:
2791 $imap->EnableServerResponseInLiteral($new_value);
2792 The EnableServerResponseInLiteral parameter tells Mail::IMAPClient to
2794 expect server responses to be embedded in literal strings. Usually lit‐
2795 eral strings contain only message data, not server responses. I have
2796 seen at least one IMAP server implementation though that includes the
2797 final <tag> OK response in the literal data. If your server does this
2798 then your script will hang whenever you try to read literal data, such
2799 as message text, or even output from the folders method if some of your
2800 folders have special characters such as double quotes or sometimes spa‐
2801 ces in the name.
2802 I am pretty sure this behavior is not RFC2060 compliant so I am drop‐
2804 ping it by default. In fact, I encountered the problem a long time ago
2805 when still new to IMAP and may have imagined the whole thing. However,
2806 if your scripts hang running certain methods you may want to at least
2807 try enabling this parameter by passing the eponymous method a true
2808 value.
2809 Fast_io
2811 Example:
2813 $Fast_io = $imap->Fast_io();
2815 # or:
2816 $imap->Fast_io($true_or_false);
2817 The Fast_io parameter controlls whether or not your Mail::IMAPClient
2819 object will attempt to use buffered (i.e. "Fast") I/O. It is turned on
2820 by default. If you turn it off you will definately slow down your pro‐
2821 gram, often to a painfull degree. However, if you are experience prob‐
2822 lems you may want to try this just to see if it helps. If it does then
2823 that means you have found a bug and should report it immediately (by
2824 following the instructions in the section on "REPORTING BUGS"). Even if
2825 it doesn't fix the problem, testing with both Fast_io turned on and
2826 with it turned off will often aid in identifying the source of the
2827 problem. (If it doesn't help you, it may help me when you report it!)
2828 Lately there have not been any bugs associated with Fast_io so this
2830 parameter may become deprecated in the future.
2831 Folder
2833 Example:
2835 $Folder = $imap->Folder();
2837 # or:
2838 $imap->Folder($new_value);
2839 The Folder parameter returns the name of the currently-selected folder
2841 (in case you forgot). It can also be used to set the name of the cur‐
2842 rently selected folder, which is completely unnecessary if you used the
2843 select method (or select's read-only equivalent, the examine method) to
2844 select it.
2845 Note that setting the Folder parameter does not automatically select a
2847 new folder; you use the select or examine object methods for that.
2848 Generally, the Folder parameter should only be queried (by using the
2849 no-argument form of the Folder method). You will only need to set the
2850 Folder parameter if you use some mysterious technique of your own for
2851 selecting a folder, which you probably won't do.
2852 Maxtemperrors
2854 Example:
2856 $Maxtemperrors = $imap->Maxtemperrors();
2858 # or:
2859 $imap->Maxtemperrors($new_value);
2860 The Maxtemperrors parameter specifies the number of times a write oper‐
2862 ation is allowed to fail on a "Resource Temporarily Available" error.
2863 These errors can occur from time to time if the server is too busy to
2864 empty out its read buffer (which is logically the "other end" of the
2865 client's write buffer). By default, Mail::IMAPClient will retry an
2866 unlimited number of times, but you can adjust this behavior by setting
2867 Maxtemperrors. Note that after each temporary error, the server will
2868 wait for a number of seconds equal to the number of consecutive tempo‐
2869 rary errors times .25, so very high values for Maxtemperrors can slow
2870 you down in a big way if your "temporary error" is not all that tempo‐
2871 rary.
2872 You can set this parameter to "UNLIMITED" to ignore "Resource Temporar‐
2874 ily Unavailable" errors. This is the default.
2875 Password
2877 Example:
2879 $Password = $imap->Password();
2881 # or:
2882 $imap->Password($new_value);
2883 Specifies the password to use when logging into the IMAP service on the
2885 host specified in the Server parameter as the user specified in the
2886 User parameter. Can be supplied with the new method call or separately
2887 by calling the Password object method.
2888 If Server, User, and Password are all provided to the new method, then
2890 the newly instantiated object will be connected to the host specified
2891 in Server (at either the port specified in Port or the default port
2892 143) and then logged on as the user specified in the User parameter
2893 (using the password provided in the Password parameter). See the dis‐
2894 cussion of the "new" method, below.
2895 Peek
2897 Example:
2899 $Peek = $imap->Peek();
2901 # or:
2902 $imap->Peek($true_or_false);
2903 Setting Peek to a true value will prevent the body_string, mes‐
2905 sage_string and message_to_file methods from automatically setting the
2906 \Seen flag. Setting "Peek" to 0 (zero) will force "body_string", "mes‐
2907 sage_string", "message_to_file", and "parse_headers" to always set the
2908 \Seen flag.
2909 The default is to set the seen flag whenever you fetch the body of a
2911 message but not when you just fetch the headers. Passing undef to the
2912 eponymous Peek method will reset the Peek parameter to its pristine,
2913 default state.
2914 Port
2916 Example:
2918 $Port = $imap->Port();
2920 # or:
2921 $imap->Port($new_value);
2922 Specifies the port on which the IMAP server is listening. The default
2924 is 143, which is the standard IMAP port. Can be supplied with the new
2925 method call or separately by calling the Port object method.
2926 Prewritemethod
2928 Specifies a method to call if your authentication mechanism requires
2930 you to to do pre-write processing of the data sent to the server. If
2931 defined, then the Prewritemethod parameter should contain a reference
2932 to a subroutine that will do Special Things to data before it is sent
2933 to the IMAP server (such as encryption or signing).
2934 This method will be called immediately prior to sending an IMAP client
2936 command to the server. Its first argument is a reference to the
2937 Mail::IMAPClient object and the second argument is a string containing
2938 the command that will be sent to the server. Your Prewritemethod should
2939 return a string that has been signed or encrypted or whatever; this
2940 returned string is what will actually be sent to the server.
2941 Your Prewritemethod will probably need to know more than this to do
2943 whatever it does. It is recommended that you tuck all other pertinent
2944 information into a hash, and store a reference to this hash somewhere
2945 where your method can get to it, possibly in the Mail::IMAPClient
2946 object itself.
2947 Note that this method should not actually send anything over the socket
2949 connection to the server; it merely converts data prior to sending.
2950 If you need a Prewritemethod then you probably need a Readmethod as
2952 well.
2953 Ranges
2955 Example:
2957 $imap->Ranges(1);
2959 # or:
2960 my $search = $imap->search(@search_args);
2961 if ( $imap->Ranges) { # $search is a MessageSet object
2962 print "This is my condensed search result: $search\n";
2963 print "This is every message in the search result: ",
2964 join(",",@$search),"\n;
2965 }
2966 If set to a true value, then the search method will return a
2968 Mail::IMAPClient::MessageSet object if called in a scalar context,
2969 instead of the array reference that fetch normally returns when called
2970 in a scalar context. If set to zero or if undefined, then search will
2971 continue to return an array reference when called in scalar context.
2972 This parameter has no affect on the search method when search is called
2974 in a list context.
2975 Readmethod
2977 This parameter, if supplied, should contain a reference to a subroutine
2979 that will replace sysreads. The subroutine will be passed the following
2980 arguments:
2981 1. imap_object_ref - a reference to the current imap object
2983 2. scalar_ref - a reference to a scalar variable into which data is
2985 read. The data place in here should be "finished data", so if you
2986 are decrypting or removing signatures then be sure to do that
2987 before you place data into this buffer.
2988 3. read_length - the number of bytes requested to be read
2990 4. offset - the offset into "scalar_ref" into which data should be
2992 read. If not supplied it should default to zero.
2993 Note that this method completely replaces reads from the connection to
2995 the server, so if you define one of these then your subroutine will
2996 have to actually do the read. It is for things like this that we have
2997 the Socket parameter and eponymous accessor method.
2998 Your Readmethod will probably need to know more than this to do what‐
3000 ever it does. It is recommended that you tuck all other pertinent
3001 information into a hash, and store a reference to this hash somewhere
3002 where your method can get to it, possibly in the Mail::IMAPClient
3003 object itself.
3004 If you need a Readmethod then you probably need a Prewritemethod as
3006 well.
3007 Server
3009 Example:
3011 $Server = $imap->Server();
3013 # or:
3014 $imap->Server($hostname);
3015 Specifies the hostname or IP address of the host running the IMAP
3017 server. If provided as part of the new method call, then the new IMAP
3018 object will automatically be connected at the time of instantiation.
3019 (See the new method, below.) Can be supplied with the new method call
3020 or separately by calling the Server object method.
3021 Showcredentials
3023 Normally debugging output will mask the login credentials when the
3025 plain text login mechanism is used. Setting Showcredentials to a true
3026 value will suppress this, so that you can see the string being passed
3027 back and forth during plain text login. Only set this to true when you
3028 are debugging problems with the IMAP LOGIN command, and then turn it
3029 off right away when you're finished working on that problem.
3030 Example:
3032 print "This is very risky!\n" if $imap->Showcredentials();
3034 # or:
3035 $imap->Showcredentials(0); # mask credentials again
3036 Socket
3038 Example:
3040 $Socket = $imap->Socket();
3042 # or:
3043 $imap->Socket($socket_fh);
3044 The Socket method can be used to obtain the socket handle of the cur‐
3046 rent connection (say, to do I/O on the connection that is not otherwise
3047 supported by Mail::IMAPClient) or to replace the current socket with a
3048 new handle (perhaps an SSL handle, for example).
3049 If you supply a socket handle yourself, either by doing something like:
3051 $imap=Mail::IMAPClient->new(Socket=>$sock, User => ... );
3053 or by doing something like:
3055 $imap=Mail::IMAPClient->new(User => $user, Password => $pass, Server => $host);
3057 # blah blah blah
3058 $imap->Socket($ssl);
3059 then it will be up to you to establish the connection AND to authenti‐
3061 cate, either via the login method, or the fancier authenticate, or,
3062 since you know so much anyway, by just doing raw I/O against the socket
3063 until you're logged in. If you do any of this then you should also set
3064 the State parameter yourself to reflect the current state of the object
3065 (i.e. Connected, Authenticated, etc).
3066 Timeout
3068 Example:
3070 $Timeout = $imap->Timeout();
3072 # or:
3073 $imap->Timeout($new_value);
3074 Specifies the timeout value in seconds for reads. Specifying a true
3076 value for Timeout will prevent Mail::IMAPClient from blocking in a
3077 read.
3078 Since timeouts are implemented via the perl select operator, the Time‐
3080 out parameter may be set to a fractional number of seconds. Not supply‐
3081 ing a Timeout, or (re)setting it to zero, disables the timeout feature.
3082 Uid
3084 Example:
3086 $Uid = $imap->Uid();
3088 # or:
3089 $imap->Uid($true_or_false);
3090 If Uid is set to a true value (i.e. 1) then the behavior of the fetch,
3092 search, copy, and store methods (and their derivatives) is changed so
3093 that arguments that would otherwise be message sequence numbers are
3094 treated as message UID's and so that return values (in the case of the
3095 search method and its derivatives) that would normally be message
3096 sequence numbers are instead message UID's.
3097 Internally this is implemented as a switch that, if turned on, causes
3099 methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or
3100 COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH,
3101 or UID COPY, respectively. The main difference between message sequence
3102 numbers and message UID's is that, according to RFC2060, UID's must not
3103 change during a session and should not change between sessions, and
3104 must never be reused. Sequence numbers do not have that same guarantee
3105 and in fact may be reused right away.
3106 Since foldernames also have a unique identifier (UIDVALIDITY), which is
3108 provided when the folder is selected or examined or by doing something
3109 like "$imap->status($folder,"UIDVALIDITY"), it is possible to uniquely
3110 identify every message on the server, although normally you won't need
3111 to bother.
3112 The methods currently affected by turning on the Uid flag are:
3114 copy fetch
3116 search store
3117 message_string message_uid
3118 body_string flags
3119 move size
3120 parse_headers thread
3121 Note that if for some reason you only want the Uid parameter turned on
3123 for one command, then you can choose between the following two snip‐
3124 pets, which are equivalent:
3125 Example 1:
3127 $imap->Uid(1);
3129 my @uids = $imap->search('SUBJECT',"Just a silly test"); #
3130 $imap->Uid(0);
3131 Example 2:
3133 my @uids;
3135 foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
3136 chomp $r;
3137 $r =~ s/\r$//;
3138 $r =~ s/^\*\s+SEARCH\s+// or next;
3139 push @uids, grep(/\d/,(split(/\s+/,$r)));
3140 }
3141 In the second example, we used the default method to issue the UID IMAP
3143 Client command, being careful to use an all-uppercase method name so as
3144 not to inadvertently call the Uid accessor method. Then we parsed out
3145 the message UIDs manually, since we don't have the benefit of the
3146 built-in search method doing it for us.
3147 Please be very careful when turning the Uid parameter on and off
3149 throughout a script. If you loose track of whether you've got the Uid
3150 parameter turned on you might do something sad, like deleting the wrong
3151 message. Remember, like all eponymous accessor methods, the Uid method
3152 without arguments will return the current value for the Uid parameter,
3153 so do yourself a favor and check. The safest approach is probably to
3154 turn it on at the beginning (or just let it default to being on) and
3155 then leave it on. (Remember that leaving it turned off can lead to
3156 problems if changes to a folder's contents cause resequencing.)
3157 By default, the Uid parameter is turned on.
3159 User
3161 Example:
3163 $User = $imap->User();
3165 # or:
3166 $imap->User($userid);
3167 Specifies the userid to use when logging into the IMAP service. Can be
3169 supplied with the new method call or separately by calling the User
3170 object method.
3171 Parameters can be set during new method invocation by passing named
3173 parameter/value pairs to the method, or later by calling the parame‐
3174 ter's eponymous object method.
3175
3177 There are several object methods that return the status of the object.
3178 They can be used at any time to check the status of an IMAPClient
3179 object, but are particularly useful for determining the cause of fail‐
3180 ure when a connection and login are attempted as part of a single new
3181 method invocation. The status methods are:
3182 Escaped_results
3184 Example: my @results = $imap->Escaped_results ;
3186 The Escaped_results method is almost identical to the History method.
3188 Unlike the History method, however, server output transmitted literally
3189 will be wrapped in double quotes, with all of the parentheses, double
3190 quotes, backslashes, newlines, and carrage returns escaped. If called
3191 in a scalar context, Escaped_results returns an array reference rather
3192 than an array.
3193 Escaped_results is useful if you are retrieving output and processing
3195 it manually, and you are depending on the above special characters to
3196 delimit the data. It is not useful when retrieving message contents;
3197 use message_string or body_string for that.
3198 History
3200 Example:
3202 my @history = $imap->History;
3204 The History method is almost identical to the Results method. Unlike
3206 the Results method, however, the IMAP command that was issued to create
3207 the results being returned is not included in the returned results. If
3208 called in a scalar context, History returns an array reference rather
3209 than an array.
3210 IsUnconnected
3212 returns a true value if the object is currently in an Unconnected
3214 state.
3215 IsConnected
3217 returns a true value if the object is currently in either a Connected,
3219 Authenticated, or Selected state.
3220 IsAuthenticated
3222 returns a true value if the object is currently in either an Authenti‐
3224 cated or Selected state.
3225 IsSelected
3227 returns a true value if the object is currently in a Selected state.
3229 LastError
3231 Internally LastError is implemented just like a parameter (as described
3233 in "Parameters", above). There is a LastError attribute and an epony‐
3234 mous accessor method which returns the LastError text string describing
3235 the last error condition encountered by the server.
3236 Note that some errors are more serious than others, so LastError's
3238 value is only meaningful if you encounter an error condition that you
3239 don't like. For example, if you use the exists method to see if a
3240 folder exists and the folder does not exist, then an error message will
3241 be recorded in LastError even though this is not a particularly serious
3242 error. On the other hand, if you didn't use exists and just tried to
3243 select a non-existing folder, then select would return "undef" after
3244 setting LastError to something like "NO SELECT failed: Can't open mail‐
3245 box "mailbox": no such mailbox". At this point it would be useful to
3246 print out the contents of LastError as you die.
3247 LastIMAPCommand
3249 New in version 2.0.4, LastIMAPCommand returns the exact IMAP command
3251 string to be sent to the server. Useful mainly in constructing error
3252 messages when LastError just isn't enough.
3253 Report
3255 The Report method returns an array containing a history of the IMAP
3257 session up to the point that Report was called. It is primarily meant
3258 to assist in debugging but can also be used to retrieve raw output for
3259 manual parsing. The value of the Clear parameter controls how many
3260 transactions are in the report. (See the discussion of Clear in "Param‐
3261 eters", above.)
3262 Results
3264 The Results method returns an array containing the results of one IMAP
3266 client command. It accepts one argument, the transaction number of the
3267 command whose results are to be returned. If transaction number is
3268 unspecified then Results returns the results of the last IMAP client
3269 command issued. If called in a scalar context, Results returns an array
3270 reference rather than an array.
3271 State
3273 The State method returns a numerical value that indicates the current
3275 status of the IMAPClient object. If invoked with an argument, it will
3276 set the object's state to that value. If invoked without an argument,
3277 it behaves just like Status, below.
3278 Normally you will not have to invoke this function. An exception is if
3280 you are bypassing the Mail::IMAPClient module's connect and/or login
3281 modules to set up your own connection (say, for example, over a secure
3282 socket), in which case you must manually do what the connect and login
3283 methods would otherwise do for you.
3284 Status
3286 The Status method returns a numerical value that indicates the current
3288 status of the IMAPClient object. (Not to be confused with the status
3289 method, all lower-case, which is the implementation of the STATUS IMAP
3290 client command.)
3291 Transaction
3293 The Transaction method returns the tag value (or transaction number) of
3295 the last IMAP client command.
3296
3298 There are two types of undocumented subroutines and methods. The first
3299 are methods that are not documented because they don't exist, even
3300 though they work just fine. Some of my favorite Mail::IMAPClient meth‐
3301 ods don't exist but I use them all the time anyway. You can too, assum‐
3302 ing you have your copy of RFC2060 and its extension RFC's handy. (By
3303 the way, you do have them handy because I gave them to you. They're
3304 bundled with the Mail::IMAPClient distribution in the docs/ subdirec‐
3305 tory.) You should feel free to use any of these undocumented methods.
3306 These undocumented methods all use what this document refers to as the
3308 "default method". See "Other IMAP Client Commands and the Default
3309 Object Method", above, for more information on the default method.
3310 There are also some undocumented methods and subroutines that actually
3312 do exist. Don't use these! If they aren't documented it's for a reason.
3313 They are either experimental, or intended for use by other Mail::IMAP‐
3314 Client methods only, or deprecated, or broken, or all or none of the
3315 above. In no cases can you write programs that use these methods and
3316 assume that these programs will work with the next version of
3317 Mail::IMAPClient. I never try to make these undocumented methods and
3318 subroutines backwards compatible because they aren't part of the docu‐
3319 mented API.
3320 Occasionally I will add a method and forget to document it; in that
3322 case it's a bug and you should report it. (See "REPORTING BUGS",
3323 below.) It is sometimes hard to tell the difference; if in doubt you
3324 may submit a bug report and see what happens! However, don't bothering
3325 submitting bug reports for missing documentation for any method or sub‐
3326 routine that begins with an underscore (_) character. These methods are
3327 always private and will never be part of the documented interface.
3328
3330 Please feel free to e-mail the author at "bug-Mail-IMAP‐
3331 Client@rt.cpan.org" if you encounter any strange behaviors. Don't worry
3332 about hurting my feelings or sounding like a whiner or anything like
3333 that; if there's a problem with this module you'll be doing me a favor
3334 by reporting it. However, I probably won't be able to do much about it
3335 if you don't include enough information, so please read and follow
3336 these instructions carefully.
3337 When reporting a bug, please be sure to include the following:
3339 - As much information about your environment as possible. I especially
3341 need to know which version of Mail::IMAPClient you are running and the
3342 type/version of IMAP server to which you are connecting. Your OS and
3343 perl verions would be helpful too.
3344 - As detailed a description of the problem as possible. (What are you
3346 doing? What happens? Have you found a work-around?)
3347 - An example script that demonstrates the problem (preferably with as
3349 few lines of code as possible!) and which calls the Mail::IMAPClient's
3350 new method with the Debug parameter set to "1". (If this generates a
3351 ridiculous amount of output and you're sure you know where the problem
3352 is, you can create your object with debugging turned off and then turn
3353 it on later, just before you issue the commands that recreate the prob‐
3354 lem. On the other hand, if you can do this you can probably also reduce
3355 the program rather than reducing the output, and this would be the best
3356 way to go under most circumstances.)
3357 - Output from the example script when it's running with the Debug
3359 parameter turned on. You can edit the output to remove (or preferably
3360 to "X" out) sensitive data, such as hostnames, user names, and pass‐
3361 words, but PLEASE do not remove the text that identifies the TYPE of
3362 IMAP server to which you are connecting. Note that in most versions of
3363 Mail::IMAPClient, debugging does not print out the user or password
3364 from the login command line. However, if you use some other means of
3365 authenticating then you may need to edit the debugging output with an
3366 eye to security.
3367 - If something worked in a previous release and doesn't work now,
3369 please tell me which release did work. You don't have to test every
3370 intervening release; just let me know it worked in version x but
3371 doesn't work in version (x+n) or whatever.
3372 - Don't be surprised if I come back asking for a trace of the problem.
3374 To provide this, you should create a file called .perldb in your cur‐
3375 rent working directory and include the following line of text in that
3376 file:
3377 "&parse_options("NonStop=1 LineInfo=mail_imapclient_db.out");"
3379 For your debugging convenience, a sample .perldb file, which was ran‐
3381 domly assigned the name sample.perldb, is provided in the distribution.
3382 Next, without changing your working directory, debug the example script
3384 like this: "perl -d example_script.pl [ args ]"
3385 Note that in these examples, the script that demonstrates your problem
3387 is named "example_script.pl" and the trace output will be saved in
3388 "mail_imapclient_db.out". You should either change these values to suit
3389 your needs, or change your needs to suit these values.
3390 Bug reports should be mailed to:
3392 bug-Mail-IMAPClient@rt.cpan.org
3394 Please remember to place a SHORT description of the problem in the sub‐
3396 ject of the message. Please try to be a bit specific; things like "Bug
3397 in Mail::IMAPClient" or "Computer Problem" won't exactly expedite
3398 things on my end.
3399
3401 If you have suggestions for extending this functionality of this mod‐
3402 ule, or if you have a question and you can't find an answer in any of
3403 the documentation (including the RFC's, which are included in this dis‐
3404 tribution for a reason), then you can e-mail me at the following
3405 address:
3406 DJKERNEN@cpan.org
3408 Please note that this address is for questions, suggestions, and other
3410 comments about Mail::IMAPClient. It's not for reporting bugs, it's not
3411 for general correspondence, and it's especially not for selling porn,
3412 mortgages, Viagra, penis enlargment pills, DVD copying software, or
3413 anything else.
3414
3416 David J. Kernen
3417 The Kernen Consulting Group, Inc
3418 DJKERNEN@cpan.org
3419
3421 Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
3422 All rights reserved.
3423 This program is free software; you can redistribute it and/or modify it
3425 under the terms of either:
3426 a) the "Artistic License" which comes with this Kit, or
3428 b) the GNU General Public License as published by the Free Software
3429 Foundation; either version 1, or (at your option) any later version.
3430 This program is distributed in the hope that it will be useful, but
3432 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
3433 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
3434 General Public License or the Artistic License for more details. All
3435 your base are belong to us.
3436perl v5.8.8 2003-06-13 IMAPClient(3)