.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Mail::IMAPClient 3pm" .TH Mail::IMAPClient 3pm "2021-09-11" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mail::IMAPClient \- An IMAP Client API .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Mail::IMAPClient; \& \& my $imap = Mail::IMAPClient\->new( \& Server => \*(Aqlocalhost\*(Aq, \& User => \*(Aqusername\*(Aq, \& Password => \*(Aqpassword\*(Aq, \& Ssl => 1, \& Uid => 1, \& ); \& \& my $folders = $imap\->folders \& or die "List folders error: ", $imap\->LastError, "\en"; \& print "Folders: @$folders\en"; \& \& $imap\->select( $Opt{folder} ) \& or die "Select \*(Aq$Opt{folder}\*(Aq error: ", $imap\->LastError, "\en"; \& \& $imap\->fetch_hash("FLAGS", "INTERNALDATE", "RFC822.SIZE") \& or die "Fetch hash \*(Aq$Opt{folder}\*(Aq error: ", $imap\->LastError, "\en"; \& \& $imap\->logout \& or die "Logout error: ", $imap\->LastError, "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides methods implementing the \s-1IMAP\s0 protocol to support interacting with \s-1IMAP\s0 message stores. .PP The module is used by constructing or instantiating a new IMAPClient object via the \*(L"new\*(R" constructor method. Once the object has been instantiated, the \*(L"connect\*(R" method is either implicitly or explicitly called. At that point methods are available that implement the \s-1IMAP\s0 client commands as specified in \fB\s-1RFC3501\s0\fR. When processing is complete, the \*(L"logout\*(R" object method should be called. .PP This documentation is not meant to be a replacement for \s-1RFC3501\s0 nor any other \s-1IMAP\s0 related RFCs. .PP Note that this documentation uses the term \fIfolder\fR in place of \&\s-1RFC3501\s0's use of \fImailbox\fR. This documentation reserves the use of the term \fImailbox\fR to refer to the set of folders owned by a specific \&\s-1IMAP\s0 id. .SS "Connection State" .IX Subsection "Connection State" \&\s-1RFC3501\s0 defines four possible states for an \s-1IMAP\s0 connection: not authenticated, authenticated, selected, and logged out. These correspond to the IMAPClient constants \f(CW\*(C`Connected\*(C'\fR, \f(CW\*(C`Authenticated\*(C'\fR, \&\f(CW\*(C`Selected\*(C'\fR, and \f(CW\*(C`Unconnected\*(C'\fR, respectively. These constants can be used in conjunction with the \*(L"Status\*(R" method to determine the status of an IMAPClient object and its underlying \s-1IMAP\s0 session. .PP Note that an IMAPClient object can be in the \f(CW\*(C`Unconnected\*(C'\fR state both before a server connection is made and after it has ended. This differs slightly from \s-1RFC3501,\s0 which does not define a pre-connection status. For a discussion of the methods available for examining the IMAPClient object's status, see the section labeled \&\*(L"Status Methods\*(R", below. .SS "Advanced Authentication Mechanisms" .IX Subsection "Advanced Authentication Mechanisms" \&\s-1RFC3501\s0 defines two commands for authenticating to an \s-1IMAP\s0 server: .IP "\s-1LOGIN\s0" 4 .IX Item "LOGIN" \&\s-1LOGIN\s0 is for plain text authentication. .IP "\s-1AUTHENTICATE\s0" 4 .IX Item "AUTHENTICATE" \&\s-1AUTHENTICATE\s0 for more advanced and/or secure authentication mechanisms. .PP Mail::IMAPClient supports the following \s-1AUTHENTICATE\s0 mechanisms: .IP "\s-1DIGEST\-MD5\s0" 4 .IX Item "DIGEST-MD5" \&\s-1DIGEST\-MD5\s0 authentication requires the Authen::SASL and Digest::MD5 modules. See also \*(L"Authuser\*(R". .IP "\s-1CRAM\-MD5\s0" 4 .IX Item "CRAM-MD5" \&\s-1CRAM\-MD5\s0 requires the Digest::HMAC_MD5 module. .IP "\s-1PLAIN\s0 (\s-1SASL\s0)" 4 .IX Item "PLAIN (SASL)" \&\s-1PLAIN\s0 (\s-1SASL\s0) authentication allows the optional use of the \*(L"Proxy\*(R" parameter. \s-1RFC 4616\s0 documents this syntax for \s-1SASL PLAIN:\s0 .Sp .Vb 1 \& message = [authzid] UTF8NUL authcid UTF8NUL passwd .Ve .Sp When \*(L"Proxy\*(R" is defined, \*(L"User\*(R" is used as 'authzid' and \*(L"Proxy\*(R" is used as 'authcid'. Otherwise, \*(L"User\*(R" is used as 'authcid'. .IP "\s-1NTLM\s0" 4 .IX Item "NTLM" \&\s-1NTLM\s0 authentication requires the Authen::NTLM module. See also \&\*(L"Domain\*(R". .SS "Errors" .IX Subsection "Errors" If you attempt an operation that results in an error, then you can retrieve the text of the error message by using the \*(L"LastError\*(R" method. However, the \*(L"LastError\*(R" method is an object method (not a class method) and can only be used once an object is successfully created. In cases where an object is not successfully created the \&\f(CW$@\fR variable is set with an error message. .PP Mail::IMAPClient resets \f(CW$@\fR and \*(L"LastError\*(R" to undef before most \&\s-1IMAP\s0 requests, so the values only have a short lifespan. \&\*(L"LastError\*(R" will always contain error info from the last error, until another error is encountered, another \s-1IMAP\s0 command is issued or it is explicitly cleared. .PP Please note that the use of \f(CW$@\fR is subject to change in the future release so it is best to use \*(L"LastError\*(R" for error checking once a Mail::IMAPClient object has been created. .PP Errors in the \*(L"new\*(R" method can prevent your object from ever being created. If the \*(L"Server\*(R", \*(L"User\*(R", and \*(L"Password\*(R" parameters are supplied to \*(L"new\*(R", it will attempt to call \*(L"connect\*(R" and \&\*(L"login\*(R". Any of these methods could fail and cause the \*(L"new\*(R" method call to return \f(CW\*(C`undef\*(C'\fR and leaving the variable \f(CW$@\fR is set to an error message. .PP \&\s-1WARNING:\s0 (due to historical \s-1API\s0 behavior) on errors, many methods may return undef regardless of \s-1LIST/SCALAR\s0 context. Therefore, it may be wise to use most methods in a scalar context. Regardless, check \&\*(L"LastError\*(R" for details on errors. .SS "Transactions" .IX Subsection "Transactions" \&\s-1RFC3501\s0 requires that each line in an \s-1IMAP\s0 conversation be prefixed with a tag. A typical conversation consists of the client issuing a tag-prefixed command string, and the server replying with one of more lines of output. Those lines of output will include a command completion status code prefixed by the same tag as the original command string. .PP The IMAPClient module uses a simple counter to ensure that each client command is issued with a unique tag value. This tag value is referred to by the IMAPClient module as the transaction number. A history is maintained by the IMAPClient object documenting each transaction. The \&\*(L"Transaction\*(R" method returns the number of the last transaction, and can be used to retrieve lines of text from the object's history. .PP The \*(L"Clear\*(R" parameter is used to control the size of the session history so that long-running sessions do not eat up unreasonable amounts of memory. See the discussion of \*(L"Clear\*(R" parameter for more information. .PP The \*(L"Report\*(R" transaction returns the history of the entire \s-1IMAP\s0 session since the initial connection or for the last \*(L"Clear\*(R" transactions. This provides a record of the entire conversation, including client command strings and server responses, and is a wonderful debugging tool as well as a useful source of raw data for custom parsing. .SH "CLASS METHODS" .IX Header "CLASS METHODS" There are a couple of methods that can be invoked as class methods. Generally they can be invoked as an object method as well. Note that if the \*(L"new\*(R" method is called as an object method, the object returned is identical to what have would been returned if \*(L"new\*(R" had been called as a class method. It doesn't give you a copy of the original object. .SS "new" .IX Subsection "new" Example: .PP .Vb 2 \& my $imap = Mail::IMAPClient\->new(%args) \& or die "new failed: $@\en"; .Ve .PP The \*(L"new\*(R" method creates a new instance of an IMAPClient object. .PP If the \*(L"Server\*(R" parameter is passed as an argument to \fBnew\fR, then \&\fBnew\fR will implicitly call the \*(L"connect\*(R" method, placing the new object in the \fIConnected\fR state. If \*(L"User\*(R" and \*(L"Password\*(R" values are also provided, then \*(L"connect\*(R" will in turn call \*(L"login\*(R", and the resulting object will be returned from \fBnew\fR in the \&\fIAuthenticated\fR state. .PP If the \*(L"Server\*(R" parameter is not supplied then the IMAPClient object is created in the \fIUnconnected\fR state. .PP If the \fBnew\fR method is passed arguments then those arguments will be treated as a list of key=>value pairs. The key should be one of the parameters as documented under \*(L"Parameters\*(R" below. .PP Here are some examples: .PP .Vb 1 \& use Mail::IMAPClient; \& \& # returns an unconnected Mail::IMAPClient object: \& my $imap = Mail::IMAPClient\->new; \& # ... \& # intervening code using the 1st object, then: \& # (returns a new, authenticated Mail::IMAPClient object) \& $imap = Mail::IMAPClient\->new( \& Server => $host, \& User => $id, \& Password => $pass, \& Clear => 5, # Unnecessary since \*(Aq5\*(Aq is the default \& # ... # Other key=>value pairs go here \& ) or die "Cannot connect to $host as $id: $@"; .Ve .PP See also \*(L"Parameters\*(R", \*(L"connect\*(R" and \*(L"login\*(R" for more information on how to manually connect and login after \fBnew\fR. .SS "Quote" .IX Subsection "Quote" Example: .PP .Vb 1 \& $imap\->search( HEADER => \*(AqMessage\-id\*(Aq => \e$imap\->Quote($msg_id) ); .Ve .PP The \fBQuote\fR method accepts a value as an argument and returns its argument as a correctly quoted string or a literal string. Since version 3.17 Mail::IMAPClient automatically quotes search arguments we use a \s-1SCALARREF\s0 so search will not modify or re-quote the value returned by \fBQuote\fR. .PP Note this method should not be used on folder names for Mail::IMAPClient methods, since methods that accept folder names as an argument will quote the folder name arguments automatically. .PP If you are getting unexpected results when running methods with values that have (or might have) embedded spaces, double quotes, braces, or parentheses, then calling \fBQuote\fR may be necessary. This method should \fBnot\fR be used with arguments that are wrapped in quotes or parens if those quotes or parens are required by \s-1RFC3501.\s0 For example, if the \s-1RFC\s0 requires an argument in this format: .PP .Vb 1 \& ( argument ) .Ve .PP and the argument is (or might be) \*(L"pennies (from heaven)\*(R", then one could use: .PP .Vb 1 \& $argument = "(" . $imap\->Quote($argument) . ")" .Ve .PP Of course, the fact that sometimes these characters are sometimes required delimiters is precisely the reason you must quote them when they are \fInot\fR delimiting. .PP However, there are times when a method fails unexpectedly and may require the use of \fBQuote\fR to work. Should this happen, you can probably file a bug/enhancement request for Mail::IMAPClient to safeguard the particular call/case better. .PP An example is \s-1RFC822\s0 Message-id's, which \fIusually\fR don't contain quotes or parens. When dealing with these it is usually best to take proactive, defensive measures from the very start and use \fBQuote\fR. .SS "Range" .IX Subsection "Range" Example: .PP .Vb 3 \& my $parsed = $imap\->parse_headers( \& $imap\->Range( $imap\->messages ), "Date", "Subject" \& ); .Ve .PP The \fBRange\fR method will condense a list of message sequence numbers or message \s-1UID\s0's into the most compact format supported by \s-1RFC3501.\s0 It accepts one or more arguments, each of which can be: .IP "a) a message number," 4 .IX Item "a) a message number," .PD 0 .IP "b) a comma-separated list of message numbers," 4 .IX Item "b) a comma-separated list of message numbers," .ie n .IP "c) a colon-separated range of message numbers (i.e. ""$begin:$end"")" 4 .el .IP "c) a colon-separated range of message numbers (i.e. ``$begin:$end'')" 4 .IX Item "c) a colon-separated range of message numbers (i.e. $begin:$end)" .IP "d) a combination of messages and message ranges, separated by commas (i.e. 1,3,5:8,10), or" 4 .IX Item "d) a combination of messages and message ranges, separated by commas (i.e. 1,3,5:8,10), or" .IP "e) a reference to an array whose elements are like \fIa)\fR through \fId)\fR." 4 .IX Item "e) a reference to an array whose elements are like a) through d)." .PD .PP The \fBRange\fR method returns a Mail::IMAPClient::MessageSet object. The object uses overload and if treated as a string it will act like a string. This means you can ignore its objectivity and just treat it like a string whose value is your message set expressed in compact format. .PP This method provides an easy way to add or remove messages from a message set. .PP For more information see Mail::IMAPClient::MessageSet. .SS "Rfc3501_date" .IX Subsection "Rfc3501_date" Example: .PP .Vb 3 \& $Rfc3501_date = $imap\->Rfc3501_date($seconds); \& # or: \& $Rfc3501_date = Mail::IMAPClient\->Rfc3501_date($seconds); .Ve .PP The \fBRfc3501_date\fR method accepts one input argument, a number of seconds since the epoch date. It returns an \s-1RFC3501\s0 compliant date string for that date (as required in date-related arguments to \s-1SEARCH,\s0 such as \*(L"since\*(R", \*(L"before\*(R", etc.). .SS "Rfc3501_datetime" .IX Subsection "Rfc3501_datetime" Example: .PP .Vb 3 \& $date = $imap\->Rfc3501_datetime($seconds); \& # or: \& $date = Mail::IMAPClient\->Rfc3501_datetime($seconds); .Ve .PP The \fBRfc3501_datetime\fR method accepts one or two arguments: a obligatory timestamp and an optional zone. The zone shall be formatted as \f(CW\*(C`[+\-]\ed{4}\*(C'\fR, and defaults to \f(CW+0000\fR. The timestamp follows the definition of the output of the platforms specific \f(CW\*(C`time\*(C'\fR, usually in seconds since Jan 1st 1970. However, you have to correct the number yourself for the zone. .SS "Rfc822_date" .IX Subsection "Rfc822_date" Example: .PP .Vb 3 \& $Rfc822_date = $imap\->Rfc822_date($seconds); \& # or: \& $Rfc822_date = Mail::IMAPClient\->Rfc822_date($seconds); .Ve .PP The \fBRfc822_date\fR method accepts one input argument, a number of seconds since the epoch date. It returns an \s-1RFC822\s0 compliant date string for that date (without the 'Date:' prefix). Useful for putting dates in message strings before calling \*(L"append\*(R", \*(L"search\*(R", etc. .SS "Strip_cr" .IX Subsection "Strip_cr" Examples: .PP .Vb 7 \& my $stripped = $imap\->Strip_cr($string); \& # or: \& my @list = $imap\->some_imap_method; \& @list = $imap\->Strip_cr(@list); \& # or: \& my $list = [ $imap\->some_imap_method ]; # returns an array ref \& $list = $imap\->Strip_cr($list); .Ve .PP The \fBStrip_cr\fR method strips carriage returns from input and returns the new string to the caller. This method accepts one or more lines of text as arguments, and returns those lines with all <\s-1CR\s0><\s-1LF\s0> sequences changed to <\s-1LF\s0>. Any input argument with no carriage returns is returned unchanged. If the first argument (not counting the class name or object reference) is an array reference, then members of that array are processed as above and subsequent arguments are ignored. If the method is called in scalar context then an array reference is returned instead of an array of results. .PP \&\s-1NOTE:\s0 \fBStrip_cr\fR does not remove new line characters. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" Object methods must be invoked against objects created via the \*(L"new\*(R" method and cannot be invoked as class methods. .PP There object methods typically fall into one of two categories. There are mailbox methods which participate in the \s-1IMAP\s0 session's conversation (i.e. they issue \s-1IMAP\s0 client commands) and object control methods which do not result in \s-1IMAP\s0 commands but which may affect later commands or provide details of previous ones. .PP This object control methods can be further broken down into two types, Parameter accessor methods, which affect the behavior of future mailbox methods, and \*(L"Status Methods\*(R", which report on the affects of previous mailbox methods. .PP Methods that do not result in new \s-1IMAP\s0 client commands being issued (such as the \*(L"Transaction\*(R", \*(L"Status\*(R", and \*(L"History\*(R" methods) all begin with an uppercase letter, to distinguish them from methods that do correspond to \s-1IMAP\s0 client commands. Class methods and eponymous parameter methods likewise begin with an uppercase letter because they also do not correspond to an \s-1IMAP\s0 client command. .PP As a general rule, mailbox control methods return \f(CW\*(C`undef\*(C'\fR on failure and something besides \f(CW\*(C`undef\*(C'\fR when they succeed. This rule is modified in the case of methods that return search results. When called in a list context, searches that do not find matching results return an empty list. When called in a scalar context, searches with no hits return 'undef' instead of an array reference. If you want to know why you received no hits, you should check \*(L"LastError\*(R" or \&\f(CW$@\fR, which will be empty if the search was successful but had no matching results but populated with an error message if the search encountered a problem (such as invalid parameters). .PP A number of \s-1IMAP\s0 commands do not have corresponding Mail::IMAPClient methods. Patches are welcome. In the pre\-2.99 releases of this module, they were automatically created (\s-1AUTOLOAD\s0), but that was very error-prone and stalled the progress of this module. .SH "Mailbox Control Methods" .IX Header "Mailbox Control Methods" .SS "append" .IX Subsection "append" Example: .PP .Vb 2 \& my $uid_or_true = $imap\->append( $folder, $msgtext ) \& or die "Could not append: ", $imap\->LastError; .Ve .PP \&\s-1WARNING:\s0 This method may be deprecated in the future, consider using \&\*(L"append_string\*(R" instead of this method. .PP The \fBappend\fR method adds a message to the specified folder. See \&\*(L"append_string\*(R" for details as it is effectively an alias for that method. .PP \&\s-1DEPRECATED BEHAVIOR:\s0 Additional arguments are added to the message text, separated with <\s-1CR\s0><\s-1LF\s0>. .SS "append_string" .IX Subsection "append_string" Example: .PP .Vb 3 \& # brackets indicate optional arguments (not array refs): \& my $uidort = $imap\->append_string( $folder, $msgtext [,$flags [,$date ] ] ) \& or die "Could not append_string: ", $imap\->LastError; .Ve .PP Arguments: .ie n .IP "$folder" 4 .el .IP "\f(CW$folder\fR" 4 .IX Item "$folder" the name of the folder to append the message to .ie n .IP "$msgtext" 4 .el .IP "\f(CW$msgtext\fR" 4 .IX Item "$msgtext" the message text (including headers) of the message .ie n .IP "$flags" 4 .el .IP "\f(CW$flags\fR" 4 .IX Item "$flags" An optional list of flags to set. The list must be specified as a space-separated list of flags, including any backslashes that may be necessary and optionally enclosed by parenthesis. .ie n .IP "$date" 4 .el .IP "\f(CW$date\fR" 4 .IX Item "$date" An optional \s-1RFC3501\s0 date argument to set as the internal date. It should be in the format described for \fIdate_time\fR fields in \s-1RFC3501,\s0 i.e. \*(L"dd-Mon-yyyy hh:mm:ss +0000\*(R". .Sp If you want to specify a date/time but you don't want any flags then specify \fIundef\fR as the third ($flags) argument. .PP Returns: .IP "error: undef" 4 .IX Item "error: undef" On error, undef can be returned regardless of \s-1LIST/SCALAR\s0 context. Check \*(L"LastError\*(R" for details. .ie n .IP "success: \s-1UID\s0 or $imap" 4 .el .IP "success: \s-1UID\s0 or \f(CW$imap\fR" 4 .IX Item "success: UID or $imap" With \s-1UIDPLUS\s0 the \s-1UID\s0 of the new message is returned otherwise a true value (currently \f(CW$self\fR) is returned. .PP To protect against \*(L"bare newlines\*(R", \fBappend\fR will insert a carriage return before any newline that is \*(L"bare\*(R". .SS "append_file" .IX Subsection "append_file" Example: .PP .Vb 5 \& my $new_msg_uid = $imap\->append_file( \& $folder, \& $file, \& [ undef, $flags, $date ] # optional \& ) or die "Could not append_file: ", $imap\->LastError; .Ve .PP The \fBappend_file\fR method adds a message to the specified folder. Note: The brackets in the example indicate optional arguments; they do not mean that the argument should be an array reference. .PP Arguments: .ie n .IP "$folder" 4 .el .IP "\f(CW$folder\fR" 4 .IX Item "$folder" the name of the folder to append the message to .ie n .IP "$file" 4 .el .IP "\f(CW$file\fR" 4 .IX Item "$file" a filename, filehandle or \s-1SCALAR\s0 reference which holds an RFC822\-formatted message .IP "undef" 4 .IX Item "undef" a deprecated argument used as a place holder for backwards compatibility .ie n .IP "$flags" 4 .el .IP "\f(CW$flags\fR" 4 .IX Item "$flags" The optional argument is handled the same as append_string. .ie n .IP "$date" 4 .el .IP "\f(CW$date\fR" 4 .IX Item "$date" The optional argument is handled the same as append_string (\s-1RFC3501\s0 date), with the exception that if \f(CW$date\fR is \*(L"1\*(R" (one) then the modification time (mtime) of the file will be used. .PP Returns: .IP "error: undef" 4 .IX Item "error: undef" On error, undef can be returned regardless of \s-1LIST/SCALAR\s0 context. Check \*(L"LastError\*(R" for details. .ie n .IP "success: \s-1UID\s0 or $imap" 4 .el .IP "success: \s-1UID\s0 or \f(CW$imap\fR" 4 .IX Item "success: UID or $imap" With \s-1UIDPLUS\s0 the \s-1UID\s0 of the new message is returned otherwise a true value (currently \f(CW$self\fR) is returned. .PP To protect against \*(L"bare newlines\*(R", \fBappend_file\fR will insert a carriage return before any newline that is \*(L"bare\*(R". .PP The \fBappend_file\fR method provides a mechanism for allowing large messages to be appended without holding the whole file in memory. .PP Version note: In 2.x an optional third argument to use for \&\f(CW\*(C`input_record_separator\*(C'\fR was allowed, however this argument is ignored/not supported as of 3.x. .SS "authenticate" .IX Subsection "authenticate" Example: .PP .Vb 2 \& $imap\->authenticate( $authentication_mechanism, $coderef ) \& or die "Could not authenticate: ", $imap\->LastError; .Ve .PP This method implements the \s-1AUTHENTICATE IMAP\s0 client command. It can be called directly or may be called by \*(L"login\*(R" if the \&\*(L"Authmechanism\*(R" parameter is set to anything except '\s-1LOGIN\s0'. .PP The \fBauthenticate\fR method accepts two arguments, an authentication type to be used (ie \s-1CRAM\-MD5\s0) and a code or subroutine reference to execute to obtain a response. The \fBauthenticate\fR method assumes that the authentication type specified in the first argument follows a challenge-response flow. The \fBauthenticate\fR method issues the \s-1IMAP\s0 Client \s-1AUTHENTICATE\s0 command and receives a challenge from the server. That challenge (minus any tag prefix or enclosing '+' characters but still in the original base64 encoding) is passed as the only argument to the code or subroutine referenced in the second argument. The return value from the 2nd argument's code is written to the server as is, except that a <\s-1CR\s0><\s-1LF\s0> sequence is appended if necessary. .PP If one or both of the arguments are not specified in the call to \&\fBauthenticate\fR but their corresponding parameters have been set (\*(L"Authmechanism\*(R" and \*(L"Authcallback\*(R", respectively) then the parameter values are used. Arguments provided to the method call however will override parameter settings. .PP If you do not specify a second argument and you have not set the \&\*(L"Authcallback\*(R" parameter, then the first argument must be one of the authentication mechanisms for which Mail::IMAPClient has built in support. .PP See also the \*(L"login\*(R" method, which is the simplest form of authentication defined by \s-1RFC3501.\s0 .SS "before" .IX Subsection "before" Example: .PP .Vb 2 \& my @msgs = $imap\->before($Rfc3501_date) \& or warn "No messages found before $Rfc3501_date.\en"; .Ve .PP The \fBbefore\fR method works just like the \*(L"since\*(R" method, below, except it returns a list of messages whose internal system dates are before the date supplied as the argument to the \fBbefore\fR method. .SS "body_string" .IX Subsection "body_string" Example: .PP .Vb 2 \& my $string = $imap\->body_string($msgId) \& or die "body_string failed: ", $imap\->LastError; .Ve .PP The \fBbody_string\fR method accepts a message sequence number (or a message \s-1UID,\s0 if the \*(L"Uid\*(R" parameter is set to true) as an argument and returns the message body as a string. The returned value contains the entire message in one scalar variable, without the message headers. .SS "bodypart_string" .IX Subsection "bodypart_string" Example: .PP .Vb 3 \& my $string = $imap\->bodypart_string( \& $msgid, $part_number, $length, $offset \& ) or die "Could not get bodypart string: ", $imap\->LastError; .Ve .PP The \fBbodypart_string\fR method accepts a message sequence number (or a message \s-1UID,\s0 if the \*(L"Uid\*(R" parameter is set to true) and a body part as arguments and returns the message part as a string. The returned value contains the entire message part (or, optionally, a portion of the part) in one scalar variable. .PP If an optional third argument is provided, that argument is the number of bytes to fetch. (The default is the whole message part.) If an optional fourth argument is provided then that fourth argument is the offset into the part at which the fetch should begin. The default is offset zero, or the beginning of the message part. .PP If you specify an offset without specifying a length then the offset will be ignored and the entire part will be returned. .PP \&\fBbodypart_string\fR will return \f(CW\*(C`undef\*(C'\fR if it encounters an error. .SS "capability" .IX Subsection "capability" Example: .PP .Vb 2 \& my $features = $imap\->capability \& or die "Could not determine capability: ", $imap\->LastError; .Ve .PP The \fBcapability\fR method returns an array (or arrayref in scalar context) of capabilities as returned by the \s-1CAPABILITY IMAP\s0 client command. If the \s-1CAPABILITY IMAP\s0 client command fails for any reason then the \fBcapability\fR method will return \f(CW\*(C`undef\*(C'\fR. Supported capabilities are cached by the client, however, this cache is deleted after a connection is set to \fIAuthenticated\fR and when \*(L"starttls\*(R" is called. .PP See also \*(L"has_capability\*(R". .SS "close" .IX Subsection "close" Example: .PP .Vb 1 \& $imap\->close or die "Could not close: $@\en"; .Ve .PP The \fBclose\fR method is used to close the currently selected folder via the \s-1CLOSE IMAP\s0 client command. According to \s-1RFC3501,\s0 the \s-1CLOSE\s0 command performs an implicit \s-1EXPUNGE,\s0 which means that any messages that are flagged as \fI\eDeleted\fR (i.e. with the \*(L"delete_message\*(R" method) will now be deleted. If you haven't deleted any messages then \&\fBclose\fR can be thought of as an \*(L"unselect\*(R". .PP Note: this closes the currently selected folder, not the \s-1IMAP\s0 session. .PP See also \*(L"delete_message\*(R", \*(L"expunge\*(R", and \s-1RFC3501.\s0 .SS "compress" .IX Subsection "compress" Example: .PP .Vb 1 \& $imap\->compress or die "Could not enable RFC4978 compression: $@\en"; .Ve .PP The \fBcompress\fR method accepts no arguments. This method is used to instruct the server to use the \s-1DEFLATE\s0 (\s-1RFC1951\s0) compression extension. See the \*(L"Compress\*(R" attribute for how to specify arguments for use during the initialization process. .PP Version note: method added in Mail::IMAPClient 3.30 .SS "connect" .IX Subsection "connect" Example: .PP .Vb 1 \& $imap\->connect or die "Could not connect: $@\en"; .Ve .PP The \fBconnect\fR method connects an imap object to the server. It returns \f(CW\*(C`undef\*(C'\fR if it fails to connect for any reason. If values are available for the \*(L"User\*(R" and \*(L"Password\*(R" parameters at the time that \fBconnect\fR is invoked, then \fBconnect\fR will call the \*(L"login\*(R" method after connecting and return the result of the \*(L"login\*(R" method to \fBconnect\fR's caller. If either or both of the \*(L"User\*(R" and \&\*(L"Password\*(R" parameters are unavailable but the connection to the server succeeds then \fBconnect\fR returns a pointer to the IMAPClient object. .PP The \*(L"Server\*(R" parameter must be set (either during \*(L"new\*(R" method invocation or via the \*(L"Server\*(R" object method) before invoking \&\fBconnect\fR. When the parameter is an absolute file path, an \s-1UNIX\s0 socket will get opened. If the \*(L"Server\*(R" parameter is supplied to the \*(L"new\*(R" method then \fBconnect\fR is implicitly called during object construction. .PP The \fBconnect\fR method sets the state of the object to \f(CW\*(C`Connected\*(C'\fR if it successfully connects to the server. It returns \f(CW\*(C`undef\*(C'\fR on failure. .SS "copy" .IX Subsection "copy" Example: .PP .Vb 3 \& # Here brackets indicate optional arguments: \& my $uidList = $imap\->copy($folder, $msg_1 [ , ... , $msg_n ]) \& or die "Could not copy: $@\en"; .Ve .PP Or: .PP .Vb 3 \& # Now brackets indicate an array ref! \& my $uidList = $imap\->copy($folder, [ $msg_1, ... , $msg_n ]) \& or die "Could not copy: $@\en"; .Ve .PP The \fBcopy\fR method requires a folder name as the first argument, and a list of one or more messages sequence numbers (or messages \s-1UID\s0's, if the \fI\s-1UID\s0\fR parameter is set to a true value). The message sequence numbers or \s-1UID\s0's should refer to messages in the currently selected folder. Those messages will be copied into the folder named in the first argument. .PP The \fBcopy\fR method returns \f(CW\*(C`undef\*(C'\fR on failure and a true value if successful. If the server to which the current Mail::IMAPClient object is connected supports the \s-1UIDPLUS\s0 capability then the true value returned by \fBcopy\fR will be a comma separated list of \s-1UID\s0's, which are the \s-1UID\s0's of the newly copied messages in the target folder. .SS "create" .IX Subsection "create" Example: .PP .Vb 2 \& $imap\->create($new_folder) \& or die "Could not create $new_folder: $@\en"; .Ve .PP The \fBcreate\fR method accepts one argument, the name of a folder (or what \s-1RFC3501\s0 calls a \*(L"mailbox\*(R") to create. If you specify additional arguments to the \fBcreate\fR method and your server allows additional arguments to the \s-1CREATE IMAP\s0 client command then the extra argument(s) will be passed to your server. .PP If you specify additional arguments to the \fBcreate\fR method and your server does not allow additional arguments to the \s-1CREATE IMAP\s0 client command then the extra argument(s) will still be passed to your server and the create will fail. .PP \&\fBcreate\fR returns a true value on success and \f(CW\*(C`undef\*(C'\fR on failure. .SS "date" .IX Subsection "date" Example: .PP .Vb 1 \& my $date = $imap\->date($msg); .Ve .PP The \fBdate\fR method accepts one argument, a message sequence number (or a message \s-1UID\s0 if the \*(L"Uid\*(R" parameter is set to a true value). It returns the date of message as specified in the message's \s-1RFC822\s0 \&\*(L"Date: \*(R" header, without the \*(L"Date: \*(R" prefix. .PP The \fBdate\fR method is a short-cut for: .PP .Vb 1 \& my $date = $imap\->get_header($msg,"Date"); .Ve .SS "delete" .IX Subsection "delete" Example: .PP .Vb 1 \& $imap\->delete($folder) or die "Could not delete $folder: $@\en"; .Ve .PP The \fBdelete\fR method accepts a single argument, the name of a folder to delete. It returns a true value on success and \f(CW\*(C`undef\*(C'\fR on failure. .SS "deleteacl" .IX Subsection "deleteacl" Example: .PP .Vb 2 \& $imap\->deleteacl( $folder, $userid ) \& or die "Could not delete acl: $@\en"; .Ve .PP The \fBdeleteacl\fR method accepts two input arguments, a folder name, a user id (or authentication identifier, to use the terminology of \&\s-1RFC2086\s0). See \s-1RFC2086\s0 for more information. (This is somewhat experimental and its implementation may change.) .SS "delete_message" .IX Subsection "delete_message" Example: .PP .Vb 3 \& my @msgs = $imap\->seen; \& scalar(@msgs) and $imap\->delete_message(\e@msgs) \& or die "Could not delete_message: $@\en"; .Ve .PP The above could also be rewritten like this: .PP .Vb 2 \& # scalar context returns array ref \& my $msgs = scalar($imap\->seen); \& \& scalar(@$msgs) and $imap\->delete_message($msgs) \& or die "Could not delete_message: $@\en"; .Ve .PP Or, as a one-liner: .PP .Vb 4 \& $imap\->delete_message( scalar($imap\->seen) ) \& or warn "Could not delete_message: $@\en"; \& # just give warning in case failure is \& # due to having no \*(Aqseen\*(Aq msgs in the 1st place! .Ve .PP The \fBdelete_message\fR method accepts a list of arguments. If the \&\*(L"Uid\*(R" parameter is not set to a true value, then each item in the list should be either: .IP "\(bu" 4 a message sequence number, .IP "\(bu" 4 a comma-separated list of message sequence numbers, .IP "\(bu" 4 a reference to an array of message sequence numbers, or .PP If the \*(L"Uid\*(R" parameter is set to a true value, then each item in the list should be either: .IP "\(bu" 4 a message \s-1UID,\s0 .IP "\(bu" 4 a comma-separated list of \s-1UID\s0's, or .IP "\(bu" 4 a reference to an array of message \s-1UID\s0's. .PP The messages identified by the sequence numbers or \s-1UID\s0's will be deleted. If successful, \fBdelete_message\fR returns the number of messages it was told to delete. However, since the delete is done by issuing the \fI+FLAGS.SILENT\fR option of the \s-1STORE IMAP\s0 client command, there is no guarantee that the delete was successful for every message. In this manner the \fBdelete_message\fR method sacrifices accuracy for speed. Generally, though, if a single message in a list of messages fails to be deleted it's because it was already deleted, which is what you wanted anyway so why worry about it? If there is a more severe error, i.e. the server replies \*(L"\s-1NO\*(R", \*(L"BAD\*(R",\s0 or, banish the thought, \*(L"\s-1BYE\*(R",\s0 then \fBdelete_message\fR will return \f(CW\*(C`undef\*(C'\fR. .PP If you must have guaranteed results then use the \s-1IMAP STORE\s0 client command (via the default method) and use the +FLAGS (\eDeleted) option, and then parse your results manually. .PP Eg: .PP .Vb 3 \& $imap\->store( $msg_id, \*(Aq+FLAGS (\eDeleted)\*(Aq ); \& my @results = $imap\->History( $imap\->Transaction ); \& ... # code to parse output goes here .Ve .PP (Frankly I see no reason to bother with any of that; if a message doesn't get deleted it's almost always because it's already not there, which is what you want anyway. But 'your mileage may vary' and all that.) .PP The IMAPClient object must be in \f(CW\*(C`Selected\*(C'\fR status to use the \&\fBdelete_message\fR method. .PP \&\fB\s-1NOTE\s0\fR: All the messages identified in the input argument(s) must be in the currently selected folder. Failure to comply with this requirement will almost certainly result in the wrong message(s) being deleted. .PP \&\fB\s-1ADDITIONAL NOTE\s0\fR: In the grand tradition of the \s-1IMAP\s0 protocol, deleting a message doesn't actually delete the message. Really. If you want to make sure the message has been deleted, you need to expunge the folder (via the \*(L"expunge\*(R" method, which is implemented via the default method). Or at least \*(L"close\*(R" it. This is generally considered a feature, since after deleting a message, you can change your mind and undelete it at any time before your \*(L"expunge\*(R" or \&\*(L"close\*(R". .PP See also: the \*(L"delete\*(R" method, to delete a folder, the \*(L"expunge\*(R" method, to expunge a folder, the \*(L"restore_message\*(R" method to undelete a message, and the \*(L"close\*(R" method (implemented here via the default method) to close a folder. Oh, and don't forget about \s-1RFC3501.\s0 .SS "deny_seeing" .IX Subsection "deny_seeing" Example: .PP .Vb 4 \& # Reset all read msgs to unread \& # (produces error if there are no seen msgs): \& $imap\->deny_seeing( scalar($imap\->seen) ) \& or die "Could not deny_seeing: $@\en"; .Ve .PP The \fBdeny_seeing\fR method accepts a list of one or more message sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then unsets the \&\*(L"\eSeen\*(R" flag for those messages (so that you can \*(L"deny\*(R" that you ever saw them). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers should be unique message id's. .PP Note that specifying \f(CW\*(C`$imap\->deny_seeing(@msgs)\*(C'\fR is just a shortcut for specifying \f(CW\*(C`$imap\->unset_flag("Seen",@msgs)\*(C'\fR. .SS "disconnect" .IX Subsection "disconnect" Example: .PP .Vb 1 \& $imap\->disconnect or warn "Could not logout: $@\en"; .Ve .PP This method calls \*(L"logout\*(R", see \*(L"logout\*(R" for details. .SS "done" .IX Subsection "done" Example: .PP .Vb 5 \& my $tag = $imap\->idle or warn "idle failed: $@\en"; \& doSomethingA(); \& my $idlemsgs = $imap\->idle_data() or warn "idle_data error: $@\en"; \& doSomethingB(); \& my $results = $imap\->done($tag) or warn "Error from done: $@\en"; .Ve .PP The \fBdone\fR method tells the \s-1IMAP\s0 server to terminate the \s-1IDLE\s0 command. The only argument is the \fItag\fR (identifier) received from the previous call to \*(L"idle\*(R". If \fItag\fR is not specified a default \&\fItag\fR based on the \fBCount\fR attribute is assumed to be the \fItag\fR to look for in the response from the server. .PP If an invalid \fItag\fR is specified, or the default \fItag\fR is wrong, then \fBdone\fR will hang indefinitely or until a timeout occurs. .PP If \fBdone\fR is called when an \*(L"idle\*(R" command is not active then the server will likely respond with an error like \fI* \s-1BAD\s0 Invalid tag\fR. .PP On failure is returned and \*(L"LastError\*(R" is set. .PP See also \*(L"idle\*(R", \*(L"idle_data\*(R" and \*(L"Results\*(R". .SS "examine" .IX Subsection "examine" Example: .PP .Vb 1 \& $imap\->examine($folder) or die "Could not examine: $@\en"; .Ve .PP The \fBexamine\fR method selects a folder in read-only mode and changes the object's state to \*(L"Selected\*(R". The folder selected via the \&\fBexamine\fR method can be examined but no changes can be made unless it is first selected via the \*(L"select\*(R" method. .PP The \fBexamine\fR method accepts one argument, which is the name of the folder to select. .SS "exists" .IX Subsection "exists" Example: .PP .Vb 1 \& $imap\->exists($folder) or warn "$folder not found: $@\en"; .Ve .PP Accepts one argument, a folder name. Returns true if the folder exists or false if it does not exist. .SS "expunge" .IX Subsection "expunge" Example: .PP .Vb 1 \& $imap\->expunge($folder) or die "Could not expunge: $@\en"; .Ve .PP The \fBexpunge\fR method accepts one optional argument, a folder name. It expunges the folder specified as the argument, or the currently selected folder (if any) when no argument is supplied. .PP Although \s-1RFC3501\s0 does not permit optional arguments (like a folder name) to the \s-1EXPUNGE\s0 client command, the \*(L"expunge\*(R" method does. Note: expunging a folder deletes the messages that have the \eDeleted flag set (i.e. messages flagged via \*(L"delete_message\*(R"). .PP See also the \*(L"close\*(R" method, which \*(L"deselects\*(R" as well as expunges. .SS "fetch" .IX Subsection "fetch" Usage: .PP .Vb 1 \& $imap\->fetch( [$seq_set|ALL], @msg_data_items ) .Ve .PP Example: .PP .Vb 1 \& my $output = $imap\->fetch(@args) or die "Could not fetch: $@\en"; .Ve .PP The \fBfetch\fR method implements the \s-1FETCH IMAP\s0 client command. It accepts a list of arguments, which will be converted into a space-delimited list of arguments to the \s-1FETCH IMAP\s0 client command. If no arguments are supplied then \fBfetch\fR does a \s-1FETCH ALL.\s0 If the \&\*(L"Uid\*(R" parameter is set to a true value then the first argument will be treated as a \s-1UID\s0 or list of \s-1UID\s0's, which means that the \s-1UID FETCH IMAP\s0 client command will be run instead of \s-1FETCH.\s0 (It would really be a good idea at this point to review \s-1RFC3501.\s0) .PP If called in array context, \fBfetch\fR will return an array of output lines. The output lines will be returned just as they were received from the server, so your script will have to be prepared to parse out the bits you want. The only exception to this is literal strings, which will be inserted into the output line at the point at which they were encountered (without the {nnn} literal field indicator). See \&\s-1RFC3501\s0 for a description of literal fields. .PP If \fBfetch\fR is called in a scalar context, then a reference to an array (as described above) is returned instead of the entire array. .PP \&\fBfetch\fR returns \f(CW\*(C`undef\*(C'\fR on failure. Inspect \*(L"LastError\*(R" or \f(CW$@\fR for an explanation of your error. .SS "fetch_hash" .IX Subsection "fetch_hash" Usage: .PP .Vb 1 \& $imap\->fetch_hash( [$seq_set|ALL], @msg_data_items, [\e%msg_by_ids] ) .Ve .PP Examples: .PP .Vb 1 \& my $hashref = $imap\->fetch_hash("RFC822.SIZE"); \& \& OR \& \& my $hashref = {}; \& $imap\->fetch_hash( "RFC822.SIZE", $hashref ); \& print "Msg #$_ is $hashref\->{$_}\->{\*(AqRFC822.SIZE\*(Aq} bytes\en" for (keys %$hashref); .Ve .PP The \fBfetch_hash\fR method accepts a list of message attributes to be fetched (as described in \s-1RFC3501\s0). It returns a hash whose keys are all the messages in the currently selected folder and whose values are key-value pairs of fetch keywords and the message's value for that keyword (see sample output below). .PP If \fBfetch_hash\fR is called in scalar context, it returns a reference to the hash instead of the hash itself. If the last argument is a hash reference, then that hash reference will be used as the place where results are stored (and that reference will be returned upon successful completion). If the last argument is not a reference then it will be treated as one of the \s-1FETCH\s0 attributes and a new hash will be created and returned (either by value or by reference, depending on the context in which \fBfetch_hash\fR was called). .PP For example, if you have a folder with 3 messages and want the size and internal date for each of them, you could do the following: .PP .Vb 10 \& use Mail::IMAPClient; \& use Data::Dumper; \& # ... other code goes here \& $imap\->select($folder); \& my $hash = $imap\->fetch_hash( "RFC822.SIZE", "INTERNALDATE" ); \& # (Same as: \& # my $hash = $imap\->fetch_hash("RFC822.SIZE"); \& # $imap\->fetch_hash( "INTERNALDATE", $hash ); \& # ). \& print Data::Dumper\->Dumpxs( [$hash], [\*(Aq$hash\*(Aq] ); .Ve .PP This would result in Data::Dumper output similar to the following: .PP .Vb 10 \& $hash = { \& \*(Aq1\*(Aq => { \& \*(AqINTERNALDATE\*(Aq => \*(Aq21\-Sep\-2002 18:21:56 +0000\*(Aq, \& \*(AqRFC822.SIZE\*(Aq => \*(Aq1586\*(Aq, \& }, \& \*(Aq2\*(Aq => { \& \*(AqINTERNALDATE\*(Aq => \*(Aq22\-Sep\-2002 11:29:42 +0000\*(Aq, \& \*(AqRFC822.SIZE\*(Aq => \*(Aq1945\*(Aq, \& }, \& \*(Aq3\*(Aq => { \& \*(AqINTERNALDATE\*(Aq => \*(Aq23\-Sep\-2002 09:16:51 +0000\*(Aq, \& \*(AqRFC822.SIZE\*(Aq => \*(Aq134314\*(Aq, \& } \& }; .Ve .PP By itself this method may be useful for tasks like obtaining the size of every message in a folder. It issues one command and receives one (possibly long!) response from the server. .PP If the fetch request causes the server to return data in a parenthesized list, the data within the parenthesized list may be escaped via the \fBEscape()\fR method. Use the \fBUnescape()\fR method to get the raw values back in this case. .SS "flags" .IX Subsection "flags" Example: .PP .Vb 2 \& my $flags = $imap\->flags($msgid) \& or die "flags failed: $@\en"; .Ve .PP The \fBflags\fR method implements the \s-1FETCH IMAP\s0 client command to list a single message's flags. It accepts one argument, a message sequence number (or a message \s-1UID,\s0 if the \*(L"Uid\*(R" parameter is true), and returns an array (or a reference to an array, if called in scalar context) listing the flags that have been set. Flag names are provided with leading backslashes. .PP As of version 1.11, you can supply either a list of message id's or a reference to an array of message id's (which means either sequence number, if the Uid parameter is false, or message \s-1UID\s0's, if the Uid parameter is true) instead of supplying a single message sequence number or \s-1UID.\s0 If you do, then the return value will not be an array or array reference; instead, it will be a hash reference, with each key being a message sequence number (or \s-1UID\s0) and each value being a reference to an array of flags set for that message. .PP For example, if you want to display the flags for every message in the folder where you store e\-mail related to your plans for world domination, you could do something like this: .PP .Vb 7 \& use Mail::IMAPClient; \& my $imap = Mail::IMAPClient\->new( \& Server => $imaphost, \& User => $login, \& Password => $pass, \& Uid => 1, # optional \& ); \& \& $imap\->select("World Domination"); \& # get the flags for every message in my \*(AqWorld Domination\*(Aq folder \& $flaghash = $imap\->flags( scalar( $imap\->search("ALL") ) ); \& \& # pump through sorted hash keys to print results: \& for my $k ( sort { $flaghash\->{$a} <=> $flaghash\->{$b} } keys %$flaghash ) { \& # print: Message 1: \eFlag1, \eFlag2, \eFlag3 \& print "Message $k:\et", join( ", ", @{$flaghash\->{$k}} ), "\en"; \& } .Ve .SS "folders" .IX Subsection "folders" Example: .PP .Vb 1 \& $imap\->folders or die "Could not list folders: $@\en"; .Ve .PP The \fBfolders\fR method returns an array listing the available folders. It will only be successful if the object is in the \fIAuthenticated\fR or \&\fISelected\fR states. .PP The \fBfolders\fR method accepts one optional argument, which is a prefix. If a prefix is supplied to the \fBfolders\fR method, then only folders beginning with the prefix will be returned. .PP For example: .PP .Vb 9 \& print join( ", ", $imap\->folders ), ".\en"; \& # Prints: \& # INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software. \& print join( ", ", $imap\->folders("Projects") ), ".\en"; \& # Prints: \& # Projects, Projects/Completed, Projects/Ongoing, Projects Software. \& print join( ", ", $imap\->folders("Projects" . $imap\->separator) ), ".\en"; \& # Prints: \& # Projects/Completed, Projects/Ongoing .Ve .PP Please note that documentation previously suggested that if you just want to list a folder's subfolders (and not the folder itself), then you need to include the hierarchy separator character (as returned by the \*(L"separator\*(R" method). However, this does not match the behavior of the existing implementation, so you will need to manually exclude the parent folder from the results. .SS "folders_hash" .IX Subsection "folders_hash" .Vb 2 \& my @fhashes = $imap\->folders_hash \& or die "Could not get list of folder hashes.\en"; .Ve .PP The \fBfolders_hash\fR method accepts one optional argument, which is a prefix. If a prefix is supplied to the \fBfolders_hash\fR method, then only folders beginning with the prefix will be returned. .PP An array(ref) of hashes is returned that contain information about the requested folders. Each hash contains three keys (name, attrs, delim) and looks like the following: .PP .Vb 5 \& { \& name => \*(AqMail/Box/Name\*(Aq, \& attrs => [ \*(Aq\eMarked\*(Aq, \*(Aq\eHasNoChildren\*(Aq ], \& delim => \*(Aq/\*(Aq, \& } .Ve .PP \&\s-1IMAP\s0 servers implementing \s-1RFC6154\s0 return attributes to be used to identify special-use mailboxes (folders). .PP .Vb 6 \& my $sattr_re = /\eA\e\e(?:All|Archive|Drafts|Flagged|Junk|Sent|Trash)\eZ/; \& foreach my $fhash (@fhashes) { \& next unless defined $fhash\->{name}; \& my @special = grep { $sattr_re } @{ $fhash\->{attrs} }; \& print("special: $fhash\->{name} : @special\en") if (@special); \& } .Ve .PP Version note: method added in Mail::IMAPClient 3.34 .SS "xlist_folders (\s-1DEPRECATED\s0)" .IX Subsection "xlist_folders (DEPRECATED)" This method is deprecated as of version 3.34. Please use folders_hash instead. See \s-1RFC6154\s0 for attributes to be used to identify special-use mailboxes (folders). .PP Example: .PP .Vb 2 \& my $xlist = $imap\->xlist_folders \& or die "Could not get xlist folders.\en"; .Ve .PP \&\s-1IMAP\s0 servers implementing the \s-1XLIST\s0 extension (such as Gmail) designate particular folders to be used for particular functions. This is useful in the case where you want to know which folder should be used for Trash when the actual folder name can't be predicted (e.g. in the case of Gmail, the folder names change depending on the user's locale settings). .PP The \fBxlist_folders\fR method returns a hash listing any \*(L"xlist\*(R" folder names, with the values listing the actual folders that should be used for those names. For example, using this method with a Gmail user using the English (\s-1US\s0) locale might give this output from Data::Dumper: .PP .Vb 9 \& $VAR1 = { \& \*(AqInbox\*(Aq => \*(AqInbox\*(Aq, \& \*(AqAllMail\*(Aq => \*(Aq[Gmail]/All Mail\*(Aq, \& \*(AqTrash\*(Aq => \*(Aq[Gmail]/Trash\*(Aq, \& \*(AqDrafts\*(Aq => \*(Aq[Gmail]/Drafts\*(Aq, \& \*(AqSent\*(Aq => \*(Aq[Gmail]/Sent Mail\*(Aq, \& \*(AqSpam\*(Aq => \*(Aq[Gmail]/Spam\*(Aq, \& \*(AqStarred\*(Aq => \*(Aq[Gmail]/Starred\*(Aq \& }; .Ve .PP The same list for a user using the French locale might look like this: .PP .Vb 9 \& $VAR1 = { \& \*(AqInbox\*(Aq => \*(AqBo&AO4\-te de r&AOk\-ception\*(Aq, \& \*(AqAllMail\*(Aq => \*(Aq[Gmail]/Tous les messages\*(Aq, \& \*(AqTrash\*(Aq => \*(Aq[Gmail]/Corbeille\*(Aq, \& \*(AqDrafts\*(Aq => \*(Aq[Gmail]/Brouillons\*(Aq, \& \*(AqSent\*(Aq => \*(Aq[Gmail]/Messages envoy&AOk\-s\*(Aq, \& \*(AqSpam\*(Aq => \*(Aq[Gmail]/Spam\*(Aq, \& \*(AqStarred\*(Aq => \*(Aq[Gmail]/Suivis\*(Aq \& }; .Ve .PP Mail::IMAPClient recognizes the following \*(L"xlist\*(R" folder names: .IP "Inbox" 4 .IX Item "Inbox" .PD 0 .IP "AllMail" 4 .IX Item "AllMail" .IP "Trash" 4 .IX Item "Trash" .IP "Drafts" 4 .IX Item "Drafts" .IP "Sent" 4 .IX Item "Sent" .IP "Spam" 4 .IX Item "Spam" .IP "Starred" 4 .IX Item "Starred" .PD .PP These are currently the only ones supported by Gmail. The \s-1XLIST\s0 extension is not documented, and there are no other known implementations other than Gmail, so this list is based on what Gmail provides. .PP If the server does not support the \s-1XLIST\s0 extension, this method returns undef. .PP Version note: method added in Mail::IMAPClient 3.21 .SS "has_capability" .IX Subsection "has_capability" Example: .PP .Vb 2 \& my $has_feature = $imap\->has_capability($feature) \& or die "Could not do has_capability($feature): $@\en"; .Ve .PP Returns: .ie n .IP """undef""" 4 .el .IP "\f(CWundef\fR" 4 .IX Item "undef" If the underlying \*(L"capability\*(R" calls fails then \f(CW\*(C`undef\*(C'\fR is returned. .ie n .IP """"" or ""()""" 4 .el .IP "\f(CW``''\fR or \f(CW()\fR" 4 .IX Item """"" or ()" If the server does not have the requested capability, then either an empty string (\f(CW""\fR in scalar context) or an empty list (\f(CW\*(C`()\*(C'\fR in list context) is returned. .IP "a \fItrue\fR value" 4 .IX Item "a true value" If the server has the requested capability, then a \fItrue\fR value is returned. The \fItrue\fR value depends upon the server response for the capability requested. The value will be an array reference in scalar context or an array in list context. The returned data is useful for understanding more about specific capabilities. For example, consider the following server \s-1CAPABILITY\s0 response: .Sp .Vb 1 \& * CAPABILITY IMAP4rev1 SORT SORT=DISPLAY I18NLEVEL=1 AUTH=PLAIN AUTH=XTEST .Ve .Sp Results are returned as shown by the trailing comments: .Sp .Vb 12 \& $c = $imap\->has_capability("IMAP4rev1"); # [ "IMAP4rev1" ] \& @c = $imap\->has_capability("IMAP4rev1"); # ( "IMAP4rev1" ) \& $c = $imap\->has_capability("SORT"); # [ "DISPLAY" ] \& @c = $imap\->has_capability("SORT=DISPLAY"); # ( "SORT=DISPLAY" ) \& $c = $imap\->has_capability("AUTH"); # [ "PLAIN", "XTEST" ] \& @c = $imap\->has_capability("AUTH"); # ( "PLAIN", "XTEST" ) \& $c = $imap\->has_capability("AUTH=XTEST"); # [ "AUTH=XTEST" ] \& @c = $imap\->has_capability("AUTH=XTEST"); # ( "AUTH=XTEST" ) \& $c = $imap\->has_capability("AUTH=NADA"); # \*(Aq\*(Aq \& @c = $imap\->has_capability("AUTH=NADA"); # () \& $c = $imap\->has_capability("NADA"); # \*(Aq\*(Aq \& @c = $imap\->has_capability("NADA"); # () .Ve .SS "idle" .IX Subsection "idle" Example: .PP .Vb 5 \& my $tag = $imap\->idle or warn "idle failed: $@\en"; \& doSomethingA(); \& my $idlemsgs = $imap\->idle_data() or warn "idle_data error: $@\en"; \& doSomethingB(); \& my $results = $imap\->done($tag) or warn "Error from done: $@\en"; .Ve .PP The \fBidle\fR method tells the \s-1IMAP\s0 server the client is ready to accept unsolicited mailbox update messages (on the selected folder/mailbox). This method is only valid on servers that support the \s-1IMAP IDLE\s0 extension, see \s-1RFC2177\s0 for details. .PP The \fBidle\fR method accepts no arguments and returns the \fItag\fR (identifier) that was sent by the client for this command. This tag should be supplied as the argument to \*(L"done\*(R" when ending the \s-1IDLE\s0 command. .PP On failure is returned and \*(L"LastError\*(R" is set. .PP The method \*(L"idle_data\*(R" may be used once \fBidle\fR has been successful. However, no mailbox operations may be called until the \fBidle\fR command has been terminated by calling \*(L"done\*(R". Failure to do so will result in an error and the idle command will typically be terminated by the server. .PP See also \*(L"idle_data\*(R" and \*(L"done\*(R". .SS "idle_data" .IX Subsection "idle_data" Usage: .PP .Vb 2 \& # an optional timeout in seconds may be specified \& $imap\->idle_data( [$timeout] ) .Ve .PP Example: .PP .Vb 5 \& my $tag = $imap\->idle or warn "idle failed: $@\en"; \& doSomethingA(); \& my $idlemsgs = $imap\->idle_data() or warn "idle_data error: $@\en"; \& doSomethingB(); \& my $results = $imap\->done($tag) or warn "Error from done: $@\en"; .Ve .PP The \fBidle_data\fR method can be used to accept any unsolicited mailbox update messages that have been sent by the server during an \*(L"idle\*(R" command. This method does not send any commands to the server, it simply looks for and optionally waits for data from the server and returns that data to the caller. .PP The \fBidle_data\fR method accepts an optional \f(CW$timeout\fR argument and returns an array (or an array reference if called in scalar context) with the messages from the server. .PP By default a timeout of 0 seconds is used (do not block). Internally the timeout is passed to \*(L"select\*(R" in perlfunc. The timeout controls how long the select call blocks if there are no messages waiting to be read from the server. .PP On failure is returned and \*(L"LastError\*(R" is set. .PP See also \*(L"imap\*(R" and \*(L"done\*(R". .PP Version note: method added in Mail::IMAPClient 3.23 Warning: this method is considered experimental and the interface/output may change in a future version. .SS "imap4rev1" .IX Subsection "imap4rev1" Example: .PP .Vb 1 \& $imap\->imap4rev1 or die "Could not imap4rev1: $@\en"; .Ve .PP Returns true if the \s-1IMAP\s0 server to which the IMAPClient object is connected has the \s-1IMAP4REV1\s0 capability. If the server does not have the capability then the empty string "" is returned, if the underlying \&\*(L"capability\*(R" calls fails then undef is returned. .SS "internaldate" .IX Subsection "internaldate" Example: .PP .Vb 2 \& my $msg_internal_date = $imap\->internaldate($msgid) \& or die "internaldate failed: $@\en"; .Ve .PP \&\fBinternaldate\fR accepts one argument, a message id (or \s-1UID\s0 if the \&\*(L"Uid\*(R" parameter is true), and returns that message's internal date or undef if the call fails or internal date is not returned. .SS "get_bodystructure" .IX Subsection "get_bodystructure" Example: .PP .Vb 2 \& my $bodyStructObject = $imap\->get_bodystructure($msgid) \& or die "Could not get_bodystructure: $@\en"; .Ve .PP The \fBget_bodystructure\fR method accepts one argument, a message sequence number or, if \*(L"Uid\*(R" is true, a message \s-1UID.\s0 It obtains the message's body structure and returns a parsed Mail::IMAPClient::BodyStructure object for the message. .SS "get_envelope" .IX Subsection "get_envelope" Example: .PP .Vb 2 \& my $envObject = $imap\->get_envelope(@args) \& or die "Could not get_envelope: $@\en"; .Ve .PP The \fBget_envelope\fR method accepts one argument, a message sequence number or, if \*(L"Uid\*(R" is true, a message \s-1UID.\s0 It obtains the message's envelope and returns a \&\fBMail::IMAPClient::BodyStructure::Envelope\fR object for the envelope, which is just a version of the envelope that's been parsed into a Perl object. .PP For more information on how to use this object once you've gotten it, see the Mail::IMAPClient::BodyStructure documentation. (As of this writing there is no separate pod document for \&\fBMail::IMAPClient::BodyStructure::Envelope\fR.) .SS "getacl" .IX Subsection "getacl" Example: .PP .Vb 2 \& my $hash = $imap\->getacl($folder) \& or die "Could not getacl for $folder: $@\en"; .Ve .PP \&\fBgetacl\fR accepts one argument, the name of a folder. If no argument is provided then the currently selected folder is used as the default. It returns a reference to a hash. The keys of the hash are userids that have access to the folder, and the value of each element are the permissions for that user. The permissions are listed in a string in the order returned from the server with no white space or punctuation between them. .SS "get_header" .IX Subsection "get_header" Example: .PP .Vb 1 \& my $messageId = $imap\->get_header( $msg, "Message\-Id" ); .Ve .PP The \fBget_header\fR method accepts two arguments, a message sequence number or \s-1UID\s0 and the name of an \s-1RFC822\s0 header (without the trailing colon). It returns the value for that header in the message whose sequence number or \s-1UID\s0 was passed as the first argument. If no value can be found it returns \f(CW\*(C`undef\*(C'\fR; if multiple values are found it returns the first one. Its return value is always a scalar. \&\fBget_header\fR uses case insensitive matching to get the value, so you do not have to worry about the case of your second argument. .PP The \fBget_header\fR method is a short-cut for: .PP .Vb 1 \& my $messageId = $imap\->parse_headers($msg,"Subject")\->{"Subject"}[0]; .Ve .SS "getquotaroot" .IX Subsection "getquotaroot" Example: .PP .Vb 2 \& my $results = $imap\->getquotaroot($mailboxname) \& or die "Could not getquotaroot for $mailboxname: $@\en"; .Ve .PP The \fBgetquotaroot\fR method implements the \s-1RFC2087 GETQUOTAROOT\s0 command. The \*(L"$mailboxname\*(R" defaults to \*(L"\s-1INBOX\*(R"\s0 if no argument is provided. .PP On error \f(CW\*(C`undef\*(C'\fR is returned, otherwise \*(L"Results\*(R" are returned. The results should have the untagged \s-1QUOTAROOT\s0 response from the server along with the \s-1QUOTAROOT\s0's resource usage and limits in an untagged \s-1QUOTA\s0 response. .PP See also \fB\s-1RFC2087\s0\fR, \*(L"getquota\*(R", \*(L"setquota\*(R", \*(L"quota\*(R" and \*(L"quota_usage\*(R". .SS "getquota" .IX Subsection "getquota" Example: .PP .Vb 2 \& my $results = $imap\->getquota($quotaroot) \& or die "Could not getquota for $quotaroot: $@\en"; .Ve .PP The \fBgetquota\fR method implements the \s-1RFC2087 GETQUOTA\s0 command. The \&\*(L"$quotaroot\*(R" defaults to "user/\fIUser\fR" if no argument is provided. .PP On error \f(CW\*(C`undef\*(C'\fR is returned, otherwise \*(L"Results\*(R" are returned. The results from the server should have the untagged \s-1QUOTA\s0 response from the server. .PP See also \fB\s-1RFC2087\s0\fR, \*(L"getquotaroot\*(R", \*(L"quota\*(R" and \*(L"quota_usage\*(R". .SS "quota" .IX Subsection "quota" Example: .PP .Vb 2 \& my $limit = $imap\->quota($quotaroot) \& or die "Could not get quota limit for $quotaroot: $@\en"; .Ve .PP The \fBquota\fR method takes the \*(L"Results\*(R" from getquota and parses out the \*(L"\s-1STORAGE\*(R"\s0 limit returned by the server. The \*(L"$quotaroot\*(R" defaults to \*(L"\s-1INBOX\*(R"\s0 if no argument is provided. .PP On error \f(CW\*(C`undef\*(C'\fR is returned, otherwise the integer \*(L"\s-1STORAGE\*(R"\s0 limit provided by the server is returned. .PP See also \fB\s-1RFC2087\s0\fR, \*(L"getquotaroot\*(R", \*(L"getquota\*(R" and \*(L"quota_usage\*(R". .SS "quota_usage" .IX Subsection "quota_usage" Example: .PP .Vb 2 \& my $usage = $imap\->quota_usage($quotaroot) \& or die "Could not get quota usage for $quotaroot: $@\en"; .Ve .PP The \fBquota_usage\fR method takes the \*(L"Results\*(R" from getquota and parses out the \*(L"\s-1STORAGE\*(R"\s0 usage returned by the server. The \&\*(L"$quotaroot\*(R" defaults to \*(L"\s-1INBOX\*(R"\s0 if no argument is provided. .PP On error \f(CW\*(C`undef\*(C'\fR is returned, otherwise the integer \*(L"\s-1STORAGE\*(R"\s0 usage provided by the server is returned. .PP See also \fB\s-1RFC2087\s0\fR, \*(L"getquotaroot\*(R", \*(L"getquota\*(R" and \*(L"quota\*(R". .SS "setquota" .IX Subsection "setquota" Example: .PP .Vb 2 \& my $results = $imap\->setquota( $quotaroot, $resource, $limit ) \& or die "Could not setquota for $quotaroot: $@\en"; .Ve .PP The \fBsetquota\fR method implements the \s-1RFC2087 SETQUOTA\s0 command. It accepts multiple pairs of \f(CW$resource\fR and \f(CW$limit\fR arguments. The \&\*(L"$quotaroot\*(R" defaults to "user/\fIUser\fR" if not defined. .PP On error \f(CW\*(C`undef\*(C'\fR is returned, otherwise \*(L"Results\*(R" are returned. .PP See also \fB\s-1RFC2087\s0\fR, \*(L"getquotaroot\*(R" and \*(L"getquota\*(R". .SS "is_parent" .IX Subsection "is_parent" Example: .PP .Vb 1 \& my $hasKids = $imap\->is_parent($folder); .Ve .PP The \fBis_parent\fR method accepts one argument, the name of a folder. It returns a value that indicates whether or not the folder has children. The value it returns is either: .ie n .IP "1 (or a positive integer)" 4 .el .IP "\f(CW1\fR (or a positive integer)" 4 .IX Item "1 (or a positive integer)" The \f(CW\*(C`\eHasChildren\*(C'\fR attribute is set, indicating that the folder has children. .ie n .IP "0 (zero)" 4 .el .IP "\f(CW0\fR (zero)" 4 .IX Item "0 (zero)" The \f(CW\*(C`\eHasNoChildren\*(C'\fR attribute is set, indicating that the folder has no children at this time. .ie n .IP """undef""" 4 .el .IP "\f(CWundef\fR" 4 .IX Item "undef" The \f(CW\*(C`\eNoInferiors\*(C'\fR attribute is set, indicating the folder is not permitted to have children. .PP Eg: .PP .Vb 12 \& my $parenthood = $imap\->is_parent($folder); \& if ( defined($parenthood) ) { \& if ($parenthood) { \& print "$folder has children.\en"; \& } \& else { \& print "$folder is permitted children, but has none.\en"; \& } \& } \& else { \& print "$folder is not permitted to have children.\en"; \& } .Ve .SS "list" .IX Subsection "list" Example: .PP .Vb 2 \& my @raw_output = $imap\->list(@args) \& or die "Could not list: $@\en"; .Ve .PP The \fBlist\fR method implements the \s-1IMAP LIST\s0 client command. Arguments are passed to the \s-1IMAP\s0 server as received, separated from each other by spaces. If no arguments are supplied then the default list command \&\f(CW\*(C`tag LIST "" \*(Aq*\*(Aq\*(C'\fR is issued. .PP The \fBlist\fR method returns an array (or an array reference, if called in a scalar context). The array is the unadulterated output of the \&\s-1LIST\s0 command. (If you want your output adulterated then see the \&\*(L"folders\*(R" method, above.) .PP An \f(CW\*(C`undef\*(C'\fR value is returned in case of errors. Be sure to check for it. .SS "listrights" .IX Subsection "listrights" Example: .PP .Vb 2 \& $imap\->listrights( $folder, $user ) \& or die "Could not listrights: $@\en"; .Ve .PP The \fBlistrights\fR method implements the \s-1IMAP LISTRIGHTS\s0 client command (\s-1RFC2086\s0). It accepts two arguments, the foldername and a user id. It returns the rights the specified user has for the specified folder. If called in a scalar context then the rights are returned a strings, with no punctuation or white space or any nonsense like that. If called in array context then \fBlistrights\fR returns an array in which each element is one right. .SS "login" .IX Subsection "login" Example: .PP .Vb 1 \& $imap\->login or die "Could not login: $@\en"; .Ve .PP The \fBlogin\fR method implements the \s-1IMAP LOGIN\s0 client command to log into the server. It automatically calls \*(L"authenticate\*(R" if the \&\fIAuthmechanism\fR parameter is set to anything except '\s-1LOGIN\s0' otherwise a clear text \s-1LOGIN\s0 is attempted. .PP The \fIUser\fR and \fIPassword\fR parameters must be set before the \fBlogin\fR method can be invoked. On success, a Mail::IMAPClient object with the Status of \fIAuthenticated\fR is returned. On failure, undef is returned and $@ is set. The methods \*(L"new\*(R", \*(L"connect\*(R", and \*(L"Socket\*(R" may automatically invoke \fBlogin\fR see the documentation of each method for details. .PP If the \*(L"Compress\*(R" parameter is set, the \*(L"compress\*(R" method will automatically be called after successful authentication. .PP See also \*(L"proxyauth\*(R" and \*(L"Proxy\*(R" for additional information regarding ways of authenticating with a server via \s-1SASL\s0 and/or \&\s-1PROXYAUTH.\s0 .SS "proxyauth" .IX Subsection "proxyauth" Example: .PP .Vb 2 \& $imap\->login( "admin", "password" ); \& $imap\->proxyauth("someuser"); .Ve .PP The \fBproxyauth\fR method implements the \s-1IMAP PROXYAUTH\s0 client command. The command is used by Sun/iPlanet/Netscape \s-1IMAP\s0 servers to allow an administrative user to masquerade as another user. .SS "logout" .IX Subsection "logout" Example: .PP .Vb 1 \& $imap\->logout or die "Could not logout: $@\en"; .Ve .PP The \fBlogout\fR method implements the \s-1LOGOUT IMAP\s0 client command. This method causes the server to end the connection and the IMAPClient client enters the \fIUnconnected\fR state. This method does not, destroy the IMAPClient object, thus the \*(L"connect\*(R" and \*(L"login\*(R" methods can be used to establish a new \s-1IMAP\s0 session. .PP Note that \s-1RFC2683\s0 section 3.1.2 (Severed connections) makes some recommendations on how \s-1IMAP\s0 clients should behave. It is up to the user of this module to decide on the preferred behavior and code accordingly. .PP Version note: documentation (from 2.x through 3.23) claimed that Mail::IMAPClient would attempt to log out of the server during \&\fB\s-1DESTROY\s0\fR if the object is in the \*(L"Connected\*(R" state. This documentation was apparently incorrect from at least 2.2.2 and possibly earlier versions on up. .SS "lsub" .IX Subsection "lsub" Example: .PP .Vb 1 \& $imap\->lsub(@args) or die "Could not lsub: $@\en"; .Ve .PP The \fBlsub\fR method implements the \s-1IMAP LSUB\s0 client command. Arguments are passed to the \s-1IMAP\s0 server as received, separated from each other by spaces. If no arguments are supplied then the default lsub command \&\f(CW\*(C`tag LSUB "" \*(Aq*\*(Aq\*(C'\fR is issued. .PP The \fBlsub\fR method returns an array (or an array reference, if called in a scalar context). The array is the unaltered output of the \s-1LSUB\s0 command. If you want an array of subscribed folders then see the \&\*(L"subscribed\*(R" method, below. .SS "mark" .IX Subsection "mark" Example: .PP .Vb 1 \& $imap\->mark(@msgs) or die "Could not mark: $@\en"; .Ve .PP The \fBmark\fR method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then sets the \*(L"\eFlagged\*(R" flag for those message(s). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers had better be unique message id's. .PP Note that specifying \f(CW\*(C`$imap\->see(@msgs)\*(C'\fR is just a shortcut for specifying \f(CW\*(C`$imap\->set_flag("Flagged",@msgs)\*(C'\fR. .SS "Massage" .IX Subsection "Massage" Example: .PP .Vb 1 \& $imap\->search(HEADER => \*(AqMessage\-id\*(Aq => $imap\->Massage($msg_id,1)); .Ve .PP \&\s-1WARNING:\s0 This method may be deprecated in the future, consider using \&\*(L"Quote\*(R" instead of this method. .PP The \fBMassage\fR method accepts a value as an argument and, optionally, a second value that, when true, indicates that the first argument is not the name of an existing folder. .PP \&\s-1WARNING:\s0 If the first argument has double quotes at the beginning and end of its value, those double quote will be stripped unless the second argument does not evaluate to true. .PP It returns its argument as a correctly quoted string or a literal string. .PP Note that you should rarely use this on folder names, since methods that accept folder names as an argument will call \fBQuote\fR for you. .SS "message_count" .IX Subsection "message_count" Example: .PP .Vb 2 \& my $msgcount = $imap\->message_count($folder); \& defined($msgcount) or die "message_count failed: $@\en"; .Ve .PP The \fBmessage_count\fR method accepts the name of a folder as an argument and returns the number of messages in that folder. Internally, it invokes the \*(L"status\*(R" method (see above) and parses out the results to obtain the number of messages. If you don't supply an argument to \fBmessage_count\fR then it will return the number of messages in the currently selected folder (assuming of course that you've used the \*(L"select\*(R" or \*(L"examine\*(R" method to select it instead of trying something funky). Note that \s-1RFC2683\s0 contains warnings about the use of the \s-1IMAP\s0 \fI\s-1STATUS\s0\fR command (and thus the \*(L"status\*(R" method and therefore the \fBmessage_count\fR method) against the currently selected folder. You should carefully consider this before using \&\fBmessage_count\fR on the currently selected folder. You may be better off using \*(L"search\*(R" or one of its variants (especially \*(L"messages\*(R"), and then counting the results. On the other hand, I regularly violate this rule on my server without suffering any dire consequences. Your mileage may vary. .SS "message_string" .IX Subsection "message_string" Example: .PP .Vb 2 \& my $string = $imap\->message_string($msgid) \& or die "message_string failed: $@\en"; .Ve .PP The \fBmessage_string\fR method accepts a message sequence number (or message \s-1UID\s0 if \*(L"Uid\*(R" is true) as an argument and returns the message as a string. The returned value contains the entire message in one scalar variable, including the message headers. Note that using this method will set the message's \*(L"\eSeen\*(R" flag as a side effect, unless \&\fIPeek\fR is set to a true value. .SS "message_to_file" .IX Subsection "message_to_file" Example: .PP .Vb 2 \& $imap\->message_to_file( $file, @msgs ) \& or die "message_to_file failed: $@\en"; .Ve .PP The \fBmessage_to_file\fR method accepts a filename or file handle and one or more message sequence numbers (or message UIDs if \*(L"Uid\*(R" is true) as arguments and places the message string(s) (including \s-1RFC822\s0 headers) into the file named in the first argument (or prints them to the file handle, if a file handle is passed). The returned value is true on success and \f(CW\*(C`undef\*(C'\fR on failure. .PP If the first argument is a reference, it is assumed to be an open file handle and will not be closed when the method completes, If it is a file, it is opened in append mode, written to, then closed. .PP Note that using this method will set the message's \*(L"\eSeen\*(R" flag as a side effect. But you can use the \*(L"deny_seeing\*(R" method to set it back, or set the \*(L"Peek\*(R" parameter to a true value to prevent setting the \*(L"\eSeen\*(R" flag at all. .PP This method currently works by making some basic assumptions about the server's behavior, notably that the message text will be returned as a literal string but that nothing else will be. If you have a better idea then I'd like to hear it. .SS "message_uid" .IX Subsection "message_uid" Example: .PP .Vb 2 \& my $msg_uid = $imap\->message_uid($msg_seq_no) \& or die "Could not get uid for $msg_seq_no: $@\en"; .Ve .PP The \fBmessage_uid\fR method accepts a message sequence number (or message \s-1UID\s0 if \*(L"Uid\*(R" is true) as an argument and returns the message's \s-1UID.\s0 Yes, if \*(L"Uid\*(R" is true then it will use the \s-1IMAP UID FETCH UID\s0 client command to obtain and return the very same argument you supplied. This is an \s-1IMAP\s0 feature so don't complain to me about it. .SS "messages" .IX Subsection "messages" Example: .PP .Vb 4 \& # Get a list of messages in the current folder: \& my @msgs = $imap\->messages or warn "Could not list messages\en"; \& # Get a reference to an array of messages in the current folder: \& my $msgs = $imap\->messages or die "Get messages failed: $@\en"; .Ve .PP If called in list context, the \fBmessages\fR method returns a list of all the messages in the currently selected folder. If called in scalar context, it returns a reference to an array containing all the messages in the folder. This is the same as specifying \&\f(CW\*(C`$imap\->"search"("ALL")\*(C'\fR. .PP An empty list is returned when no messages are found. On failure is returned and \*(L"LastError\*(R" is set. .SS "migrate" .IX Subsection "migrate" Example: .PP .Vb 2 \& $imap_src\->migrate( $imap_dest, "ALL", $targetFolder ) \& or die "Could not migrate: ", $imap_src\->LastError; .Ve .PP The \fBmigrate\fR method copies the indicated message(s) \fBfrom\fR the currently selected folder \fBto\fR another Mail::IMAPClient object's session. It requires these arguments: .IP "1." 4 a reference to the target Mail::IMAPClient object (not the calling object, which is connected to the source account); .IP "2." 4 the message(s) to be copied, specified as either a) the message sequence number (or message \s-1UID\s0 if the \s-1UID\s0 parameter is true) of a single message, b) a reference to an array of message sequence numbers (or message \s-1UID\s0's if the \s-1UID\s0 parameter is true) or c) the special string \*(L"\s-1ALL\*(R",\s0 which is a shortcut for the results of \&\f(CW\*(C`"search"("ALL")\*(C'\fR. .IP "3." 4 the name of the destination folder on the target mailbox to receive the message(s). If this argument is not supplied or is \fIundef\fR then the currently selected folder on the calling object will be used. The destination folder will be automatically created if necessary. .PP The target ($imap_dest) Mail::IMAPClient object must not be the same object as the source ($imap_src). .PP This method does not attempt to minimize memory usage. In the future it could be enhanced to (optionally) write message data to a temporary file to avoid storing the entire message in memory. .PP To work around potential network timeouts on large messages, consider setting \*(L"Reconnectretry\*(R" to 1 on both \f(CW$imap_src\fR and \f(CW$imap_dest\fR. .PP See also \f(CW\*(C`Supportedflags\*(C'\fR. .SS "move" .IX Subsection "move" Example: .PP .Vb 3 \& my $newUid = $imap\->move( $newFolder, $oldUid ) \& or die "Could not move: $@\en"; \& $imap\->expunge; .Ve .PP The \fBmove\fR method moves messages from the currently selected folder to the folder specified in the first argument to \fBmove\fR. If the \&\*(L"Uid\*(R" parameter is not true, then the rest of the arguments should be either: .IP "a)" 4 .IX Item "a)" a message sequence number, .IP "b)" 4 .IX Item "b)" a comma-separated list of message sequence numbers, or .IP "c)" 4 .IX Item "c)" a reference to an array of message sequence numbers. .PP If the \*(L"Uid\*(R" parameter is true, then the arguments should be: .IP "a)" 4 .IX Item "a)" a message \s-1UID,\s0 .IP "b)" 4 .IX Item "b)" a comma-separated list of message \s-1UID\s0's, or .IP "c)" 4 .IX Item "c)" a reference to an array of message \s-1UID\s0's. .PP If the target folder does not exist then it will be created. .PP If move is successful, then it returns a true value. Furthermore, if the Mail::IMAPClient object is connected to a server that has the \&\s-1UIDPLUS\s0 capability, then the true value will be the comma-separated list of \s-1UID\s0's for the newly copied messages. The list will be in the order in which the messages were moved which should correspond to the order of the message \s-1UID\s0 provided by the caller. .PP If the move is not successful then \fBmove\fR returns \f(CW\*(C`undef\*(C'\fR. .PP Note that a move really just involves copying the message to the new folder and then setting the \fI\eDeleted\fR flag. To actually delete the original message you will need to run \*(L"expunge\*(R" (or \*(L"close\*(R"). .SS "namespace" .IX Subsection "namespace" Example: .PP .Vb 2 \& my $refs = $imap\->namespace \& or die "namespace failed: $@\en"; .Ve .PP The namespace method runs the \s-1NAMESPACE IMAP\s0 command (as defined in \&\s-1RFC 2342\s0). When called in a list context, it returns a list of three references. Each reference looks like this: .PP .Vb 5 \& [ \& [ $prefix_1, $separator_1 ], \& [ $prefix_2, $separator_2 ], \& [ $prefix_n, $separator_n ], \& ] .Ve .PP The first reference provides a list of prefixes and separator characters for the available personal namespaces. The second reference provides a list of prefixes and separator characters for the available shared namespaces. The third reference provides a list of prefixes and separator characters for the available public namespaces. .PP If any of the three namespaces are unavailable on the current server then an 'undef' is returned instead of a reference. So for example if shared folders were not supported on the server but personal and public namespaces were both available (with one namespace each), the returned value might resemble this: .PP .Vb 1 \& [ [ "", "/" ] , undef, [ "#news", "." ] ]; .Ve .PP If the \fBnamespace\fR method is called in scalar context, it returns a reference to the above-mentioned list of three references, thus creating a single structure that would pretty-print something like this: .PP .Vb 10 \& $VAR1 = [ \& [ \& [ $user_prefix_1, $user_separator_1 ], \& [ $user_prefix_2, $user_separator_2 ], \& [ $user_prefix_n, $user_separator_n ], \& ], # or undef \& [ \& [ $shared_prefix_1, $shared_separator_1 ], \& [ $shared_prefix_2, $shared_separator_2 ], \& [ $shared_prefix_n, $shared_separator_n ], \& ], # or undef \& [ \& [ $public_prefix_1, $public_separator_1 ], \& [ $public_prefix_2, $public_separator_2 ], \& [ $public_prefix_n, $public_separator_n ], \& ], # or undef \& ]; .Ve .SS "on" .IX Subsection "on" Example: .PP .Vb 2 \& my @msgs = $imap\->on($Rfc3501_date) \& or warn "Could not find messages sent on $Rfc3501_date: $@\en"; .Ve .PP The \fBon\fR method works just like the \*(L"since\*(R" method, below, except it returns a list of messages whose internal system dates are the same as the date supplied as the argument. .SS "parse_headers" .IX Subsection "parse_headers" Example: .PP .Vb 2 \& my $hashref = $imap\->parse_headers( $msg || \e@msgs, "Date", "Subject" ) \& or die "Could not parse_headers: $@\en"; .Ve .PP The \fBparse_headers\fR method accepts as arguments a message sequence number and a list of header fields. It returns a hash reference in which the keys are the header field names (without the colon) and the values are references to arrays of values. On failure is returned and \*(L"LastError\*(R" is set. .PP A picture would look something like this: .PP .Vb 10 \& $hashref = $imap\->parse_headers( 1, "Date", "Received", "Subject", "To"); \& $hashref = { \& "Date" => [ "Thu, 09 Sep 1999 09:49:04 \-0400" ] , \& "Received" => [ q/ \& from mailhub ([111.11.111.111]) by mailhost.bigco.com \& (Netscape Messaging Server 3.6) with ESMTP id AAA527D for \& ; Fri, 18 Jun 1999 16:29:07 +0000 \& /, q/ \& from directory\-daemon by mailhub.bigco.com (PMDF V5.2\-31 #38473) \& id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com \& (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT) \& /, q/ \& from someplace ([999.9.99.99]) by smtp\-relay.bigco.com (PMDF V5.2\-31 #38473) \& with ESMTP id <0FDJ0000P74H0W@smtp\-relay.bigco.com> for big.shot@bigco.com; Fri, \& 18 Jun 1999 16:29:05 +0000 (GMT) \& /] , \& "Subject" => [ qw/ Help! I\*(Aqve fallen and I can\*(Aqt get up!/ ] , \& "To" => [ "Big Shot ] , \& }; .Ve .PP The text in the example for the \*(L"Received\*(R" array has been formatted to make reading the example easier. The actual values returned are just strings of words separated by spaces and with newlines and carriage returns stripped off. The \fIReceived\fR header is probably the main reason that the \fBparse_headers\fR method creates a hash of lists rather than a hash of values. .PP If the second argument to \fBparse_headers\fR is '\s-1ALL\s0' or if it is unspecified then all available headers are included in the returned hash of lists. .PP If you're not emotionally prepared to deal with a hash of lists then you can always call the \*(L"fetch\*(R" method yourself with the appropriate parameters and parse the data out any way you want to. Also, in the case of headers whose contents are also reflected in the envelope, you can use the \*(L"get_envelope\*(R" method as an alternative to \&\*(L"parse_headers\*(R". .PP If the \*(L"Uid\*(R" parameter is true then the first argument will be treated as a message \s-1UID.\s0 If the first argument is a reference to an array of message sequence numbers (or \s-1UID\s0's if \*(L"Uid\*(R" is true), then \&\fBparse_headers\fR will be run against each message in the array. In this case the return value is a hash, in which the key is the message sequence number (or \s-1UID\s0) and the value is a reference to a hash as described above. .PP An example of using \fBparse_headers\fR to print the date and subject of every message in your demo folder could look like this: .PP .Vb 4 \& use Mail::IMAPClient; \& my $imap = Mail::IMAPClient\->new( \& Server => $imaphost, User => $login, Password => $pass, Uid => 1 \& ); \& \& $imap\->select("demo"); \& \& my $msgs = $imap\->search("ALL"); \& for my $h ( \& \& # get the Subject and Date from every message in folder "demo" the \& # first arg is a reference to an array listing all messages in the \& # folder (which is what gets returned by the $imap\->search("ALL") \& # method when called in scalar context) and the remaining arguments \& # are the fields to parse out The key is the message number, which \& # in this case we don\*(Aqt care about: \& \& values %{ $imap\->parse_headers( $msgs , "Subject", "Date") } ) \& { \& # $h is the value of each element in the hash ref returned \& # from parse_headers, and $h is also a reference to a hash. \& # We\*(Aqll only print the first occurrence of each field because \& # we don\*(Aqt expect more than one Date: or Subject: line per \& # message. \& print map { "$_:\et$h\->{$_}[0]\en"} keys %$h; \& } .Ve .SS "recent" .IX Subsection "recent" Example: .PP .Vb 1 \& my @recent = $imap\->recent or warn "No recent msgs: $@\en"; .Ve .PP The \fBrecent\fR method performs an \s-1IMAP SEARCH RECENT\s0 search against the selected folder and returns an array of sequence numbers (or \s-1UID\s0's, if the \*(L"Uid\*(R" parameter is true) of messages that are recent. .SS "recent_count" .IX Subsection "recent_count" Example: .PP .Vb 3 \& my $count = 0; \& defined($count = $imap\->recent_count($folder)) \& or die "recent_count failed: $@\en"; .Ve .PP The \fBrecent_count\fR method accepts as an argument a folder name. It returns the number of recent messages in the folder (as returned by the \s-1IMAP\s0 client command \*(L"\s-1STATUS\s0 folder \s-1RECENT\*(R"\s0), or \f(CW\*(C`undef\*(C'\fR in the case of an error. The \fBrecent_count\fR method was contributed by Rob Deker (deker@ikimbo.com). .SS "noop" .IX Subsection "noop" Example: .PP .Vb 1 \& $imap\->noop or die "noop failed: $@\en"; .Ve .PP The \fBnoop\fR method performs an \s-1IMAP NOOP\s0 command. Per \s-1RFC3501\s0 this command does nothing and always succeeds. However, if a connection times out or other errors occur while communicating with the server, this method can still fail. This command can be used as a periodic poll to check for (untagged) status updates (new messages, etc.) from the server and also to reset any inactivity/auto\-logout timers the server may maintain. .SS "reconnect" .IX Subsection "reconnect" Example: .PP .Vb 1 \& $imap\->noop or $imap\->reconnect or die "noop failed: $@\en"; .Ve .PP Attempt to reconnect if the \s-1IMAP\s0 connection unless \f(CW$imap\fR is already in the IsConnected state. This method calls \*(L"connect\*(R" and optionally \&\*(L"select\*(R" if a Folder was previously selected. On success, returns the (same) \f(CW$imap\fR object. On failure is returned and \&\*(L"LastError\*(R" is set. .PP Version note: method added in Mail::IMAPClient 3.17 .SS "rename" .IX Subsection "rename" Example: .PP .Vb 2 \& $imap\->rename( $oldname, $nedwname ) \& or die "rename failed: $@\en"; .Ve .PP The \fBrename\fR method accepts two arguments: the name of an existing folder, and a new name for the folder. The existing folder will be renamed to the new name using the \s-1RENAME IMAP\s0 client command. \&\fBrename\fR will return a true value if successful, or \f(CW\*(C`undef\*(C'\fR if unsuccessful. .SS "restore_message" .IX Subsection "restore_message" Example: .PP .Vb 1 \& $imap\->restore_message(@msgs) or die "restore_message failed: $@\en"; .Ve .PP The \fBrestore_message\fR method is used to undo a previous \&\*(L"delete_message\*(R" operation (but not if there has been an intervening \&\*(L"expunge\*(R" or \*(L"close\*(R"). The IMAPClient object must be in \&\*(L"Selected\*(R" status to use the \fBrestore_message\fR method. .PP The \fBrestore_message\fR method accepts a list of arguments. If the \&\*(L"Uid\*(R" parameter is not set to a true value, then each item in the list should be either: .IP ">" 4 a message sequence number, .IP ">" 4 a comma-separated list of message sequence numbers, .IP ">" 4 a reference to an array of message sequence numbers, or .PP If the \*(L"Uid\*(R" parameter is set to a true value, then each item in the list should be either: .IP ">" 4 a message \s-1UID,\s0 .IP ">" 4 a comma-separated list of \s-1UID\s0's, or .IP ">" 4 a reference to an array of message \s-1UID\s0's. .PP The messages identified by the sequence numbers or \s-1UID\s0's will have their \fI\eDeleted\fR flags cleared, effectively \*(L"undeleting\*(R" the messages. \fBrestore_message\fR returns the number of messages it was able to restore. .PP Note that \fBrestore_messages\fR is similar to calling \&\f(CW\*(C`"unset_flag"("\eDeleted",@msgs)\*(C'\fR, except that \fBrestore_messages\fR returns a (slightly) more meaningful value. Also it's easier to type. .SS "run" .IX Subsection "run" Example: .PP .Vb 1 \& $imap\->run(@args) or die "run failed: $@\en"; .Ve .PP The \fBrun\fR method is provided to make those uncommon things possible... however, we would like you to contribute the knowledge of missing features with us. .PP The \fBrun\fR method excepts one or two arguments. The first argument is a string containing an \s-1IMAP\s0 client command, including a tag and all required arguments. The optional second argument is a string to look for that will indicate success. (The default is \f(CW\*(C`/OK.*/\*(C'\fR). The \&\fBrun\fR method returns an array (or arrayref in scalar context) of output lines from the command, which you are free to parse as you see fit. .PP The \fBrun\fR method does not do any syntax checking, other than rudimentary checking for a tag. .PP When \fBrun\fR processes the command, it increments the transaction count and saves the command and responses in the History buffer in the same way other commands do. However, it also creates a special entry in the History buffer named after the tag supplied in the string passed as the first argument. If you supply a numeric value as the tag then you may risk overwriting a previous transaction's entry in the History buffer. .PP If you want the control of \fBrun\fR but you don't want to worry about tags then see \*(L"tag_and_run\*(R", below. .SS "search" .IX Subsection "search" Example: .PP .Vb 7 \& my $msgs1 = $imap\->search(@args); \& if ($msgs1) { \& print "search matches: @$msgs1"; \& } \& else { \& warn "Error in search: $@\en" if $@; \& } \& \& # or note: be sure to quote string properly \& my $msgs2 = $imap\->search( \e( $imap\->Quote($msgid), "FROM", q{"me"} ) ) \& or warn "search failed: $@\en"; \& \& # or note: be sure to quote string properly \& my $msgs3 = $imap\->search(\*(AqTEXT "string not in mailbox"\*(Aq) \& or warn "search failed: $@\en"; .Ve .PP The \fBsearch\fR method implements the \s-1SEARCH IMAP\s0 client command. Any arguments supplied to \fBsearch\fR are prefixed with a space then appended to the \s-1SEARCH IMAP\s0 client command. The \s-1SEARCH IMAP\s0 client command allows for many options and arguments. See \s-1RFC3501\s0 for details. .PP As of version 3.17 \fBsearch\fR tries to \*(L"\s-1DWIM\*(R"\s0 by automatically quoting things that likely need quotes when the words do not match any of the following: .PP .Vb 5 \& ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED \& FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT \& SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT \& TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED \& UNKEYWORD UNSEEN .Ve .PP The following options exist to avoid the automatic quoting (note: caller is responsible for verifying the data sent in these cases is properly escaped/quoted): .IP "\(bu" 4 specify a single string/argument in the call to search. .IP "\(bu" 4 specify args as scalar references (\s-1SCALAR\s0) and the values of those \&\s-1SCALAR\s0 refs will be passed along as-is. .PP The \fBsearch\fR method returns an array containing sequence numbers of messages that passed the \s-1SEARCH IMAP\s0 client command's search criteria. If the \*(L"Uid\*(R" parameter is true then the array will contain message \&\s-1UID\s0's. If \fBsearch\fR is called in scalar context then a pointer to the array will be passed, instead of the array itself. If no messages meet the criteria then \fBsearch\fR returns an empty list (when in list context) or \f(CW\*(C`undef\*(C'\fR (in scalar context). .PP Since a valid, successful search can legitimately return zero matches, you may wish to distinguish between a search that correctly returns zero hits and a search that has failed for some other reason (i.e. invalid search parameters). Therefore, the \f(CW$@\fR variable will always be cleared before the \fI\s-1SEARCH\s0\fR command is issued to the server, and will thus remain empty unless the server gives a \fI\s-1BAD\s0\fR or \fI\s-1NO\s0\fR response to the \fI\s-1SEARCH\s0\fR command. .SS "see" .IX Subsection "see" Example: .PP .Vb 1 \& $imap\->see(@msgs) or die "see failed: $@\en"; .Ve .PP The \fBsee\fR method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then sets the \fI\eSeen\fR flag for those message(s). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers had better be unique message id's, but then you already knew that, didn't you? .PP Note that specifying \f(CW\*(C`$imap\->see(@msgs)\*(C'\fR is just a shortcut for specifying \f(CW\*(C`$imap\->"set_flag"("Seen",@msgs)\*(C'\fR. .SS "seen" .IX Subsection "seen" Example: .PP .Vb 1 \& my @seenMsgs = $imap\->seen or warn "No seen msgs: $@\en"; .Ve .PP The \fBseen\fR method performs an \s-1IMAP SEARCH SEEN\s0 search against the selected folder and returns an array of sequence numbers of messages that have already been seen (ie their \fI\eSeen\fR flag is set). If the \&\*(L"Uid\*(R" parameter is true then an array of message \s-1UID\s0's will be returned instead. If called in scalar context than a reference to the array (rather than the array itself) will be returned. .SS "select" .IX Subsection "select" Example: .PP .Vb 1 \& $imap\->select($folder) or die "select failed: $@\en"; .Ve .PP The \fBselect\fR method selects a folder and changes the object's state to \fISelected\fR. It accepts one argument, which is the name of the folder to select. .SS "selectable" .IX Subsection "selectable" Example: .PP .Vb 3 \& foreach my $f ( grep( $imap\->selectable($_), $imap\->folders ) ) { \& $imap\->select($f); \& } .Ve .PP The \fBselectable\fR method accepts one value, a folder name, and returns true if the folder is selectable or false if it is not selectable. .SS "sentbefore" .IX Subsection "sentbefore" Example: .PP .Vb 2 \& my @msgs = $imap\->sentbefore($Rfc3501_date) \& or warn "Could not find any msgs sent before $Rfc3501_date: $@\en"; .Ve .PP The \fBsentbefore\fR method works just like \*(L"sentsince\*(R", below, except it searches for messages that were sent before the date supplied as an argument to the method. .SS "senton" .IX Subsection "senton" Example: .PP .Vb 2 \& my @msgs = $imap\->senton($Rfc3501_date) \& or warn "Could not find any messages sent on $Rfc3501_date: $@\en"; .Ve .PP The \fBsenton\fR method works just like \*(L"sentsince\*(R", below, except it searches for messages that were sent on the exact date supplied as an argument to the method. .SS "sentsince" .IX Subsection "sentsince" Example: .PP .Vb 2 \& my @msgs = $imap\->sentsince($Rfc3501_date) \& or warn "Could not find any messages sent since $Rfc3501_date: $@\en"; .Ve .PP The \fBsentsince\fR method accepts one argument, a date in either epoch time format (seconds since 1/1/1970, or as output by time and as accepted by localtime) or in the \fIdate_text\fR format as defined in \s-1RFC3501\s0 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). .PP It searches for items in the currently selected folder for messages sent since the day whose date is provided as the argument. It uses the \s-1RFC822\s0 \fIDate:\fR header to determine the \fIsentsince\fR date. (Actually, it the server that uses the \fIDate:\fR header; this documentation just assumes that the date is coming from the \fIDate:\fR header because that's what \s-1RFC3501\s0 dictates.) .PP In the case of arguments supplied as a number of seconds, the returned result list will include items sent on or after that day, regardless of whether they arrived before the specified time on that day. The \&\s-1IMAP\s0 protocol does not support searches at a granularity finer than a day, so neither do I. On the other hand, the only thing I check for in a \fIdate_text\fR argument is that it matches the pattern \&\f(CW\*(C`/\ed\ed\-\eD\eD\eD\-\ed\ed\ed\ed/\*(C'\fR (notice the lack of anchors), so if your server lets you add something extra to a \fIdate_text\fR string then so will Mail::IMAPClient. .PP If you'd like, you can use the \*(L"Rfc3501_date\*(R" method to convert from epoch time (as returned by time) into an \s-1RFC3501\s0 date specification. .SS "separator" .IX Subsection "separator" Example: .PP .Vb 2 \& my $sepChar = $imap\->separator(@args) \& or die "Could not get separator: $@\en"; .Ve .PP The \fBseparator\fR method returns the character used as a separator character in folder hierarchies. On UNIX-based servers, this is often but not necessarily a forward slash (/). It accepts one argument, the name of a folder whose hierarchy's separator should be returned. If no folder name is supplied then the separator for the \s-1INBOX\s0 is returned, which probably is good enough. .PP If you want your programs to be portable from \s-1IMAP\s0 server brand X to \&\s-1IMAP\s0 server brand Y, then you should never use hard-coded separator characters to specify subfolders. (In fact, it's even more complicated than that, since some server don't allow any subfolders at all, some only allow subfolders under the \*(L"\s-1INBOX\*(R"\s0 folder, and some forbid subfolders in the inbox but allow them \*(L"next\*(R" to the inbox. Furthermore, some server implementations do not allow folders to contain both subfolders and mail messages; other servers allow this.) .SS "set_flag" .IX Subsection "set_flag" Example: .PP .Vb 2 \& $imap\->set_flag( "Seen", @msgs ) \& or die "Could not set flag: $@\en"; .Ve .PP The \fBset_flag\fR method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then sets the flag specified for those message(s). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect. .PP Note that when specifying the flag in question, the preceding backslash (\e) is entirely optional. (For you, that is. Mail::IMAPClient still has remember to stick it in there before passing the command to the server if the flag is one of the reserved flags specified in \s-1RFC3501.\s0 This is in fact so important that the method checks its argument and adds the backslash when necessary, which is why you don't have to worry about it overly much.) .SS "setacl" .IX Subsection "setacl" Example: .PP .Vb 2 \& $imap\->setacl( $folder, $userid, $aclstring ) \& or die "Could not set acl: $@\en"; .Ve .PP The \fBsetacl\fR method accepts three input arguments, a folder name, a user id (or authentication identifier, to use the terminology of \&\s-1RFC2086\s0), and an access rights modification string. See \s-1RFC2086\s0 for more information. (This is somewhat experimental and its implementation may change.) .SS "since" .IX Subsection "since" Example: .PP .Vb 2 \& my @msgs = $imap\->since($date) \& or warn "Could not find any messages since $date: $@\en"; .Ve .PP The \fBsince\fR method accepts a date in either epoch format (seconds since 1/1/1970, or as output by \*(L"time\*(R" in perlfunc and as accepted by \&\*(L"localtime\*(R" in perlfunc) or in the \fIdate_text\fR format as defined in \&\s-1RFC3501\s0 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). It searches for items in the currently selected folder for messages whose internal dates are on or after the day whose date is provided as the argument. It uses the internal system date for a message to determine if that message was sent since the given date. .PP In the case of arguments supplied as a number of seconds, the returned result list will include items whose internal date is on or after that day, regardless of whether they arrived before the specified time on that day. .PP If \fBsince\fR is called in a list context then it will return a list of messages meeting the \fI\s-1SEARCH SINCE\s0\fR criterion, or an empty list if no messages meet the criterion. .PP If \fBsince\fR is called in a scalar context then it will return a reference to an array of messages meeting the \fI\s-1SEARCH SINCE\s0\fR criterion, or \f(CW\*(C`undef\*(C'\fR if no messages meet the criterion. .PP Since \fBsince\fR is a front-end to \*(L"search\*(R", some of the same rules apply. For example, the \f(CW$@\fR variable will always be cleared before the \fI\s-1SEARCH\s0\fR command is issued to the server, and will thus remain empty unless the server gives a \fI\s-1BAD\s0\fR or \fI\s-1NO\s0\fR response to the \&\fI\s-1SEARCH\s0\fR command. .SS "size" .IX Subsection "size" Example: .PP .Vb 2 \& my $size = $imap\->size($msgId) \& or die "Could not find size of message $msgId: $@\en"; .Ve .PP The \fBsize\fR method accepts one input argument, a sequence number (or message \s-1UID\s0 if the \*(L"Uid\*(R" parameter is true). It returns the size of the message in the currently selected folder with the supplied sequence number (or \s-1UID\s0). The IMAPClient object must be in a \&\fISelected\fR state in order to use this method. .SS "sort" .IX Subsection "sort" Example: .PP .Vb 2 \& my @msgs = $imap\->sort(@args); \& warn "Error in sort: $@\en" if $@; .Ve .PP The \fBsort\fR method is just like the \*(L"search\*(R" method, only different. It implements the \s-1SORT\s0 extension as described in \&\fIhttps://tools.ietf.org/html/rfc5256\fR. It would be wise to use the \*(L"has_capability\*(R" method to verify that the \s-1SORT\s0 capability is available on your server before trying to use the \fBsort\fR method. If you forget to check and you're connecting to a server that doesn't have the \s-1SORT\s0 capability then \fBsort\fR will return undef. \*(L"LastError\*(R" will then say you are \*(L"\s-1BAD\*(R".\s0 If your server doesn't support the \s-1SORT\s0 capability then you'll have to use \*(L"search\*(R" and then sort the results yourself. .PP The first argument to \fBsort\fR is a space-delimited list of sorting criteria. The Internet Draft that describes \s-1SORT\s0 requires that this list be wrapped in parentheses, even if there is only one sort criterion. If you forget the parentheses then the \fBsort\fR method will add them. But you have to forget both of them, or none. This isn't \&\s-1CMS\s0 running under \s-1VM\s0! .PP The second argument is a character set to use for sorting. Different character sets use different sorting orders, so this argument is important. Since all servers must support \s-1UTF\-8\s0 and US-ASCII if they support the \s-1SORT\s0 capability at all, you can use one of those if you don't have some other preferred character set in mind. .PP The rest of the arguments are searching criteria, just as you would supply to the \*(L"search\*(R" method. These are all documented in \s-1RFC3501.\s0 If you just want all of the messages in the currently selected folder returned to you in sorted order, use \fI\s-1ALL\s0\fR as your only search criterion. .PP The \fBsort\fR method returns an array containing sequence numbers of messages that passed the \s-1SORT IMAP\s0 client command's search criteria. If the \*(L"Uid\*(R" parameter is true then the array will contain message \&\s-1UID\s0's. If \fBsort\fR is called in scalar context then a pointer to the array will be passed, instead of the array itself. The message sequence numbers or unique identifiers are ordered according to the sort criteria specified. The sort criteria are nested in the order specified; that is, items are sorted first by the first criterion, and within the first criterion they are sorted by the second criterion, and so on. .PP The sort method will clear \f(CW$@\fR before attempting the \fI\s-1SORT\s0\fR operation just as the \*(L"search\*(R" method does. .SS "starttls" .IX Subsection "starttls" Example: .PP .Vb 1 \& $imap\->starttls() or die "starttls failed: $@\en"; .Ve .PP The \fBstarttls\fR method accepts no arguments. This method is used to upgrade an exiting connection which is not authenticated to a \s-1TLS/SSL\s0 connection by using the \s-1IMAP STARTTLS\s0 command followed by using the \&\fBstart_SSL\fR class method from IO::Socket::SSL to do the necessary \&\s-1TLS\s0 negotiation. The negotiation is done in a blocking fashion with a default \fBTimeout\fR of 30 seconds. The arguments used in the call to \&\fBstart_SSL\fR can be controlled by setting the Mail::IMAPClient \&\*(L"Starttls\*(R" attribute to an \s-1ARRAY\s0 reference containing the desired arguments. .PP Version note: method added in Mail::IMAPClient 3.22 .SS "status" .IX Subsection "status" Example: .PP .Vb 2 \& my @rawdata = $imap\->status( $folder, qw/(Messages)/ ) \& or die "Error obtaining status: $@\en"; .Ve .PP The \fBstatus\fR method accepts one argument, the name of a folder (or mailbox, to use \s-1RFC3501\s0's terminology), and returns an array containing the results of running the \s-1IMAP STATUS\s0 client command against that folder. If additional arguments are supplied then they are appended to the \s-1IMAP STATUS\s0 client command string, separated from the rest of the string and each other with spaces. .PP If \fBstatus\fR is not called in an array context then it returns a reference to an array rather than the array itself. .PP The \fBstatus\fR method should not be confused with the \fBStatus\fR method (with an uppercase 'S'), which returns information about the IMAPClient object. (See the section labeled \*(L"Status Methods\*(R", below). .SS "store" .IX Subsection "store" Example: .PP .Vb 1 \& $imap\->store(@args) or die "Could not store: $@\en"; .Ve .PP The \fBstore\fR method accepts a message sequence number or comma-separated list of message sequence numbers as a first argument, a message data item name, and a value for the message data item. Currently, data items are the word \*(L"\s-1FLAGS\*(R"\s0 followed by a space and a list of flags (in parens). The word \*(L"\s-1FLAGS\*(R"\s0 can be modified by prefixing it with either a \*(L"+\*(R" or a \*(L"\-\*(R" (to indicate \*(L"add these flags\*(R" or \*(L"remove these flags\*(R") and by suffixing it with \*(L".SILENT\*(R" (which reduces the amount of output from the server; very useful with large message sets). Normally you won't need to call \fBstore\fR because there are oodles of methods that will invoke store for you with the correct arguments. Furthermore, these methods are friendlier and more flexible with regards to how you specify your arguments. See for example \*(L"see\*(R", \*(L"deny_seeing\*(R", \*(L"delete_message\*(R", and \&\*(L"restore_message\*(R". Or \*(L"mark\*(R", \*(L"unmark\*(R", \*(L"set_flag\*(R", and \&\*(L"unset_flag\*(R". .SS "subject" .IX Subsection "subject" Example: .PP .Vb 1 \& my $subject = $imap\->subject($msg); .Ve .PP The \fBsubject\fR method accepts one argument, a message sequence number (or a message \s-1UID,\s0 if the \fIUid\fR parameter is true). The text in the \&\*(L"Subject\*(R" header of that message is returned (without the \*(L"Subject: \*(R" prefix). This method is a short-cut for: .PP .Vb 1 \& my $subject = $imap\->get_header($msg, "Subject"); .Ve .SS "subscribed" .IX Subsection "subscribed" Example: .PP .Vb 2 \& my @subscribedFolders = $imap\->subscribed \& or warn "Could not find subscribed folders: $@\en"; .Ve .PP The \fBsubscribed\fR method works like the \fBfolders\fR method, above, except that the returned list (or array reference, if called in scalar context) contains only the subscribed folders. .PP Like \*(L"folders\*(R", you can optionally provide a prefix argument to the \&\fBsubscribed\fR method. .SS "tag_and_run" .IX Subsection "tag_and_run" Example: .PP .Vb 2 \& my $output = $imap\->tag_and_run(@args) \& or die "Could not tag_and_run: $@\en"; .Ve .PP The \fBtag_and_run\fR method accepts one or two arguments. The first argument is a string containing an \s-1IMAP\s0 client command, without a tag but with all required arguments. The optional second argument is a string to look for that will indicate success (without pattern delimiters). The default is \f(CW\*(C`OK.*\*(C'\fR. .PP The \fBtag_and_run\fR method will prefix your string (from the first argument) with the next transaction number and run the command. It returns an array of output lines from the command, which you are free to parse as you see fit. Using this method instead of \fBrun\fR (above) will free you from having to worry about handling the tags (and from worrying about the side affects of naming your own tags). .SS "uidexpunge" .IX Subsection "uidexpunge" Example: .PP .Vb 1 \& $imap\->uidexpunge(@uids) or die "Could not uidexpunge: $@\en"; .Ve .PP The \fBuidexpunge\fR method implements the \s-1UID EXPUNGE IMAP\s0 (\s-1RFC4315 UIDPLUS\s0 ext) client command to permanently remove all messages that have the \eDeleted flag set and have a \s-1UID\s0 that is included in the list of UIDs. .PP \&\fBuidexpunge\fR returns an array or arrayref (scalar context) of output lines returned from the \s-1UID EXPUNGE\s0 command. .PP \&\fBuidexpunge\fR returns undef on failure. .PP If the server does not support the \s-1UIDPLUS\s0 extension, this method returns undef. .SS "uidnext" .IX Subsection "uidnext" Example: .PP .Vb 1 \& my $nextUid = $imap\->uidnext($folder) or die "uidnext failed: $@\en"; .Ve .PP The \fBuidnext\fR method accepts one argument, the name of a folder, and returns the numeric string that is the next available message \s-1UID\s0 for that folder. .SS "thread" .IX Subsection "thread" Example: .PP .Vb 1 \& my $thread = $imap\->thread( $algorithm, $charset, @search_args ); .Ve .PP The \fBthread\fR method accepts zero to three arguments. The first argument is the threading algorithm to use, generally either \&\fI\s-1ORDEREDSUBJECT\s0\fR or \fI\s-1REFERENCES\s0\fR. The second argument is the character set to use, and the third argument is the set of search arguments to use. .PP If the algorithm is not supplied, it defaults to \fI\s-1REFERENCES\s0\fR if available, or \fI\s-1ORDEREDSUBJECT\s0\fR if available. If neither of these is available then the \fBthread\fR method returns undef. .PP If the character set is not specified it will default to \fI\s-1UTF\-8\s0\fR. .PP If the search arguments are not specified, the default is \fI\s-1ALL\s0\fR. .PP If \fBthread\fR is called for an object connected to a server that does not support the \s-1THREADS\s0 extension then the \fBthread\fR method will return \f(CW\*(C`undef\*(C'\fR. .PP The \fBthreads\fR method will issue the \fI\s-1THREAD\s0\fR command as defined in \&\fIhttps://tools.ietf.org/html/rfc5256\fR. It returns an array of threads. Each element in the array is either a message id or a reference to another array of (sub)threads. .PP If the \*(L"Uid\*(R" parameter is set to a true value then the message id's returned in the thread structure will be message \s-1UID\s0's. Otherwise they will be message sequence numbers. .SS "uidvalidity" .IX Subsection "uidvalidity" Example: .PP .Vb 2 \& my $validity = $imap\->uidvalidity($folder) \& or die "uidvalidity failed: $@\en"; .Ve .PP The \fBuidvalidity\fR method accepts one argument, the name of a folder, and returns the numeric string that is the unique identifier validity value for the folder. .SS "unmark" .IX Subsection "unmark" Example: .PP .Vb 1 \& $imap\->unmark(@msgs) or die "Could not unmark: $@\en"; .Ve .PP The \fBunmark\fR method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then unsets the \fI\eFlagged\fR flag for those message(s). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers should really be unique message id's. .PP Note that specifying \f(CW\*(C`$imap\->unmark(@msgs)\*(C'\fR is just a shortcut for specifying \f(CW\*(C`$imap\->unset_flag("Flagged",@msgs)\*(C'\fR. .PP Note also that the \fI\eFlagged\fR flag is just one of many possible flags. This is a little confusing, but you'll have to get used to the idea that among the reserved flags specified in \s-1RFC3501\s0 is one name \&\fI\eFlagged\fR. There is no specific meaning for this flag; it means whatever the mailbox owner (or delegate) wants it to mean when it is turned on. .SS "unseen" .IX Subsection "unseen" Example: .PP .Vb 1 \& my @unread = $imap\->unseen or warn "Could not find unseen msgs: $@\en"; .Ve .PP The \fBunseen\fR method performs an \s-1IMAP SEARCH UNSEEN\s0 search against the selected folder and returns an array of sequence numbers of messages that have not yet been seen (ie their \fI\eSeen\fR flag is not set). If the \*(L"Uid\*(R" parameter is true then an array of message \s-1UID\s0's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned. .SS "unseen_count" .IX Subsection "unseen_count" Example: .PP .Vb 4 \& foreach my $f ($imap\->folders) { \& print "The $f folder has ", \& $imap\->unseen_count($f)||0, " unseen messages.\en"; \& } .Ve .PP The \fBunseen_count\fR method accepts the name of a folder as an argument and returns the number of unseen messages in that folder. If no folder argument is provided then it returns the number of unseen messages in the currently selected Folder. .SS "unset_flag" .IX Subsection "unset_flag" Example: .PP .Vb 2 \& $imap\->unset_flag( "\eSeen", @msgs ) \& or die "unset_flag failed: $@\en"; .Ve .PP The \fBunset_flag\fR method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then unsets the flag specified for those message(s). Of course, if the \*(L"Uid\*(R" parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect. .SH "Other IMAP Client Commands" .IX Header "Other IMAP Client Commands" Until release \f(CW2.99\fR, when you called a method which did not exist, they where automatically translated into an \s-1IMAP\s0 call with the same name via an \s-1AUTOLOAD\s0 hack. This \*(L"feature\*(R" was removed for various reasons: people made typos in the capitalization of method names, and the program still seemed to work correctly. Besides, it blocked further development of this module, because people did not contribute their private extensions to the protocol implementation. .ie n .SS "copy($msg, $folder)" .el .SS "copy($msg, \f(CW$folder\fP)" .IX Subsection "copy($msg, $folder)" Copy a message from the currently selected folder in the folder whose name is in \f(CW$folder\fR .SS "subscribe($folder)" .IX Subsection "subscribe($folder)" Subscribe to a folder .PP \&\fB\s-1CAUTION:\s0\fR Once again, remember to quote your quotes (or use the \&\*(L"Quote\*(R" method) if you want quotes to be part of the \s-1IMAP\s0 command string. .PP You can also use the default method to override the behavior of implemented \s-1IMAP\s0 methods by changing the case of the method name, preferably to all-uppercase so as not to conflict with the Class method and accessor method namespace. For example, if you don't want the \*(L"search\*(R" method's behavior (which returns a list of message numbers) but would rather have an array of raw data returned from your \&\*(L"search\*(R" operation, you can issue the following snippet: .PP .Vb 1 \& my @raw = $imap\->SEARCH("SUBJECT","Whatever..."); .Ve .PP which is slightly more efficient than the equivalent: .PP .Vb 2 \& $imap\->search("SUBJECT","Whatever..."); \& my @raw = $imap\->Results; .Ve .PP Of course you probably want the search results tucked nicely into a list for you anyway, in which case you might as well use the \&\*(L"search\*(R" method. .SH "Parameters" .IX Header "Parameters" There are several parameters that influence the behavior of an IMAPClient object. Each is set by specifying a named value pair during new method invocation as follows: .PP .Vb 4 \& my $imap = Mail::IMAPClient\->new ( parameter => "value", \& parameter2 => "value", \& ... \& ); .Ve .PP Parameters can also be set after an object has been instantiated by using the parameter's eponymous accessor method like this: .PP .Vb 3 \& my $imap = Mail::IMAPClient\->new; \& $imap\->parameter( "value"); \& $imap\->parameter2("value"); .Ve .PP The eponymous accessor methods can also be used without arguments to obtain the current value of the parameter as follows: .PP .Vb 3 \& my $imap = Mail::IMAPClient\->new; \& $imap\->parameter( "value"); \& $imap\->parameter2("value"); \& \& ... # A whole bunch of awesome Perl code, omitted for brevity \& \& my $forgot = $imap\->parameter; \& my $forgot2 = $imap\->parameter2; .Ve .PP Note that in these examples I'm using 'parameter' and 'parameter2' as generic parameter names. The IMAPClient object doesn't actually have parameters named 'parameter' and 'parameter2'. On the contrary, the available parameters are: .SS "Authmechanism" .IX Subsection "Authmechanism" Example: .PP .Vb 3 \& $imap\->Authmechanism("CRAM\-MD5"); \& # or \& my $authmech = $imap\->Authmechanism(); .Ve .PP If specified, the \fIAuthmechanism\fR causes the specified authentication mechanism to be used whenever Mail::IMAPClient would otherwise invoke \&\fBlogin\fR. If the value specified for the \fIAuthmechanism\fR parameter is not a valid authentication mechanism for your server then you will never ever be able to log in again for the rest of your Perl script, probably. So you might want to check, like this: .PP .Vb 2 \& my $authmech = "CRAM\-MD5"; \& $imap\->has_capability($authmech) and $imap\->Authmechanism($authmech); .Ve .PP Of course if you know your server supports your favorite authentication mechanism then you know, so you can then include your \fIAuthmechanism\fR with your \fBnew\fR call, as in: .PP .Vb 7 \& my $imap = Mail::IMAPClient\->new( \& User => $user, \& Passord => $passord, \& Server => $server, \& Authmechanism => $authmech, \& %etc \& ); .Ve .PP If \fIAuthmechanism\fR is supplied but \fIAuthcallback\fR is not then you had better be supporting one of the authentication mechanisms that Mail::IMAPClient supports \*(L"out of the box\*(R" (such as \s-1CRAM\-MD5\s0). .SS "Authcallback" .IX Subsection "Authcallback" Example: .PP .Vb 1 \& $imap\->Authcallback( \e&callback ); .Ve .PP This specifies a default callback to the default authentication mechanism (see \*(L"Authmechanism\*(R", above). Together, these two methods replace automatic calls to login with automatic calls that look like this (sort of): .PP .Vb 1 \& $imap\->authenticate($imap\->Authmechanism,$imap\->Authcallback); .Ve .PP If \fIAuthmechanism\fR is supplied but \fIAuthcallback\fR is not then you had better be supporting one of the authentication mechanisms that Mail::IMAPClient supports \*(L"out of the box\*(R" (such as \s-1CRAM\-MD5\s0). .SS "Authuser" .IX Subsection "Authuser" The \fIAuthuser\fR parameter is used by the \s-1DIGEST\-MD5\s0 \*(L"Authmechanism\*(R". .PP Typically when you authenticate the username specified in the User parameter is used. However, when using the \s-1DIGEST\-MD5\s0 \&\fIAuthmechanism\fR the \fIAuthuser\fR can be used to specify a different username for the login. .PP This can be useful to mark messages as seen for the \fIAuthuser\fR if you don't know the password of the user as the seen state is often a per-user state. .SS "Buffer" .IX Subsection "Buffer" Example: .PP .Vb 3 \& $Buffer = $imap\->Buffer(); \& # or: \& $imap\->Buffer($new_value); .Ve .PP The \fIBuffer\fR parameter sets the size of a block of I/O. It is ignored unless \*(L"Fast_io\*(R", below, is set to a true value (the default), or unless you are using the \*(L"migrate\*(R" method. It's value should be the number of bytes to attempt to read in one I/O operation. The default value is 4096. .PP When using the \*(L"migrate\*(R" method, you can often achieve dramatic improvements in throughput by adjusting this number upward. However, doing so also entails a memory cost, so if set too high you risk losing all the benefits of the \*(L"migrate\*(R" method's chunking algorithm. Your program can thus terminate with an \*(L"out of memory\*(R" error and you'll have no one but yourself to blame. .PP Note that, as hinted above, the \fIBuffer\fR parameter affects the behavior of the \*(L"migrate\*(R" method regardless of whether you have \&\*(L"Fast_io\*(R" turned on. Believe me, you don't want to go around migrating tons of mail without using buffered I/O! .SS "Clear" .IX Subsection "Clear" Example: .PP .Vb 3 \& $Clear = $imap\->Clear(); \& # or: \& $imap\->Clear($integer); .Ve .PP The name of this parameter, for historical reasons, is somewhat misleading. It should be named \fIWrap\fR, because it specifies how many transactions are stored in the wrapped history buffer. But it didn't always work that way; the buffer used to actually get cleared. The name though remains the same in the interests of backwards compatibility. .PP \&\fIClear\fR specifies that the object's history buffer should be wrapped after every \fIn\fR transactions, where \fIn\fR is the value specified for the \fIClear\fR parameter. Calling the eponymous \fBClear\fR method without an argument will return the current value of the \fIClear\fR parameter but will not cause clear the history buffer to wrap. .PP Setting \fIClear\fR to 0 turns off automatic history buffer wrapping, and setting it to 1 turns off the history buffer facility (except for the last transaction, which cannot be disabled without breaking the IMAPClient module). Setting \fIClear\fR to 0 will not cause an immediate clearing of the history buffer; setting it to 1 (or any other number) will (except of course for that inevitable last transaction). .PP The default \fIClear\fR value is set to five (5) in order to conserve memory. .SS "Compress" .IX Subsection "Compress" If set, Mail::IMAPClient attempts to enable use of the \s-1RFC4978 COMPRESS DEFLATE\s0 extension. This requires that the server supports this \s-1CAPABILITY.\s0 This attribute can be set to a true value to enable or an \s-1ARRAYREF\s0 to control the arguments used in the call to \&\fBCompress::Zlib::deflateInit()\fR. .PP Mail::IMAPClient will automatically use Compress::Zlib to deflate/inflate the data to/from the server. This attribute is used in the \*(L"login\*(R" method. .PP See also \*(L"compress\*(R" and \*(L"capability\*(R". .PP Version note: attribute added in Mail::IMAPClient 3.30 .SS "Debug" .IX Subsection "Debug" Example: .PP .Vb 3 \& $Debug = $imap\->Debug(); \& # or: \& $imap\->Debug($true_or_false); .Ve .PP Sets the debugging flag to either a true or false value. Can be supplied with the \*(L"new\*(R" method call or separately by calling the \&\fBDebug\fR object method. Use of this parameter is strongly recommended when debugging scripts and required when reporting bugs. .SS "Debug_fh" .IX Subsection "Debug_fh" Example: .PP .Vb 3 \& $Debug_fh = $imap\->Debug_fh(); \& # or: \& $imap\->Debug_fh($fileHandle); .Ve .PP Specifies the file handle to which debugging information should be printed. It can either a file handle object reference or a file handle glob. The default is to print debugging info to \s-1STDERR.\s0 .PP For example, you can: .PP .Vb 8 \& use Mail::IMAPClient; \& use IO::File; \& # set $user, $pass, and $server here \& my $dh = IO::File\->new(">debugging.output") \& or die "Can\*(Aqt open debugging.output: $!\en"; \& my $imap = Mail::IMAPClient\->new( \& User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh \& ); .Ve .PP which is the same as: .PP .Vb 11 \& use Mail::IMAPClient; \& use IO::File; \& # set $user, $pass, and $server here \& my $imap = Mail::IMAPClient\->new( \& User => $user, \& Password => $pass, \& Server => $server, \& Debug => "yes, please", \& Debug_fh => IO::File\->new(">debugging.output") \& || die "Can\*(Aqt open debugging.output: $!\en" \& ); .Ve .PP You can also: .PP .Vb 7 \& use Mail::IMAPClient; \& # set $user, $pass, and $server here \& open(DBG,">debugging.output") \& or die "Can\*(Aqt open debugging.output: $!\en"; \& my $imap = Mail::IMAPClient\->new( \& User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG \& ); .Ve .PP Specifying this parameter is not very useful unless \*(L"Debug\*(R" is set to a true value. .SS "Domain" .IX Subsection "Domain" The \fIDomain\fR parameter is used by the \s-1NTLM\s0 \*(L"Authmechanism\*(R". The domain is an optional parameter for \s-1NTLM\s0 authentication. .SS "EnableServerResponseInLiteral" .IX Subsection "EnableServerResponseInLiteral" Removed in 2.99_01 (now autodetect) .SS "Fast_io" .IX Subsection "Fast_io" Example: .PP .Vb 3 \& $Fast_io = $imap\->Fast_io(); \& # or: \& $imap\->Fast_io($true_or_false); .Ve .PP The \fIFast_io\fR parameter controls whether or not the Mail::IMAPClient object will attempt to use non-blocking I/O on the \s-1IMAP\s0 socket. It is turned on by default (unless the caller provides the socket to be used). .PP See also \*(L"Buffer\*(R". .SS "Folder" .IX Subsection "Folder" Example: .PP .Vb 3 \& $Folder = $imap\->Folder(); \& # or: \& $imap\->Folder($new_value); .Ve .PP The \fIFolder\fR parameter returns the name of the currently-selected folder (in case you forgot). It can also be used to set the name of the currently selected folder, which is completely unnecessary if you used the \*(L"select\*(R" method (or \*(L"select\*(R"'s read-only equivalent, the \&\*(L"examine\*(R" method) to select it. .PP Note that setting the \fIFolder\fR parameter does not automatically select a new folder; you use the \*(L"select\*(R" or \*(L"examine\*(R" object methods for that. Generally, the \fIFolder\fR parameter should only be queried (by using the no-argument form of the \fBFolder\fR method). You will only need to set the \fIFolder\fR parameter if you use some mysterious technique of your own for selecting a folder, which you probably won't do. .SS "Ignoresizeerrors" .IX Subsection "Ignoresizeerrors" Certain (caching) servers, like Exchange 2007, often report the wrong message size. Instead of chopping the message into a size that it fits the specified size, the reported size will be simply ignored when this parameter is set to \f(CW1\fR. .SS "Keepalive" .IX Subsection "Keepalive" Some firewalls and network gear like to timeout connections prematurely if the connection sits idle. The \fBKeepalive\fR parameter, when set to a true value, affects the behavior of \*(L"new\*(R" and \&\*(L"Socket\*(R" by enabling \s-1SO_KEEPALIVE\s0 on the socket. .PP Version note: attribute added in Mail::IMAPClient 3.17 .SS "Maxcommandlength" .IX Subsection "Maxcommandlength" The \fBMaxcommandlength\fR attribute is used by \fBfetch()\fR to limit length of commands sent to a server. The default is 1000 chars, following the recommendation of \s-1RFC2683\s0 section 3.2.1.5. .PP \&\fBNote\fR: this attribute should also be used for several other methods but this has not yet been implemented please feel free to file bugs for methods where you run into problems with this. .PP This attribute should remove the need for utilities like imapsync to create their own \fBsplit()\fR functions and instead allows Mail::IMAPClient to \s-1DWIM.\s0 .PP In practice, this parameter has proven to be useful to overcome a limit of 8000 octets for UW-IMAPD and 16384 octets for Courier/Cyrus \&\s-1IMAP\s0 servers. .PP Version note: attribute added in Mail::IMAPClient 3.17 .SS "Maxtemperrors" .IX Subsection "Maxtemperrors" Example: .PP .Vb 3 \& $Maxtemperrors = $imap\->Maxtemperrors(); \& # or: \& $imap\->Maxtemperrors($number); .Ve .PP The \fIMaxtemperrors\fR parameter specifies the number of times a read or write operation is allowed to fail on a \*(L"Resource Temporarily Available\*(R" (e.g. \s-1EAGAIN\s0) error. The default setting is \fIundef\fR which means there is no limit. .PP Setting this parameter to the string \*(L"unlimited\*(R" (instead of undef) to ignore \*(L"Resource Temporarily Unavailable\*(R" errors is deprecated. .PP \&\fBNote\fR: This setting should be used with caution and may be removed in a future release. Setting this can cause methods to return to the caller before data is received (and then handled) properly thereby possibly then leaving the module in a bad state. In the future, this behavior may be changed in an attempt to avoid this situation. .SS "Password" .IX Subsection "Password" Example: .PP .Vb 3 \& $Password = $imap\->Password(); \& # or: \& $imap\->Password($new_value); .Ve .PP Specifies the password to use when logging into the \s-1IMAP\s0 service on the host specified in the \fIServer\fR parameter as the user specified in the \fIUser\fR parameter. Can be supplied with the \fBnew\fR method call or separately by calling the \fBPassword\fR object method. .PP If \fIServer\fR, \fIUser\fR, and \fIPassword\fR are all provided to the \*(L"new\*(R" method, then the newly instantiated object will be connected to the host specified in \fIServer\fR (at either the port specified in \fIPort\fR or the default port 143) and then logged on as the user specified in the \fIUser\fR parameter (using the password provided in the \fIPassword\fR parameter). See the discussion of the \*(L"new\*(R" method, below. .SS "Peek" .IX Subsection "Peek" Example: .PP .Vb 3 \& $Peek = $imap\->Peek(); \& # or: \& $imap\->Peek($true_or_false); .Ve .PP Setting \fIPeek\fR to a true value will prevent the \*(L"body_string\*(R", \&\*(L"message_string\*(R" and \*(L"message_to_file\*(R" methods from automatically setting the \fI\eSeen\fR flag. Setting \*(L"Peek\*(R" to 0 (zero) will force \&\*(L"body_string\*(R", \*(L"message_string\*(R", \*(L"message_to_file\*(R", and \&\*(L"parse_headers\*(R" to always set the \fI\eSeen\fR flag. .PP The default is to set the seen flag whenever you fetch the body of a message but not when you just fetch the headers. Passing \fIundef\fR to the eponymous \fBPeek\fR method will reset the \fIPeek\fR parameter to its pristine, default state. .SS "Port" .IX Subsection "Port" Example: .PP .Vb 3 \& $Port = $imap\->Port(); \& # or: \& $imap\->Port($new_value); .Ve .PP Specifies the port on which the \s-1IMAP\s0 server is listening. A default value of 993 (if \*(L"Ssl\*(R" is true) or 143 is set during a call to \&\*(L"connect\*(R" if no value is provided by the caller. This argument can be supplied with the \*(L"new\*(R" method call or separately by calling the \&\*(L"Port\*(R" object method. .SS "Prewritemethod" .IX Subsection "Prewritemethod" \&\fIPrewritemethod\fR parameter should contain a reference to a subroutine that will do \*(L"special things\*(R" to data before it is sent to the \s-1IMAP\s0 server (such as encryption or signing). .PP This method will be called immediately prior to sending an \s-1IMAP\s0 client command to the server. Its first argument is a reference to the \&\fIMail::IMAPClient\fR object and the second argument is a string containing the command that will be sent to the server. Your \&\fIPrewritemethod\fR should return a string that has been signed or encrypted or whatever; this returned string is what will actually be sent to the server. .PP Your \fIPrewritemethod\fR will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the \fIMail::IMAPClient\fR object itself. .PP Note that this method should not actually send anything over the socket connection to the server; it merely converts data prior to sending. .PP See also \*(L"Readmethod\*(R". .SS "Ranges" .IX Subsection "Ranges" Example: .PP .Vb 8 \& $imap\->Ranges(1); \& # or: \& my $search = $imap\->search(@search_args); \& if ( $imap\->Ranges) { # $search is a MessageSet object \& print "This is my condensed search result: $search\en"; \& print "This is every message in the search result: ", \& join(",",@$search),"\en; \& } .Ve .PP If set to a true value, then the \*(L"search\*(R" method will return a Mail::IMAPClient::MessageSet object if called in a scalar context, instead of the array reference that \fBfetch\fR normally returns when called in a scalar context. If set to zero or if undefined, then \&\fBsearch\fR will continue to return an array reference when called in scalar context. .PP This parameter has no affect on the \fBsearch\fR method when \fBsearch\fR is called in a list context. .SS "RawSocket" .IX Subsection "RawSocket" Example: \f(CW$socket\fR = \f(CW$imap\fR\->RawSocket; # or: \f(CW$imap\fR\->RawSocket($socketh); .PP The \fIRawSocket\fR method can be used to obtain the socket handle of the current connection (say, to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (for instance an \s-1SSL\s0 handle, see IO::Socket::SSL, but be sure to see the \*(L"Socket\*(R" method as well). .PP If you supply a socket handle yourself, either by doing something like: .PP .Vb 1 \& $imap=Mail::IMAPClient\->new(RawSocket => $sock, User => ... ); .Ve .PP or by doing something like: .PP .Vb 4 \& $imap = Mail::IMAPClient\->new(User => $user, \& Password => $pass, Server => $host); \& # blah blah blah \& $imap\->RawSocket($ssl); .Ve .PP then it will be up to you to establish the connection \s-1AND\s0 to authenticate, either via the \*(L"login\*(R" method, or the fancier \&\*(L"authenticate\*(R", or, since you know so much anyway, by just doing raw I/O against the socket until you're logged in. If you do any of this then you should also set the \*(L"State\*(R" parameter yourself to reflect the current state of the object (i.e. Connected, Authenticated, etc). .PP Note that no operation will be attempted on the socket when this method is called. In particular, after the \s-1TCP\s0 connections towards the \s-1IMAP\s0 server is established, the protocol mandates the server to send an initial greeting message, and you will have to explicitly cope with this message before doing any other operation, e.g. trying to call \*(L"login\*(R". Caveat emptor. .PP For a more \s-1DWIM\s0 approach to setting the socket see \*(L"Socket\*(R". .SS "Readmethod" .IX Subsection "Readmethod" Example: .PP .Vb 7 \& $imap\->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET \& sub { \& my ( $self, $handle, $buffer, $count, $offset ) = @_; \& my $rc = sysread( $handle, $$buffer, $count, $offset ); \& # do something useful here... \& } \& ); .Ve .PP \&\fBReadmethod\fR should contain a reference to a subroutine that will replace sysread. The subroutine will be passed the following arguments: first the used Mail::IMAPClient object. Second, a reference to a socket. Third, a reference to a scalar variable into which data is read (\s-1BUFFER\s0). The data placed here should be \*(L"finished data\*(R", so if you are decrypting or removing signatures then be sure to do that before you place data into this buffer. Fourth, the number of bytes requested to be read; the \s-1LENGTH\s0 of the request. Lastly, the \&\s-1OFFSET\s0 into the \s-1BUFFER\s0 where the data should be read. If not supplied it should default to zero. .PP Note that this method completely replaces reads from the connection to the server, so if you define one of these then your subroutine will have to actually do the read. It is for things like this that we have the \*(L"Socket\*(R" parameter and eponymous accessor method. .PP Your \fIReadmethod\fR will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the \fIMail::IMAPClient\fR object itself. .PP See also \*(L"Prewritemethod\*(R". .SS "Readmoremethod" .IX Subsection "Readmoremethod" \&\fBReadmoremethod\fR should contain a reference to a subroutine that will replace/enhance the behavior of the internal \fB_read_more()\fR method. The subroutine will be passed the following arguments: first the used Mail::IMAPClient object. Second, a reference to a socket. Third, a timeout value which is used as the timeout value for \fBCORE::select()\fR by default. Depending upon changes/features introduced by Readmethod changes may be required here. .PP Version note: attribute added in Mail::IMAPClient 3.30 .SS "Reconnectretry" .IX Subsection "Reconnectretry" If an \s-1IMAP\s0 connection sits idle too long, the connection may be closed by the server or firewall, etc. The \fBReconnectretry\fR parameter, when given a positive integer value, will cause Mail::IMAPClient to retrying \s-1IMAP\s0 commands up to X times when an \s-1EPIPE\s0 or \s-1ECONNRESET\s0 error occurs. This is disabled (0) by default. .PP See also \*(L"Keepalive\*(R" .PP Version note: attribute added in Mail::IMAPClient 3.17 .SS "Server" .IX Subsection "Server" Example: .PP .Vb 3 \& $Server = $imap\->Server(); \& # or: \& $imap\->Server($hostname); .Ve .PP Specifies the hostname or \s-1IP\s0 address of the host running the \s-1IMAP\s0 server. If provided as part of the \*(L"new\*(R" method call, then the new \&\s-1IMAP\s0 object will automatically be connected at the time of instantiation. (See the \*(L"new\*(R" method, below.) Can be supplied with the \*(L"new\*(R" method call or separately by calling the \fBServer\fR object method. .SS "Showcredentials" .IX Subsection "Showcredentials" Normally debugging output will mask the login credentials when the plain text login mechanism is used. Setting \fIShowcredentials\fR to a true value will suppress this, so that you can see the string being passed back and forth during plain text login. Only set this to true when you are debugging problems with the \s-1IMAP LOGIN\s0 command, and then turn it off right away when you're finished working on that problem. .PP Example: .PP .Vb 3 \& print "This is very risky!\en" if $imap\->Showcredentials(); \& # or: \& $imap\->Showcredentials(0); # mask credentials again .Ve .SS "Socket" .IX Subsection "Socket" \&\fB\s-1PLEASE NOTE\s0\fR The semantics of this method has changed as of version 2.99_04 of this module. If you need the old semantics use \&\*(L"RawSocket\*(R". .PP Example: .PP .Vb 3 \& $Socket = $imap\->Socket(); \& # or: \& $imap\->Socket($socket_fh); .Ve .PP The \fISocket\fR method can be used to obtain the socket handle of the current connection. This may be necessary to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (for instance an \s-1SSL\s0 handle, see IO::Socket::SSL). .PP If you supply a socket handle yourself, either by doing something like: .PP .Vb 1 \& $imap = Mail::IMAPClient\->new( Socket => $sock, User => ... ); .Ve .PP or by doing something like: .PP .Vb 4 \& $imap = Mail::IMAPClient\->new( \& User => $user, Password => $pass, Server => $host \& ); \& $imap\->Socket($ssl); .Ve .PP then you are responsible for establishing the connection, i.e. make sure that \f(CW$ssl\fR in the example is a valid and connected socket. .PP This method is primarily used to provide a drop-in replacement for IO::Socket::(INET|IP), used by \*(L"connect\*(R" by default. In fact, this method is called by \*(L"connect\*(R" itself after having established a suitable IO::Socket::(INET|IP) socket connection towards the target server; for this reason, this method also carries the normal operations associated with \*(L"connect\*(R", namely: .IP "\(bu" 4 read the initial greeting message from the server; .IP "\(bu" 4 call \*(L"login\*(R" if the conditions apply (see \*(L"connect\*(R" for details); .IP "\(bu" 4 leave the \fIMail::IMAPClient\fR object in a suitable state. .PP For these reasons, the following example will work \*(L"out of the box\*(R": .PP .Vb 10 \& use IO::Socket::SSL; \& my $imap = Mail::IMAPClient\->new \& ( User => \*(Aqyour\-username\*(Aq, \& Password => \*(Aqyour\-password\*(Aq, \& Socket => IO::Socket::SSL\->new \& ( Proto => \*(Aqtcp\*(Aq, \& PeerAddr => \*(Aqsome.imap.server\*(Aq, \& PeerPort => 993, # IMAP over SSL standard port \& ), \& ); .Ve .PP If you need more control over the socket, e.g. you have to implement a fancier authentication method, see \*(L"RawSocket\*(R". .SS "Starttls" .IX Subsection "Starttls" If an \s-1IMAP\s0 connection must start \s-1TLS/SSL\s0 after connecting to a server then set this attribute. If the value is set to an arrayref then they will be used as arguments to IO::Socket::SSL\->start_SSL. By default this connection is set to blocking while establishing the connection with a timeout of 30 seconds. The socket will be reset to the original blocking/non\-blocking value after a successful \s-1TLS\s0 negotiation has occurred. The arguments used in the call to start_SSL can be controlled by setting this attribute to an \s-1ARRAY\s0 reference containing the desired arguments. .PP Version note: attribute added in Mail::IMAPClient 3.22 .SS "Socketargs" .IX Subsection "Socketargs" The arguments used in the call to IO::Socket::{UNIX|INET|IP|SSL}\->new can be controlled by setting this attribute to an \s-1ARRAY\s0 reference containing the desired arguments. .PP For example, to always pass MultiHomed => 1 to IO::Socket::...\->new the following can be used: .PP .Vb 3 \& $imap = Mail::IMAPClient\->new( \& ..., Socketargs => [ MultiHomed => 1 ], ... \& ); .Ve .PP See also \*(L"Ssl\*(R" for specific control of the args to IO::Socket::SSL. .PP Version note: attribute added in Mail::IMAPClient 3.34 .SS "Ssl" .IX Subsection "Ssl" If an \s-1IMAP\s0 connection requires \s-1SSL\s0 you can set the Ssl attribute to \&'1' and Mail::IMAPClient will automatically use IO::Socket::SSL instead of IO::Socket::(INET|IP) to connect to the server. This attribute is used in the \*(L"connect\*(R" method. The arguments used in the call to IO::Socket::SSL\->new can be controlled by setting this attribute to an \s-1ARRAY\s0 reference containing the desired arguments. .PP See also \*(L"connect\*(R" for details on connection initiation and \&\*(L"Socket\*(R" and \*(L"Rawsocket\*(R" if you need to take more control of connection management. .PP Version note: attribute added in Mail::IMAPClient 3.18 .SS "Supportedflags" .IX Subsection "Supportedflags" Especially when \f(CW\*(C`migrate()\*(C'\fR is used, the receiving peer may need to be configured explicitly with the list of supported flags; that may be different from the source \s-1IMAP\s0 server. .PP The names are to be specified as an \s-1ARRAY.\s0 Black-slashes and casing will be ignored. .PP You may also specify a \s-1CODE\s0 reference, which will be called for each of the flags separately. In this case, the flags are not (yet) normalized. The returned lists of the \s-1CODE\s0 calls are shape the resulting flag list. .SS "Timeout" .IX Subsection "Timeout" Example: .PP .Vb 3 \& $Timeout = $imap\->Timeout(); \& # or: \& $imap\->Timeout($seconds); .Ve .PP Specifies the timeout value in seconds for reads (default is 600). Specifying a \fITimeout\fR will prevent Mail::IMAPClient from blocking in a read. .PP Since timeouts are implemented via the Perl select operator, the \fITimeout\fR parameter may be set to a fractional number of seconds. Setting \fITimeout\fR to 0 (zero) disables the timeout feature. .SS "Uid" .IX Subsection "Uid" Example: .PP .Vb 3 \& $Uid = $imap\->Uid(); \& # or: \& $imap\->Uid($true_or_false); .Ve .PP If \*(L"Uid\*(R" is set to a true value (i.e. 1) then the behavior of the \&\*(L"fetch\*(R", \*(L"search\*(R", \*(L"copy\*(R", and \*(L"store\*(R" methods (and their derivatives) is changed so that arguments that would otherwise be message sequence numbers are treated as message \s-1UID\s0's and so that return values (in the case of the \*(L"search\*(R" method and its derivatives) that would normally be message sequence numbers are instead message \s-1UID\s0's. .PP Internally this is implemented as a switch that, if turned on, causes methods that would otherwise issue an \s-1IMAP FETCH, STORE, SEARCH,\s0 or \&\s-1COPY\s0 client command to instead issue \s-1UID FETCH, UID STORE, UID SEARCH,\s0 or \s-1UID COPY,\s0 respectively. The main difference between message sequence numbers and message \s-1UID\s0's is that, according to \s-1RFC3501, UID\s0's must not change during a session and should not change between sessions, and must never be reused. Sequence numbers do not have that same guarantee and in fact may be reused right away. .PP Since folder names also have a unique identifier (\s-1UIDVALIDITY\s0), which is provided when the folder is \*(L"select\*(R"ed or \*(L"examine\*(R"d or by doing something like \*(L"$imap\->status($folder,\*(R"\s-1UIDVALIDITY"\s0), it is possible to uniquely identify every message on the server, although normally you won't need to bother. .PP The methods currently affected by turning on the \*(L"Uid\*(R" flag are: .PP .Vb 6 \& copy fetch \& search store \& message_string message_uid \& body_string flags \& move size \& parse_headers thread .Ve .PP Note that if for some reason you only want the \*(L"Uid\*(R" parameter turned on for one command, then you can choose between the following two snippets, which are equivalent: .PP Example 1: .PP .Vb 3 \& $imap\->Uid(1); \& my @uids = $imap\->search(\*(AqSUBJECT\*(Aq,"Just a silly test"); # \& $imap\->Uid(0); .Ve .PP Example 2: .PP .Vb 7 \& my @uids; \& foreach $r ($imap\->UID("SEARCH","SUBJECT","Just a silly test") { \& chomp $r; \& $r =~ s/\er$//; \& $r =~ s/^\e*\es+SEARCH\es+// or next; \& push @uids, grep(/\ed/,(split(/\es+/,$r))); \& } .Ve .PP In the second example, we used the default method to issue the \s-1UID IMAP\s0 client command, being careful to use an all-uppercase method name so as not to inadvertently call the \*(L"Uid\*(R" accessor method. Then we parsed out the message UIDs manually, since we don't have the benefit of the built-in \*(L"search\*(R" method doing it for us. .PP Please be very careful when turning the \*(L"Uid\*(R" parameter on and off throughout a script. If you loose track of whether you've got the \&\*(L"Uid\*(R" parameter turned on you might do something sad, like deleting the wrong message. Remember, like all eponymous accessor methods, the \&\fBUid\fR method without arguments will return the current value for the \&\*(L"Uid\*(R" parameter, so do yourself a favor and check. The safest approach is probably to turn it on at the beginning (or just let it default to being on) and then leave it on. (Remember that leaving it turned off can lead to problems if changes to a folder's contents cause resequencing.) .PP By default, the \*(L"Uid\*(R" parameter is turned on. .SS "User" .IX Subsection "User" Example: .PP .Vb 3 \& $User = $imap\->User(); \& # or: \& $imap\->User($userid); .Ve .PP Specifies the userid to use when logging into the \s-1IMAP\s0 service. Can be supplied with the \*(L"new\*(R" method call or separately by calling the \&\fBUser\fR object method. .PP Parameters can be set during \*(L"new\*(R" method invocation by passing named parameter/value pairs to the method, or later by calling the parameter's eponymous object method. .SH "Status Methods" .IX Header "Status Methods" There are several object methods that return the status of the object. They can be used at any time to check the status of an IMAPClient object, but are particularly useful for determining the cause of failure when a connection and login are attempted as part of a single \&\*(L"new\*(R" method invocation. The status methods are: .SS "Escaped_history" .IX Subsection "Escaped_history" Example: .PP .Vb 1 \& my @history = $imap\->Escaped_history; .Ve .PP The \fBEscaped_history\fR method is almost identical to the \fBHistory\fR method. Unlike the \fBHistory\fR method, however, server output transmitted literally will be wrapped in double quotes, with all double quotes, backslashes escaped. If called in a scalar context, \&\fBEscaped_history\fR returns an array reference rather than an array. .PP \&\fBEscaped_history\fR is useful if you are retrieving output and processing it manually, and you are depending on the above special characters to delimit the data. It is not useful when retrieving message contents; use \fBmessage_string\fR or \fBbody_string\fR for that. .SS "Escaped_results" .IX Subsection "Escaped_results" Example: .PP .Vb 1 \& my @results = $imap\->Escaped_results; .Ve .PP The \fBEscaped_results\fR method is almost identical to the \fBResults\fR method. Unlike the \fBResults\fR method, however, server output transmitted literally will be wrapped in double quotes, with all double quotes, backslashes escaped. If called in a scalar context, \&\fBEscaped_results\fR returns an array reference rather than an array. .PP \&\fBEscaped_results\fR is useful if you are retrieving output and processing it manually, and you are depending on the above special characters to delimit the data. It is not useful when retrieving message contents; use \fBmessage_string\fR or \fBbody_string\fR for that. .SS "History" .IX Subsection "History" Example: .PP .Vb 1 \& my @history = $imap\->History; .Ve .PP The \fBHistory\fR method is almost identical to the \*(L"Results\*(R" method. Unlike the \*(L"Results\*(R" method, however, the \s-1IMAP\s0 command that was issued to create the results being returned is not included in the returned results. If called in a scalar context, \fBHistory\fR returns an array reference rather than an array. .SS "IsUnconnected" .IX Subsection "IsUnconnected" returns a true value if the object is currently in an \*(L"Unconnected\*(R" state. .SS "IsConnected" .IX Subsection "IsConnected" returns a true value if the object is currently in either a \&\*(L"Connected\*(R", \*(L"Authenticated\*(R", or \*(L"Selected\*(R" state. .SS "IsAuthenticated" .IX Subsection "IsAuthenticated" returns a true value if the object is currently in either an \&\*(L"Authenticated\*(R" or \*(L"Selected\*(R" state. .SS "IsSelected" .IX Subsection "IsSelected" returns a true value if the object is currently in a \*(L"Selected\*(R" state. .SS "LastError" .IX Subsection "LastError" Internally \fBLastError\fR is implemented just like a parameter (as described in \*(L"Parameters\*(R", above). There is a \fILastError\fR attribute and an eponymous accessor method which returns the \&\fILastError\fR text string describing the last error condition encountered by the server. .PP Note that some errors are more serious than others, so \fILastError\fR's value is only meaningful if you encounter an error condition that you don't like. For example, if you use the \*(L"exists\*(R" method to see if a folder exists and the folder does not exist, then an error message will be recorded in \fILastError\fR even though this is not a particularly serious error. On the other hand, if you didn't use \&\*(L"exists\*(R" and just tried to \*(L"select\*(R" a non-existing folder, then \&\*(L"select\*(R" would return \f(CW\*(C`undef\*(C'\fR after setting \fILastError\fR to something like \f(CW\*(C`NO SELECT failed: Can\*(Aqt open mailbox "mailbox": no such mailbox\*(C'\fR. At this point it would be useful to print out the contents of \fILastError\fR as you die. .SS "LastIMAPCommand" .IX Subsection "LastIMAPCommand" New in version 2.0.4, \fBLastIMAPCommand\fR returns the exact \s-1IMAP\s0 command string to be sent to the server. Useful mainly in constructing error messages when \*(L"LastError\*(R" just isn't enough. .SS "Report" .IX Subsection "Report" The \fBReport\fR method returns an array containing a history of the \s-1IMAP\s0 session up to the point that \fBReport\fR was called. It is primarily meant to assist in debugging but can also be used to retrieve raw output for manual parsing. The value of the \*(L"Clear\*(R" parameter controls how many transactions are in the report. .SS "Results" .IX Subsection "Results" The \fBResults\fR method returns an array containing the results of one \&\s-1IMAP\s0 client command. It accepts one argument, the transaction number of the command whose results are to be returned. If transaction number is unspecified then \fBResults\fR returns the results of the last \&\s-1IMAP\s0 client command issued. If called in a scalar context, \fBResults\fR returns an array reference rather than an array. .SS "State" .IX Subsection "State" The \fBState\fR method returns a numerical value that indicates the current status of the IMAPClient object. If invoked with an argument, it will set the object's state to that value. If invoked without an argument, it behaves just like \*(L"Status\*(R", below. .PP Normally you will not have to invoke this function. An exception is if you are bypassing the Mail::IMAPClient module's \*(L"connect\*(R" and/or \&\*(L"login\*(R" modules to set up your own connection (say, for example, over a secure socket), in which case you must manually do what the \&\*(L"connect\*(R" and \*(L"login\*(R" methods would otherwise do for you. .SS "Status" .IX Subsection "Status" The \fBStatus\fR method returns a numerical value that indicates the current status of the IMAPClient object. (Not to be confused with the \&\*(L"status\*(R" method, all lower-case, which is the implementation of the \&\fI\s-1STATUS\s0\fR \s-1IMAP\s0 client command.) .SS "Transaction" .IX Subsection "Transaction" The \fBTransaction\fR method returns the tag value (or transaction number) of the last \s-1IMAP\s0 client command. .SH "Custom Authentication Mechanisms" .IX Header "Custom Authentication Mechanisms" If you just want to use plain text authentication or any of the supported \*(L"Advanced Authentication Mechanisms\*(R" then there is no need to read this section. .PP There are a number of methods and parameters that you can use to build your own authentication mechanism. All of the methods and parameters discussed in this section are described in more detail elsewhere in this document. This section provides a starting point for building your own authentication mechanism. .PP There are \fImany\fR authentication mechanisms out there, if your preferred mechanism is not currently supported but you manage to get it working please consider donating them to this module. Patches and suggestions are always welcome. .PP Support for add-on authentication mechanisms in Mail::IMAPClient is pretty straight forward. You create a callback to be used to provide the response to the server's challenge. The \*(L"Authcallback\*(R" parameter contains a reference to the callback, which can be an anonymous subroutine or a named subroutine. Then, you identify your authentication mechanism, either via the \*(L"Authmechanism\*(R" parameter or as an argument to \*(L"authenticate\*(R". .PP You may also need to provide a subroutine to encrypt (or whatever) data before it is sent to the server. The \*(L"Prewritemethod\*(R" parameter must contain a reference to this subroutine. And, you will need to decrypt data from the server; a reference to the subroutine that does this must be stored in the \*(L"Readmethod\*(R" parameter. .PP This framework is based on the assumptions that a) the mechanism you are using requires a challenge-response exchange, and b) the mechanism does not fundamentally alter the exchange between client and server but merely wraps the exchange in a layer of encryption. It also assumes that the line-oriented nature of the \s-1IMAP\s0 conversation is preserved; authentication mechanisms that break up messages into blocks of a predetermined size may still be possible but will certainly be more difficult to implement. .PP Alternatively, if you have access to \fBimtest\fR, a utility included in the Cyrus \s-1IMAP\s0 distribution, you can use that utility to broker your communications with the \s-1IMAP\s0 server. This is quite easy to implement. An example, \fIexamples/imtestExample.pl\fR, can be found in the \&\f(CW\*(C`examples\*(C'\fR subdirectory of the source distribution. .PP The following list summarizes the methods and parameters that you may find useful in implementing advanced authentication: .IP "The authenticate method" 4 .IX Item "The authenticate method" The \*(L"authenticate\*(R" method uses the \*(L"Authmechanism\*(R" parameter to determine how to authenticate with the server see the method documentation for details. .IP "Socket and RawSocket" 4 .IX Item "Socket and RawSocket" The \*(L"Socket\*(R" and \*(L"RawSocket\*(R" methods provide access to the socket connection. The socket is typically automatically created by the \&\*(L"connect\*(R" method, but if you are implementing an advanced authentication technique you may choose to set up your own socket connection and then set this parameter manually, bypassing the \&\fBconnect\fR method completely. This is also useful if you want to use IO::Socket::(INET|IP) alternatives like IO::Socket::SSL and need full control. .Sp \&\*(L"RawSocket\*(R" simply gets/sets the socket without attempting any interaction on it. In this case, you have to be sure to handle all the preliminary operations and manually set the Mail::IMAPClient object in sync with its actual status with respect to this socket (see below for additional parameters regarding this, especially the \&\*(L"State\*(R" parameter). .Sp Unlike \*(L"RawSocket\*(R", \*(L"Socket\*(R" attempts to carry on preliminary connection phases if the conditions apply. If both parameters are present, this takes the precedence over \*(L"RawSocket\*(R". If \&\*(L"Starttls\*(R" is set, then the \*(L"starttls\*(R" method will be called by \&\*(L"Socket\*(R". .Sp \&\fB\s-1PLEASE NOTE\s0\fR As of version 2.99_04 of this module, semantics for \&\*(L"Socket\*(R" have changed to make it more \*(L"\s-1DWIM\*(R".\s0 \*(L"RawSocket\*(R" was introduced as a replacement for the \*(L"Socket\*(R" parameter in older version. .IP "State, Server, User, Password, Proxy and Domain Parameters" 4 .IX Item "State, Server, User, Password, Proxy and Domain Parameters" If you need to make your own connection to the server and perform your authentication manually, then you can set these parameters to keep your Mail::IMAPClient object in sync with its actual status. Of these, only the \*(L"State\*(R" parameter is always necessary. The others need to be set only if you think your program will need them later. .IP "Authmechanism" 4 .IX Item "Authmechanism" Set this to the value that \s-1AUTHENTICATE\s0 should send to the server as the authentication mechanism. If you are brokering your own authentication then this parameter may be less useful. It exists primarily so that you can set it when you call \*(L"new\*(R" to instantiate your object. The \*(L"new\*(R" method will call \*(L"connect\*(R", which will call \*(L"login\*(R". If \*(L"login\*(R" sees that you have set an \&\fBAuthmechanism\fR then it will call \fBauthenticate\fR, using your \&\fBAuthmechanism\fR and \fBAuthcallback\fR parameters as arguments. .IP "Authcallback" 4 .IX Item "Authcallback" The \*(L"Authcallback\*(R", if set, holds a pointer to a subroutine (\s-1CODEREF\s0). The \*(L"login\*(R" method will use this as the callback argument to the \fBauthenticate\fR method if the \fBAuthmechanism\fR and \&\fBAuthcallback\fR parameters are both set. If you set \fBAuthmechanism\fR but not \fBAuthcallback\fR then the default callback for your mechanism will be used. All supported authentication mechanisms have a default callback; in every other case not supplying the callback results in an error. .Sp Most advanced authentication mechanisms require a challenge-response exchange. After the \*(L"authenticate\*(R" method sends \*(L" \s-1AUTHENTICATE\s0 \e015\e012\*(R" to the \s-1IMAP\s0 server, the server replies with a challenge. The \*(L"authenticate\*(R" method then invokes the code whose reference is stored in the \fBAuthcallback\fR parameter as follows: .Sp .Vb 1 \& $Authcallback\->( $challenge, $imap ) .Ve .Sp where \f(CW$Authcallback\fR is the code reference stored in the \&\fBAuthcallback\fR parameter, \f(CW$challenge\fR is the challenge received from the \s-1IMAP\s0 server, and \f(CW$imap\fR is a pointer to the Mail::IMAPClient object. The return value from the \fBAuthcallback\fR routine should be the response to the challenge, and that return value will be sent by the \*(L"authenticate\*(R" method to the server. .IP "Prewritemethod/Readmethod" 4 .IX Item "Prewritemethod/Readmethod" The \fBPrewritemethod\fR can hold a subroutine that will do whatever encryption is necessary and then return the result to the caller so it in turn can be sent to the server. .Sp The \fBReadmethod\fR can hold a subroutine to be used to replace \&\fBsysread\fR usually performed by Mail::IMAPClient. .Sp See \*(L"Prewritemethod\*(R" and \*(L"Readmethod\*(R" for details. .SH "REPORTING BUGS" .IX Header "REPORTING BUGS" Please file bug reports via https://github.com/plobbes/mail\-imapclient/issues .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .Vb 4 \& Copyright (C) 1999\-2003 The Kernen Group, Inc. \& Copyright (C) 2007\-2009 Mark Overmeer \& Copyright (C) 2010\-2021 Phil Pearl (Lobbes) \& All rights reserved. .Ve .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available. .PP This program is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the \&\s-1GNU\s0 General Public License or the Artistic License for more details.