{ "content": [ { "type": "text", "text": "# Mail::IMAPClient (perldoc)\n\n## NAME\n\nMail::IMAPClient - An IMAP Client API\n\n## SYNOPSIS\n\nuse Mail::IMAPClient;\nmy $imap = Mail::IMAPClient->new(\nServer => 'localhost',\nUser => 'username',\nPassword => 'password',\nSsl => 1,\nUid => 1,\n);\nmy $folders = $imap->folders\nor die \"List folders error: \", $imap->LastError, \"\\n\";\nprint \"Folders: @$folders\\n\";\n$imap->select( $Opt{folder} )\nor die \"Select '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n$imap->fetchhash(\"FLAGS\", \"INTERNALDATE\", \"RFC822.SIZE\")\nor die \"Fetch hash '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n$imap->logout\nor die \"Logout error: \", $imap->LastError, \"\\n\";\n\n## DESCRIPTION\n\nThis module provides methods implementing the IMAP protocol to support interacting with IMAP\nmessage stores.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (4 subsections)\n- **CLASS METHODS** (6 subsections)\n- **OBJECT METHODS**\n- **Mailbox Control Methods** (2 subsections)\n- **Other IMAP Client Commands**\n- **Parameters** (35 subsections)\n- **Status Methods** (14 subsections)\n- **Custom Authentication Mechanisms**\n- **REPORTING BUGS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Mail::IMAPClient", "section": "", "mode": "perldoc", "summary": "Mail::IMAPClient - An IMAP Client API", "synopsis": "use Mail::IMAPClient;\nmy $imap = Mail::IMAPClient->new(\nServer => 'localhost',\nUser => 'username',\nPassword => 'password',\nSsl => 1,\nUid => 1,\n);\nmy $folders = $imap->folders\nor die \"List folders error: \", $imap->LastError, \"\\n\";\nprint \"Folders: @$folders\\n\";\n$imap->select( $Opt{folder} )\nor die \"Select '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n$imap->fetchhash(\"FLAGS\", \"INTERNALDATE\", \"RFC822.SIZE\")\nor die \"Fetch hash '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n$imap->logout\nor die \"Logout error: \", $imap->LastError, \"\\n\";", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 23, "subsections": [] }, { "name": "DESCRIPTION", "lines": 15, "subsections": [ { "name": "Connection State", "lines": 11 }, { "name": "Advanced Authentication Mechanisms", "lines": 29 }, { "name": "Errors", "lines": 21 }, { "name": "Transactions", "lines": 20 } ] }, { "name": "CLASS METHODS", "lines": 45, "subsections": [ { "name": "Quote", "lines": 34 }, { "name": "Range", "lines": 23 }, { "name": "Rfc3501date", "lines": 10 }, { "name": "Rfc3501datetime", "lines": 11 }, { "name": "Rfc822date", "lines": 10 }, { "name": "Stripcr", "lines": 20 } ] }, { "name": "OBJECT METHODS", "lines": 30, "subsections": [] }, { "name": "Mailbox Control Methods", "lines": 371, "subsections": [ { "name": "message", "lines": 713 }, { "name": "Massage", "lines": 884 } ] }, { "name": "Other IMAP Client Commands", "lines": 31, "subsections": [] }, { "name": "Parameters", "lines": 31, "subsections": [ { "name": "Authmechanism", "lines": 30 }, { "name": "Authcallback", "lines": 14 }, { "name": "Authuser", "lines": 9 }, { "name": "Buffer", "lines": 20 }, { "name": "Clear", "lines": 24 }, { "name": "Compress", "lines": 12 }, { "name": "Debug", "lines": 10 }, { "name": "Debugfh", "lines": 46 }, { "name": "Domain", "lines": 3 }, { "name": "EnableServerResponseInLiteral", "lines": 2 }, { "name": "Fastio", "lines": 12 }, { "name": "Folder", "lines": 17 }, { "name": "Ignoresizeerrors", "lines": 4 }, { "name": "Keepalive", "lines": 6 }, { "name": "Maxcommandlength", "lines": 14 }, { "name": "Maxtemperrors", "lines": 18 }, { "name": "Password", "lines": 16 }, { "name": "Peek", "lines": 15 }, { "name": "Port", "lines": 11 }, { "name": "Prewritemethod", "lines": 19 }, { "name": "Ranges", "lines": 18 }, { "name": "RawSocket", "lines": 31 }, { "name": "Readmethod", "lines": 29 }, { "name": "Readmoremethod", "lines": 8 }, { "name": "Reconnectretry", "lines": 9 }, { "name": "Server", "lines": 11 }, { "name": "Showcredentials", "lines": 12 }, { "name": "Socket", "lines": 55 }, { "name": "Starttls", "lines": 10 }, { "name": "Socketargs", "lines": 13 }, { "name": "Ssl", "lines": 11 }, { "name": "Supportedflags", "lines": 9 }, { "name": "Timeout", "lines": 12 }, { "name": "Uid", "lines": 67 }, { "name": "User", "lines": 12 } ] }, { "name": "Status Methods", "lines": 5, "subsections": [ { "name": "Escapedhistory", "lines": 13 }, { "name": "Escapedresults", "lines": 13 }, { "name": "History", "lines": 9 }, { "name": "IsUnconnected", "lines": 2 }, { "name": "IsConnected", "lines": 3 }, { "name": "IsAuthenticated", "lines": 3 }, { "name": "IsSelected", "lines": 2 }, { "name": "LastError", "lines": 13 }, { "name": "LastIMAPCommand", "lines": 3 }, { "name": "Report", "lines": 5 }, { "name": "Results", "lines": 6 }, { "name": "State", "lines": 9 }, { "name": "Status", "lines": 4 }, { "name": "Transaction", "lines": 3 } ] }, { "name": "Custom Authentication Mechanisms", "lines": 106, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 13, "subsections": [] } ], "sections": { "NAME": { "content": "Mail::IMAPClient - An IMAP Client API\n", "subsections": [] }, "SYNOPSIS": { "content": "use Mail::IMAPClient;\n\nmy $imap = Mail::IMAPClient->new(\nServer => 'localhost',\nUser => 'username',\nPassword => 'password',\nSsl => 1,\nUid => 1,\n);\n\nmy $folders = $imap->folders\nor die \"List folders error: \", $imap->LastError, \"\\n\";\nprint \"Folders: @$folders\\n\";\n\n$imap->select( $Opt{folder} )\nor die \"Select '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n\n$imap->fetchhash(\"FLAGS\", \"INTERNALDATE\", \"RFC822.SIZE\")\nor die \"Fetch hash '$Opt{folder}' error: \", $imap->LastError, \"\\n\";\n\n$imap->logout\nor die \"Logout error: \", $imap->LastError, \"\\n\";\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides methods implementing the IMAP protocol to support interacting with IMAP\nmessage stores.\n\nThe module is used by constructing or instantiating a new IMAPClient object via the \"new\"\nconstructor method. Once the object has been instantiated, the \"connect\" method is either\nimplicitly or explicitly called. At that point methods are available that implement the IMAP\nclient commands as specified in RFC3501. When processing is complete, the \"logout\" object method\nshould be called.\n\nThis documentation is not meant to be a replacement for RFC3501 nor any other IMAP related RFCs.\n\nNote that this documentation uses the term *folder* in place of RFC3501's use of *mailbox*. This\ndocumentation reserves the use of the term *mailbox* to refer to the set of folders owned by a\nspecific IMAP id.\n", "subsections": [ { "name": "Connection State", "content": "RFC3501 defines four possible states for an IMAP connection: not authenticated, authenticated,\nselected, and logged out. These correspond to the IMAPClient constants \"Connected\",\n\"Authenticated\", \"Selected\", and \"Unconnected\", respectively. These constants can be used in\nconjunction with the \"Status\" method to determine the status of an IMAPClient object and its\nunderlying IMAP session.\n\nNote that an IMAPClient object can be in the \"Unconnected\" state both before a server connection\nis made and after it has ended. This differs slightly from RFC3501, which does not define a\npre-connection status. For a discussion of the methods available for examining the IMAPClient\nobject's status, see the section labeled \"Status Methods\", below.\n" }, { "name": "Advanced Authentication Mechanisms", "content": "RFC3501 defines two commands for authenticating to an IMAP server:\n\nLOGIN\nLOGIN is for plain text authentication.\n\nAUTHENTICATE\nAUTHENTICATE for more advanced and/or secure authentication mechanisms.\n\nMail::IMAPClient supports the following AUTHENTICATE mechanisms:\n\nDIGEST-MD5\nDIGEST-MD5 authentication requires the Authen::SASL and Digest::MD5 modules. See also\n\"Authuser\".\n\nCRAM-MD5\nCRAM-MD5 requires the Digest::HMACMD5 module.\n\nPLAIN (SASL)\nPLAIN (SASL) authentication allows the optional use of the \"Proxy\" parameter. RFC 4616\ndocuments this syntax for SASL PLAIN:\n\nmessage = [authzid] UTF8NUL authcid UTF8NUL passwd\n\nWhen \"Proxy\" is defined, \"User\" is used as 'authzid' and \"Proxy\" is used as 'authcid'.\nOtherwise, \"User\" is used as 'authcid'.\n\nNTLM\nNTLM authentication requires the Authen::NTLM module. See also \"Domain\".\n" }, { "name": "Errors", "content": "If you attempt an operation that results in an error, then you can retrieve the text of the\nerror message by using the \"LastError\" method. However, the \"LastError\" method is an object\nmethod (not a class method) and can only be used once an object is successfully created. In\ncases where an object is not successfully created the $@ variable is set with an error message.\n\nMail::IMAPClient resets $@ and \"LastError\" to undef before most IMAP requests, so the values\nonly have a short lifespan. \"LastError\" will always contain error info from the last error,\nuntil another error is encountered, another IMAP command is issued or it is explicitly cleared.\n\nPlease note that the use of $@ is subject to change in the future release so it is best to use\n\"LastError\" for error checking once a Mail::IMAPClient object has been created.\n\nErrors in the \"new\" method can prevent your object from ever being created. If the \"Server\",\n\"User\", and \"Password\" parameters are supplied to \"new\", it will attempt to call \"connect\" and\n\"login\". Any of these methods could fail and cause the \"new\" method call to return \"undef\" and\nleaving the variable $@ is set to an error message.\n\nWARNING: (due to historical API behavior) on errors, many methods may return undef regardless of\nLIST/SCALAR context. Therefore, it may be wise to use most methods in a scalar context.\nRegardless, check \"LastError\" for details on errors.\n" }, { "name": "Transactions", "content": "RFC3501 requires that each line in an IMAP conversation be prefixed with a tag. A typical\nconversation consists of the client issuing a tag-prefixed command string, and the server\nreplying with one of more lines of output. Those lines of output will include a command\ncompletion status code prefixed by the same tag as the original command string.\n\nThe IMAPClient module uses a simple counter to ensure that each client command is issued with a\nunique tag value. This tag value is referred to by the IMAPClient module as the transaction\nnumber. A history is maintained by the IMAPClient object documenting each transaction. The\n\"Transaction\" method returns the number of the last transaction, and can be used to retrieve\nlines of text from the object's history.\n\nThe \"Clear\" parameter is used to control the size of the session history so that long-running\nsessions do not eat up unreasonable amounts of memory. See the discussion of \"Clear\" parameter\nfor more information.\n\nThe \"Report\" transaction returns the history of the entire IMAP session since the initial\nconnection or for the last \"Clear\" transactions. This provides a record of the entire\nconversation, including client command strings and server responses, and is a wonderful\ndebugging tool as well as a useful source of raw data for custom parsing.\n" } ] }, "CLASS METHODS": { "content": "There are a couple of methods that can be invoked as class methods. Generally they can be\ninvoked as an object method as well. Note that if the \"new\" method is called as an object\nmethod, the object returned is identical to what have would been returned if \"new\" had been\ncalled as a class method. It doesn't give you a copy of the original object.\n\nnew\nExample:\n\nmy $imap = Mail::IMAPClient->new(%args)\nor die \"new failed: $@\\n\";\n\nThe \"new\" method creates a new instance of an IMAPClient object.\n\nIf the \"Server\" parameter is passed as an argument to new, then new will implicitly call the\n\"connect\" method, placing the new object in the *Connected* state. If \"User\" and \"Password\"\nvalues are also provided, then \"connect\" will in turn call \"login\", and the resulting object\nwill be returned from new in the *Authenticated* state.\n\nIf the \"Server\" parameter is not supplied then the IMAPClient object is created in the\n*Unconnected* state.\n\nIf the new method is passed arguments then those arguments will be treated as a list of\nkey=>value pairs. The key should be one of the parameters as documented under \"Parameters\"\nbelow.\n\nHere are some examples:\n\nuse Mail::IMAPClient;\n\n# returns an unconnected Mail::IMAPClient object:\nmy $imap = Mail::IMAPClient->new;\n# ...\n# intervening code using the 1st object, then:\n# (returns a new, authenticated Mail::IMAPClient object)\n$imap = Mail::IMAPClient->new(\nServer => $host,\nUser => $id,\nPassword => $pass,\nClear => 5, # Unnecessary since '5' is the default\n# ... # Other key=>value pairs go here\n) or die \"Cannot connect to $host as $id: $@\";\n\nSee also \"Parameters\", \"connect\" and \"login\" for more information on how to manually connect and\nlogin after new.\n", "subsections": [ { "name": "Quote", "content": "Example:\n\n$imap->search( HEADER => 'Message-id' => \\$imap->Quote($msgid) );\n\nThe Quote method accepts a value as an argument and returns its argument as a correctly quoted\nstring or a literal string. Since version 3.17 Mail::IMAPClient automatically quotes search\narguments we use a SCALARREF so search will not modify or re-quote the value returned by Quote.\n\nNote this method should not be used on folder names for Mail::IMAPClient methods, since methods\nthat accept folder names as an argument will quote the folder name arguments automatically.\n\nIf you are getting unexpected results when running methods with values that have (or might have)\nembedded spaces, double quotes, braces, or parentheses, then calling Quote may be necessary.\nThis method should not be used with arguments that are wrapped in quotes or parens if those\nquotes or parens are required by RFC3501. For example, if the RFC requires an argument in this\nformat:\n\n( argument )\n\nand the argument is (or might be) \"pennies (from heaven)\", then one could use:\n\n$argument = \"(\" . $imap->Quote($argument) . \")\"\n\nOf course, the fact that sometimes these characters are sometimes required delimiters is\nprecisely the reason you must quote them when they are *not* delimiting.\n\nHowever, there are times when a method fails unexpectedly and may require the use of Quote to\nwork. Should this happen, you can probably file a bug/enhancement request for Mail::IMAPClient\nto safeguard the particular call/case better.\n\nAn example is RFC822 Message-id's, which *usually* don't contain quotes or parens. When dealing\nwith these it is usually best to take proactive, defensive measures from the very start and use\nQuote.\n" }, { "name": "Range", "content": "Example:\n\nmy $parsed = $imap->parseheaders(\n$imap->Range( $imap->messages ), \"Date\", \"Subject\"\n);\n\nThe Range method will condense a list of message sequence numbers or message UID's into the most\ncompact format supported by RFC3501. It accepts one or more arguments, each of which can be:\n\na) a message number,\nb) a comma-separated list of message numbers,\nc) a colon-separated range of message numbers (i.e. \"$begin:$end\")\nd) a combination of messages and message ranges, separated by commas (i.e. 1,3,5:8,10), or\ne) a reference to an array whose elements are like *a)* through *d)*.\n\nThe Range method returns a Mail::IMAPClient::MessageSet object. The object uses overload and if\ntreated as a string it will act like a string. This means you can ignore its objectivity and\njust treat it like a string whose value is your message set expressed in compact format.\n\nThis method provides an easy way to add or remove messages from a message set.\n\nFor more information see Mail::IMAPClient::MessageSet.\n" }, { "name": "Rfc3501date", "content": "Example:\n\n$Rfc3501date = $imap->Rfc3501date($seconds);\n# or:\n$Rfc3501date = Mail::IMAPClient->Rfc3501date($seconds);\n\nThe Rfc3501date method accepts one input argument, a number of seconds since the epoch date. It\nreturns an RFC3501 compliant date string for that date (as required in date-related arguments to\nSEARCH, such as \"since\", \"before\", etc.).\n" }, { "name": "Rfc3501datetime", "content": "Example:\n\n$date = $imap->Rfc3501datetime($seconds);\n# or:\n$date = Mail::IMAPClient->Rfc3501datetime($seconds);\n\nThe Rfc3501datetime method accepts one or two arguments: a obligatory timestamp and an optional\nzone. The zone shall be formatted as \"[+-]\\d{4}\", and defaults to +0000. The timestamp follows\nthe definition of the output of the platforms specific \"time\", usually in seconds since Jan 1st\n1970. However, you have to correct the number yourself for the zone.\n" }, { "name": "Rfc822date", "content": "Example:\n\n$Rfc822date = $imap->Rfc822date($seconds);\n# or:\n$Rfc822date = Mail::IMAPClient->Rfc822date($seconds);\n\nThe Rfc822date method accepts one input argument, a number of seconds since the epoch date. It\nreturns an RFC822 compliant date string for that date (without the 'Date:' prefix). Useful for\nputting dates in message strings before calling \"append\", \"search\", etc.\n" }, { "name": "Stripcr", "content": "Examples:\n\nmy $stripped = $imap->Stripcr($string);\n# or:\nmy @list = $imap->someimapmethod;\n@list = $imap->Stripcr(@list);\n# or:\nmy $list = [ $imap->someimapmethod ]; # returns an array ref\n$list = $imap->Stripcr($list);\n\nThe Stripcr method strips carriage returns from input and returns the new string to the caller.\nThis method accepts one or more lines of text as arguments, and returns those lines with all\n sequences changed to . Any input argument with no carriage returns is returned\nunchanged. If the first argument (not counting the class name or object reference) is an array\nreference, then members of that array are processed as above and subsequent arguments are\nignored. If the method is called in scalar context then an array reference is returned instead\nof an array of results.\n\nNOTE: Stripcr does not remove new line characters.\n" } ] }, "OBJECT METHODS": { "content": "Object methods must be invoked against objects created via the \"new\" method and cannot be\ninvoked as class methods.\n\nThere object methods typically fall into one of two categories. There are mailbox methods which\nparticipate in the IMAP session's conversation (i.e. they issue IMAP client commands) and object\ncontrol methods which do not result in IMAP commands but which may affect later commands or\nprovide details of previous ones.\n\nThis object control methods can be further broken down into two types, Parameter accessor\nmethods, which affect the behavior of future mailbox methods, and \"Status Methods\", which report\non the affects of previous mailbox methods.\n\nMethods that do not result in new IMAP client commands being issued (such as the \"Transaction\",\n\"Status\", and \"History\" methods) all begin with an uppercase letter, to distinguish them from\nmethods that do correspond to IMAP client commands. Class methods and eponymous parameter\nmethods likewise begin with an uppercase letter because they also do not correspond to an IMAP\nclient command.\n\nAs a general rule, mailbox control methods return \"undef\" on failure and something besides\n\"undef\" when they succeed. This rule is modified in the case of methods that return search\nresults. When called in a list context, searches that do not find matching results return an\nempty list. When called in a scalar context, searches with no hits return 'undef' instead of an\narray reference. If you want to know why you received no hits, you should check \"LastError\" or\n$@, which will be empty if the search was successful but had no matching results but populated\nwith an error message if the search encountered a problem (such as invalid parameters).\n\nA number of IMAP commands do not have corresponding Mail::IMAPClient methods. Patches are\nwelcome. In the pre-2.99 releases of this module, they were automatically created (AUTOLOAD),\nbut that was very error-prone and stalled the progress of this module.\n", "subsections": [] }, "Mailbox Control Methods": { "content": "append\nExample:\n\nmy $uidortrue = $imap->append( $folder, $msgtext )\nor die \"Could not append: \", $imap->LastError;\n\nWARNING: This method may be deprecated in the future, consider using \"appendstring\" instead of\nthis method.\n\nThe append method adds a message to the specified folder. See \"appendstring\" for details as it\nis effectively an alias for that method.\n\nDEPRECATED BEHAVIOR: Additional arguments are added to the message text, separated with\n.\n\nappendstring\nExample:\n\n# brackets indicate optional arguments (not array refs):\nmy $uidort = $imap->appendstring( $folder, $msgtext [,$flags [,$date ] ] )\nor die \"Could not appendstring: \", $imap->LastError;\n\nArguments:\n\n$folder\nthe name of the folder to append the message to\n\n$msgtext\nthe message text (including headers) of the message\n\n$flags\nAn optional list of flags to set. The list must be specified as a space-separated list of\nflags, including any backslashes that may be necessary and optionally enclosed by\nparenthesis.\n\n$date\nAn optional RFC3501 date argument to set as the internal date. It should be in the format\ndescribed for *datetime* fields in RFC3501, i.e. \"dd-Mon-yyyy hh:mm:ss +0000\".\n\nIf you want to specify a date/time but you don't want any flags then specify *undef* as the\nthird ($flags) argument.\n\nReturns:\n\nerror: undef\nOn error, undef can be returned regardless of LIST/SCALAR context. Check \"LastError\" for\ndetails.\n\nsuccess: UID or $imap\nWith UIDPLUS the UID of the new message is returned otherwise a true value (currently $self)\nis returned.\n\nTo protect against \"bare newlines\", append will insert a carriage return before any newline that\nis \"bare\".\n\nappendfile\nExample:\n\nmy $newmsguid = $imap->appendfile(\n$folder,\n$file,\n[ undef, $flags, $date ] # optional\n) or die \"Could not appendfile: \", $imap->LastError;\n\nThe appendfile method adds a message to the specified folder. Note: The brackets in the example\nindicate optional arguments; they do not mean that the argument should be an array reference.\n\nArguments:\n\n$folder\nthe name of the folder to append the message to\n\n$file\na filename, filehandle or SCALAR reference which holds an RFC822-formatted message\n\nundef\na deprecated argument used as a place holder for backwards compatibility\n\n$flags\nThe optional argument is handled the same as appendstring.\n\n$date\nThe optional argument is handled the same as appendstring (RFC3501 date), with the\nexception that if $date is \"1\" (one) then the modification time (mtime) of the file will be\nused.\n\nReturns:\n\nerror: undef\nOn error, undef can be returned regardless of LIST/SCALAR context. Check \"LastError\" for\ndetails.\n\nsuccess: UID or $imap\nWith UIDPLUS the UID of the new message is returned otherwise a true value (currently $self)\nis returned.\n\nTo protect against \"bare newlines\", appendfile will insert a carriage return before any newline\nthat is \"bare\".\n\nThe appendfile method provides a mechanism for allowing large messages to be appended without\nholding the whole file in memory.\n\nVersion note: In 2.x an optional third argument to use for \"inputrecordseparator\" was allowed,\nhowever this argument is ignored/not supported as of 3.x.\n\nauthenticate\nExample:\n\n$imap->authenticate( $authenticationmechanism, $coderef )\nor die \"Could not authenticate: \", $imap->LastError;\n\nThis method implements the AUTHENTICATE IMAP client command. It can be called directly or may be\ncalled by \"login\" if the \"Authmechanism\" parameter is set to anything except 'LOGIN'.\n\nThe authenticate method accepts two arguments, an authentication type to be used (ie CRAM-MD5)\nand a code or subroutine reference to execute to obtain a response. The authenticate method\nassumes that the authentication type specified in the first argument follows a\nchallenge-response flow. The authenticate method issues the IMAP Client AUTHENTICATE command and\nreceives a challenge from the server. That challenge (minus any tag prefix or enclosing '+'\ncharacters but still in the original base64 encoding) is passed as the only argument to the code\nor subroutine referenced in the second argument. The return value from the 2nd argument's code\nis written to the server as is, except that a sequence is appended if necessary.\n\nIf one or both of the arguments are not specified in the call to authenticate but their\ncorresponding parameters have been set (\"Authmechanism\" and \"Authcallback\", respectively) then\nthe parameter values are used. Arguments provided to the method call however will override\nparameter settings.\n\nIf you do not specify a second argument and you have not set the \"Authcallback\" parameter, then\nthe first argument must be one of the authentication mechanisms for which Mail::IMAPClient has\nbuilt in support.\n\nSee also the \"login\" method, which is the simplest form of authentication defined by RFC3501.\n\nbefore\nExample:\n\nmy @msgs = $imap->before($Rfc3501date)\nor warn \"No messages found before $Rfc3501date.\\n\";\n\nThe before method works just like the \"since\" method, below, except it returns a list of\nmessages whose internal system dates are before the date supplied as the argument to the before\nmethod.\n\nbodystring\nExample:\n\nmy $string = $imap->bodystring($msgId)\nor die \"bodystring failed: \", $imap->LastError;\n\nThe bodystring method accepts a message sequence number (or a message UID, if the \"Uid\"\nparameter is set to true) as an argument and returns the message body as a string. The returned\nvalue contains the entire message in one scalar variable, without the message headers.\n\nbodypartstring\nExample:\n\nmy $string = $imap->bodypartstring(\n$msgid, $partnumber, $length, $offset\n) or die \"Could not get bodypart string: \", $imap->LastError;\n\nThe bodypartstring method accepts a message sequence number (or a message UID, if the \"Uid\"\nparameter is set to true) and a body part as arguments and returns the message part as a string.\nThe returned value contains the entire message part (or, optionally, a portion of the part) in\none scalar variable.\n\nIf an optional third argument is provided, that argument is the number of bytes to fetch. (The\ndefault is the whole message part.) If an optional fourth argument is provided then that fourth\nargument is the offset into the part at which the fetch should begin. The default is offset\nzero, or the beginning of the message part.\n\nIf you specify an offset without specifying a length then the offset will be ignored and the\nentire part will be returned.\n\nbodypartstring will return \"undef\" if it encounters an error.\n\ncapability\nExample:\n\nmy $features = $imap->capability\nor die \"Could not determine capability: \", $imap->LastError;\n\nThe capability method returns an array (or arrayref in scalar context) of capabilities as\nreturned by the CAPABILITY IMAP client command. If the CAPABILITY IMAP client command fails for\nany reason then the capability method will return \"undef\". Supported capabilities are cached by\nthe client, however, this cache is deleted after a connection is set to *Authenticated* and when\n\"starttls\" is called.\n\nSee also \"hascapability\".\n\nclose\nExample:\n\n$imap->close or die \"Could not close: $@\\n\";\n\nThe close method is used to close the currently selected folder via the CLOSE IMAP client\ncommand. According to RFC3501, the CLOSE command performs an implicit EXPUNGE, which means that\nany messages that are flagged as *\\Deleted* (i.e. with the \"deletemessage\" method) will now be\ndeleted. If you haven't deleted any messages then close can be thought of as an \"unselect\".\n\nNote: this closes the currently selected folder, not the IMAP session.\n\nSee also \"deletemessage\", \"expunge\", and RFC3501.\n\ncompress\nExample:\n\n$imap->compress or die \"Could not enable RFC4978 compression: $@\\n\";\n\nThe compress method accepts no arguments. This method is used to instruct the server to use the\nDEFLATE (RFC1951) compression extension. See the \"Compress\" attribute for how to specify\narguments for use during the initialization process.\n\nVersion note: method added in Mail::IMAPClient 3.30\n\nconnect\nExample:\n\n$imap->connect or die \"Could not connect: $@\\n\";\n\nThe connect method connects an imap object to the server. It returns \"undef\" if it fails to\nconnect for any reason. If values are available for the \"User\" and \"Password\" parameters at the\ntime that connect is invoked, then connect will call the \"login\" method after connecting and\nreturn the result of the \"login\" method to connect's caller. If either or both of the \"User\" and\n\"Password\" parameters are unavailable but the connection to the server succeeds then connect\nreturns a pointer to the IMAPClient object.\n\nThe \"Server\" parameter must be set (either during \"new\" method invocation or via the \"Server\"\nobject method) before invoking connect. When the parameter is an absolute file path, an UNIX\nsocket will get opened. If the \"Server\" parameter is supplied to the \"new\" method then connect\nis implicitly called during object construction.\n\nThe connect method sets the state of the object to \"Connected\" if it successfully connects to\nthe server. It returns \"undef\" on failure.\n\ncopy\nExample:\n\n# Here brackets indicate optional arguments:\nmy $uidList = $imap->copy($folder, $msg1 [ , ... , $msgn ])\nor die \"Could not copy: $@\\n\";\n\nOr:\n\n# Now brackets indicate an array ref!\nmy $uidList = $imap->copy($folder, [ $msg1, ... , $msgn ])\nor die \"Could not copy: $@\\n\";\n\nThe copy method requires a folder name as the first argument, and a list of one or more messages\nsequence numbers (or messages UID's, if the *UID* parameter is set to a true value). The message\nsequence numbers or UID's should refer to messages in the currently selected folder. Those\nmessages will be copied into the folder named in the first argument.\n\nThe copy method returns \"undef\" on failure and a true value if successful. If the server to\nwhich the current Mail::IMAPClient object is connected supports the UIDPLUS capability then the\ntrue value returned by copy will be a comma separated list of UID's, which are the UID's of the\nnewly copied messages in the target folder.\n\ncreate\nExample:\n\n$imap->create($newfolder)\nor die \"Could not create $newfolder: $@\\n\";\n\nThe create method accepts one argument, the name of a folder (or what RFC3501 calls a \"mailbox\")\nto create. If you specify additional arguments to the create method and your server allows\nadditional arguments to the CREATE IMAP client command then the extra argument(s) will be passed\nto your server.\n\nIf you specify additional arguments to the create method and your server does not allow\nadditional arguments to the CREATE IMAP client command then the extra argument(s) will still be\npassed to your server and the create will fail.\n\ncreate returns a true value on success and \"undef\" on failure.\n\ndate\nExample:\n\nmy $date = $imap->date($msg);\n\nThe date method accepts one argument, a message sequence number (or a message UID if the \"Uid\"\nparameter is set to a true value). It returns the date of message as specified in the message's\nRFC822 \"Date: \" header, without the \"Date: \" prefix.\n\nThe date method is a short-cut for:\n\nmy $date = $imap->getheader($msg,\"Date\");\n\ndelete\nExample:\n\n$imap->delete($folder) or die \"Could not delete $folder: $@\\n\";\n\nThe delete method accepts a single argument, the name of a folder to delete. It returns a true\nvalue on success and \"undef\" on failure.\n\ndeleteacl\nExample:\n\n$imap->deleteacl( $folder, $userid )\nor die \"Could not delete acl: $@\\n\";\n\nThe deleteacl method accepts two input arguments, a folder name, a user id (or authentication\nidentifier, to use the terminology of RFC2086). See RFC2086 for more information. (This is\nsomewhat experimental and its implementation may change.)\n\ndeletemessage\nExample:\n\nmy @msgs = $imap->seen;\nscalar(@msgs) and $imap->deletemessage(\\@msgs)\nor die \"Could not deletemessage: $@\\n\";\n\nThe above could also be rewritten like this:\n\n# scalar context returns array ref\nmy $msgs = scalar($imap->seen);\n\nscalar(@$msgs) and $imap->deletemessage($msgs)\nor die \"Could not deletemessage: $@\\n\";\n\nOr, as a one-liner:\n\n$imap->deletemessage( scalar($imap->seen) )\nor warn \"Could not deletemessage: $@\\n\";\n# just give warning in case failure is\n# due to having no 'seen' msgs in the 1st place!\n\nThe deletemessage method accepts a list of arguments. If the \"Uid\" parameter is not set to a\ntrue value, then each item in the list should be either:\n\n* a message sequence number,\n\n* a comma-separated list of message sequence numbers,\n\n* a reference to an array of message sequence numbers, or\n\nIf the \"Uid\" parameter is set to a true value, then each item in the list should be either:\n\n* a message UID,\n\n* a comma-separated list of UID's, or\n\n* a reference to an array of message UID's.\n\nThe messages identified by the sequence numbers or UID's will be deleted. If successful,\ndeletemessage returns the number of messages it was told to delete. However, since the delete\nis done by issuing the *+FLAGS.SILENT* option of the STORE IMAP client command, there is no\nguarantee that the delete was successful for every message. In this manner the deletemessage\nmethod sacrifices accuracy for speed. Generally, though, if a single message in a list of\nmessages fails to be deleted it's because it was already deleted, which is what you wanted\nanyway so why worry about it? If there is a more severe error, i.e. the server replies \"NO\",\n\"BAD\", or, banish the thought, \"BYE\", then deletemessage will return \"undef\".\n\nIf you must have guaranteed results then use the IMAP STORE client command (via the default\nmethod) and use the +FLAGS (\\Deleted) option, and then parse your results manually.\n\nEg:\n\n$imap->store( $msgid, '+FLAGS (\\Deleted)' );\nmy @results = $imap->History( $imap->Transaction );\n... # code to parse output goes here\n\n(Frankly I see no reason to bother with any of that; if a message doesn't get deleted it's\nalmost always because it's already not there, which is what you want anyway. But 'your mileage\nmay vary' and all that.)\n\nThe IMAPClient object must be in \"Selected\" status to use the deletemessage method.\n\nNOTE: All the messages identified in the input argument(s) must be in the currently selected\nfolder. Failure to comply with this requirement will almost certainly result in the wrong", "subsections": [ { "name": "message", "content": "ADDITIONAL NOTE: In the grand tradition of the IMAP protocol, deleting a message doesn't\nactually delete the message. Really. If you want to make sure the message has been deleted, you\nneed to expunge the folder (via the \"expunge\" method, which is implemented via the default\nmethod). Or at least \"close\" it. This is generally considered a feature, since after deleting a\nmessage, you can change your mind and undelete it at any time before your \"expunge\" or \"close\".\n\nSee also: the \"delete\" method, to delete a folder, the \"expunge\" method, to expunge a folder,\nthe \"restoremessage\" method to undelete a message, and the \"close\" method (implemented here via\nthe default method) to close a folder. Oh, and don't forget about RFC3501.\n\ndenyseeing\nExample:\n\n# Reset all read msgs to unread\n# (produces error if there are no seen msgs):\n$imap->denyseeing( scalar($imap->seen) )\nor die \"Could not denyseeing: $@\\n\";\n\nThe denyseeing method accepts a list of one or more message sequence numbers, or a single\nreference to an array of one or more message sequence numbers, as its argument(s). It then\nunsets the \"\\Seen\" flag for those messages (so that you can \"deny\" that you ever saw them). Of\ncourse, if the \"Uid\" parameter is set to a true value then those message sequence numbers should\nbe unique message id's.\n\nNote that specifying \"$imap->denyseeing(@msgs)\" is just a shortcut for specifying\n\"$imap->unsetflag(\"Seen\",@msgs)\".\n\ndisconnect\nExample:\n\n$imap->disconnect or warn \"Could not logout: $@\\n\";\n\nThis method calls \"logout\", see \"logout\" for details.\n\ndone\nExample:\n\nmy $tag = $imap->idle or warn \"idle failed: $@\\n\";\ndoSomethingA();\nmy $idlemsgs = $imap->idledata() or warn \"idledata error: $@\\n\";\ndoSomethingB();\nmy $results = $imap->done($tag) or warn \"Error from done: $@\\n\";\n\nThe done method tells the IMAP server to terminate the IDLE command. The only argument is the\n*tag* (identifier) received from the previous call to \"idle\". If *tag* is not specified a\ndefault *tag* based on the Count attribute is assumed to be the *tag* to look for in the\nresponse from the server.\n\nIf an invalid *tag* is specified, or the default *tag* is wrong, then done will hang\nindefinitely or until a timeout occurs.\n\nIf done is called when an \"idle\" command is not active then the server will likely respond with\nan error like BAD Invalid tag*.\n\nOn failure is returned and \"LastError\" is set.\n\nSee also \"idle\", \"idledata\" and \"Results\".\n\nexamine\nExample:\n\n$imap->examine($folder) or die \"Could not examine: $@\\n\";\n\nThe examine method selects a folder in read-only mode and changes the object's state to\n\"Selected\". The folder selected via the examine method can be examined but no changes can be\nmade unless it is first selected via the \"select\" method.\n\nThe examine method accepts one argument, which is the name of the folder to select.\n\nexists\nExample:\n\n$imap->exists($folder) or warn \"$folder not found: $@\\n\";\n\nAccepts one argument, a folder name. Returns true if the folder exists or false if it does not\nexist.\n\nexpunge\nExample:\n\n$imap->expunge($folder) or die \"Could not expunge: $@\\n\";\n\nThe expunge method accepts one optional argument, a folder name. It expunges the folder\nspecified as the argument, or the currently selected folder (if any) when no argument is\nsupplied.\n\nAlthough RFC3501 does not permit optional arguments (like a folder name) to the EXPUNGE client\ncommand, the \"expunge\" method does. Note: expunging a folder deletes the messages that have the\n\\Deleted flag set (i.e. messages flagged via \"deletemessage\").\n\nSee also the \"close\" method, which \"deselects\" as well as expunges.\n\nfetch\nUsage:\n\n$imap->fetch( [$seqset|ALL], @msgdataitems )\n\nExample:\n\nmy $output = $imap->fetch(@args) or die \"Could not fetch: $@\\n\";\n\nThe fetch method implements the FETCH IMAP client command. It accepts a list of arguments, which\nwill be converted into a space-delimited list of arguments to the FETCH IMAP client command. If\nno arguments are supplied then fetch does a FETCH ALL. If the \"Uid\" parameter is set to a true\nvalue then the first argument will be treated as a UID or list of UID's, which means that the\nUID FETCH IMAP client command will be run instead of FETCH. (It would really be a good idea at\nthis point to review RFC3501.)\n\nIf called in array context, fetch will return an array of output lines. The output lines will be\nreturned just as they were received from the server, so your script will have to be prepared to\nparse out the bits you want. The only exception to this is literal strings, which will be\ninserted into the output line at the point at which they were encountered (without the {nnn}\nliteral field indicator). See RFC3501 for a description of literal fields.\n\nIf fetch is called in a scalar context, then a reference to an array (as described above) is\nreturned instead of the entire array.\n\nfetch returns \"undef\" on failure. Inspect \"LastError\" or $@ for an explanation of your error.\n\nfetchhash\nUsage:\n\n$imap->fetchhash( [$seqset|ALL], @msgdataitems, [\\%msgbyids] )\n\nExamples:\n\nmy $hashref = $imap->fetchhash(\"RFC822.SIZE\");\n\nOR\n\nmy $hashref = {};\n$imap->fetchhash( \"RFC822.SIZE\", $hashref );\nprint \"Msg #$ is $hashref->{$}->{'RFC822.SIZE'} bytes\\n\" for (keys %$hashref);\n\nThe fetchhash method accepts a list of message attributes to be fetched (as described in\nRFC3501). It returns a hash whose keys are all the messages in the currently selected folder and\nwhose values are key-value pairs of fetch keywords and the message's value for that keyword (see\nsample output below).\n\nIf fetchhash is called in scalar context, it returns a reference to the hash instead of the\nhash itself. If the last argument is a hash reference, then that hash reference will be used as\nthe place where results are stored (and that reference will be returned upon successful\ncompletion). If the last argument is not a reference then it will be treated as one of the FETCH\nattributes and a new hash will be created and returned (either by value or by reference,\ndepending on the context in which fetchhash was called).\n\nFor example, if you have a folder with 3 messages and want the size and internal date for each\nof them, you could do the following:\n\nuse Mail::IMAPClient;\nuse Data::Dumper;\n# ... other code goes here\n$imap->select($folder);\nmy $hash = $imap->fetchhash( \"RFC822.SIZE\", \"INTERNALDATE\" );\n# (Same as:\n# my $hash = $imap->fetchhash(\"RFC822.SIZE\");\n# $imap->fetchhash( \"INTERNALDATE\", $hash );\n# ).\nprint Data::Dumper->Dumpxs( [$hash], ['$hash'] );\n\nThis would result in Data::Dumper output similar to the following:\n\n$hash = {\n'1' => {\n'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',\n'RFC822.SIZE' => '1586',\n},\n'2' => {\n'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',\n'RFC822.SIZE' => '1945',\n},\n'3' => {\n'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',\n'RFC822.SIZE' => '134314',\n}\n};\n\nBy itself this method may be useful for tasks like obtaining the size of every message in a\nfolder. It issues one command and receives one (possibly long!) response from the server.\n\nIf the fetch request causes the server to return data in a parenthesized list, the data within\nthe parenthesized list may be escaped via the Escape() method. Use the Unescape() method to get\nthe raw values back in this case.\n\nflags\nExample:\n\nmy $flags = $imap->flags($msgid)\nor die \"flags failed: $@\\n\";\n\nThe flags method implements the FETCH IMAP client command to list a single message's flags. It\naccepts one argument, a message sequence number (or a message UID, if the \"Uid\" parameter is\ntrue), and returns an array (or a reference to an array, if called in scalar context) listing\nthe flags that have been set. Flag names are provided with leading backslashes.\n\nAs of version 1.11, you can supply either a list of message id's or a reference to an array of\nmessage id's (which means either sequence number, if the Uid parameter is false, or message\nUID's, if the Uid parameter is true) instead of supplying a single message sequence number or\nUID. If you do, then the return value will not be an array or array reference; instead, it will\nbe a hash reference, with each key being a message sequence number (or UID) and each value being\na reference to an array of flags set for that message.\n\nFor example, if you want to display the flags for every message in the folder where you store\ne-mail related to your plans for world domination, you could do something like this:\n\nuse Mail::IMAPClient;\nmy $imap = Mail::IMAPClient->new(\nServer => $imaphost,\nUser => $login,\nPassword => $pass,\nUid => 1, # optional\n);\n\n$imap->select(\"World Domination\");\n# get the flags for every message in my 'World Domination' folder\n$flaghash = $imap->flags( scalar( $imap->search(\"ALL\") ) );\n\n# pump through sorted hash keys to print results:\nfor my $k ( sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash ) {\n# print: Message 1: \\Flag1, \\Flag2, \\Flag3\nprint \"Message $k:\\t\", join( \", \", @{$flaghash->{$k}} ), \"\\n\";\n}\n\nfolders\nExample:\n\n$imap->folders or die \"Could not list folders: $@\\n\";\n\nThe folders method returns an array listing the available folders. It will only be successful if\nthe object is in the *Authenticated* or *Selected* states.\n\nThe folders method accepts one optional argument, which is a prefix. If a prefix is supplied to\nthe folders method, then only folders beginning with the prefix will be returned.\n\nFor example:\n\nprint join( \", \", $imap->folders ), \".\\n\";\n# Prints:\n# INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.\nprint join( \", \", $imap->folders(\"Projects\") ), \".\\n\";\n# Prints:\n# Projects, Projects/Completed, Projects/Ongoing, Projects Software.\nprint join( \", \", $imap->folders(\"Projects\" . $imap->separator) ), \".\\n\";\n# Prints:\n# Projects/Completed, Projects/Ongoing\n\nPlease note that documentation previously suggested that if you just want to list a folder's\nsubfolders (and not the folder itself), then you need to include the hierarchy separator\ncharacter (as returned by the \"separator\" method). However, this does not match the behavior of\nthe existing implementation, so you will need to manually exclude the parent folder from the\nresults.\n\nfoldershash\nmy @fhashes = $imap->foldershash\nor die \"Could not get list of folder hashes.\\n\";\n\nThe foldershash method accepts one optional argument, which is a prefix. If a prefix is\nsupplied to the foldershash method, then only folders beginning with the prefix will be\nreturned.\n\nAn array(ref) of hashes is returned that contain information about the requested folders. Each\nhash contains three keys (name, attrs, delim) and looks like the following:\n\n{\nname => 'Mail/Box/Name',\nattrs => [ '\\Marked', '\\HasNoChildren' ],\ndelim => '/',\n}\n\nIMAP servers implementing RFC6154 return attributes to be used to identify special-use mailboxes\n(folders).\n\nmy $sattrre = /\\A\\\\(?:All|Archive|Drafts|Flagged|Junk|Sent|Trash)\\Z/;\nforeach my $fhash (@fhashes) {\nnext unless defined $fhash->{name};\nmy @special = grep { $sattrre } @{ $fhash->{attrs} };\nprint(\"special: $fhash->{name} : @special\\n\") if (@special);\n}\n\nVersion note: method added in Mail::IMAPClient 3.34\n\nxlistfolders (DEPRECATED)\nThis method is deprecated as of version 3.34. Please use foldershash instead. See RFC6154 for\nattributes to be used to identify special-use mailboxes (folders).\n\nExample:\n\nmy $xlist = $imap->xlistfolders\nor die \"Could not get xlist folders.\\n\";\n\nIMAP servers implementing the XLIST extension (such as Gmail) designate particular folders to be\nused for particular functions. This is useful in the case where you want to know which folder\nshould be used for Trash when the actual folder name can't be predicted (e.g. in the case of\nGmail, the folder names change depending on the user's locale settings).\n\nThe xlistfolders method returns a hash listing any \"xlist\" folder names, with the values\nlisting the actual folders that should be used for those names. For example, using this method\nwith a Gmail user using the English (US) locale might give this output from Data::Dumper:\n\n$VAR1 = {\n'Inbox' => 'Inbox',\n'AllMail' => '[Gmail]/All Mail',\n'Trash' => '[Gmail]/Trash',\n'Drafts' => '[Gmail]/Drafts',\n'Sent' => '[Gmail]/Sent Mail',\n'Spam' => '[Gmail]/Spam',\n'Starred' => '[Gmail]/Starred'\n};\n\nThe same list for a user using the French locale might look like this:\n\n$VAR1 = {\n'Inbox' => 'Bo&AO4-te de r&AOk-ception',\n'AllMail' => '[Gmail]/Tous les messages',\n'Trash' => '[Gmail]/Corbeille',\n'Drafts' => '[Gmail]/Brouillons',\n'Sent' => '[Gmail]/Messages envoy&AOk-s',\n'Spam' => '[Gmail]/Spam',\n'Starred' => '[Gmail]/Suivis'\n};\n\nMail::IMAPClient recognizes the following \"xlist\" folder names:\n\nInbox\nAllMail\nTrash\nDrafts\nSent\nSpam\nStarred\n\nThese are currently the only ones supported by Gmail. The XLIST extension is not documented, and\nthere are no other known implementations other than Gmail, so this list is based on what Gmail\nprovides.\n\nIf the server does not support the XLIST extension, this method returns undef.\n\nVersion note: method added in Mail::IMAPClient 3.21\n\nhascapability\nExample:\n\nmy $hasfeature = $imap->hascapability($feature)\nor die \"Could not do hascapability($feature): $@\\n\";\n\nReturns:\n\n\"undef\"\nIf the underlying \"capability\" calls fails then \"undef\" is returned.\n\n\"\" or \"()\"\nIf the server does not have the requested capability, then either an empty string (\"\" in\nscalar context) or an empty list (\"()\" in list context) is returned.\n\na *true* value\nIf the server has the requested capability, then a *true* value is returned. The *true*\nvalue depends upon the server response for the capability requested. The value will be an\narray reference in scalar context or an array in list context. The returned data is useful\nfor understanding more about specific capabilities. For example, consider the following\nserver CAPABILITY response:\n\n* CAPABILITY IMAP4rev1 SORT SORT=DISPLAY I18NLEVEL=1 AUTH=PLAIN AUTH=XTEST\n\nResults are returned as shown by the trailing comments:\n\n$c = $imap->hascapability(\"IMAP4rev1\"); # [ \"IMAP4rev1\" ]\n@c = $imap->hascapability(\"IMAP4rev1\"); # ( \"IMAP4rev1\" )\n$c = $imap->hascapability(\"SORT\"); # [ \"DISPLAY\" ]\n@c = $imap->hascapability(\"SORT=DISPLAY\"); # ( \"SORT=DISPLAY\" )\n$c = $imap->hascapability(\"AUTH\"); # [ \"PLAIN\", \"XTEST\" ]\n@c = $imap->hascapability(\"AUTH\"); # ( \"PLAIN\", \"XTEST\" )\n$c = $imap->hascapability(\"AUTH=XTEST\"); # [ \"AUTH=XTEST\" ]\n@c = $imap->hascapability(\"AUTH=XTEST\"); # ( \"AUTH=XTEST\" )\n$c = $imap->hascapability(\"AUTH=NADA\"); # ''\n@c = $imap->hascapability(\"AUTH=NADA\"); # ()\n$c = $imap->hascapability(\"NADA\"); # ''\n@c = $imap->hascapability(\"NADA\"); # ()\n\nidle\nExample:\n\nmy $tag = $imap->idle or warn \"idle failed: $@\\n\";\ndoSomethingA();\nmy $idlemsgs = $imap->idledata() or warn \"idledata error: $@\\n\";\ndoSomethingB();\nmy $results = $imap->done($tag) or warn \"Error from done: $@\\n\";\n\nThe idle method tells the IMAP server the client is ready to accept unsolicited mailbox update\nmessages (on the selected folder/mailbox). This method is only valid on servers that support the\nIMAP IDLE extension, see RFC2177 for details.\n\nThe idle method accepts no arguments and returns the *tag* (identifier) that was sent by the\nclient for this command. This tag should be supplied as the argument to \"done\" when ending the\nIDLE command.\n\nOn failure is returned and \"LastError\" is set.\n\nThe method \"idledata\" may be used once idle has been successful. However, no mailbox operations\nmay be called until the idle command has been terminated by calling \"done\". Failure to do so\nwill result in an error and the idle command will typically be terminated by the server.\n\nSee also \"idledata\" and \"done\".\n\nidledata\nUsage:\n\n# an optional timeout in seconds may be specified\n$imap->idledata( [$timeout] )\n\nExample:\n\nmy $tag = $imap->idle or warn \"idle failed: $@\\n\";\ndoSomethingA();\nmy $idlemsgs = $imap->idledata() or warn \"idledata error: $@\\n\";\ndoSomethingB();\nmy $results = $imap->done($tag) or warn \"Error from done: $@\\n\";\n\nThe idledata method can be used to accept any unsolicited mailbox update messages that have\nbeen sent by the server during an \"idle\" command. This method does not send any commands to the\nserver, it simply looks for and optionally waits for data from the server and returns that data\nto the caller.\n\nThe idledata method accepts an optional $timeout argument and returns an array (or an array\nreference if called in scalar context) with the messages from the server.\n\nBy default a timeout of 0 seconds is used (do not block). Internally the timeout is passed to\n\"select\" in perlfunc. The timeout controls how long the select call blocks if there are no\nmessages waiting to be read from the server.\n\nOn failure is returned and \"LastError\" is set.\n\nSee also \"imap\" and \"done\".\n\nVersion note: method added in Mail::IMAPClient 3.23 Warning: this method is considered\nexperimental and the interface/output may change in a future version.\n\nimap4rev1\nExample:\n\n$imap->imap4rev1 or die \"Could not imap4rev1: $@\\n\";\n\nReturns true if the IMAP server to which the IMAPClient object is connected has the IMAP4REV1\ncapability. If the server does not have the capability then the empty string \"\" is returned, if\nthe underlying \"capability\" calls fails then undef is returned.\n\ninternaldate\nExample:\n\nmy $msginternaldate = $imap->internaldate($msgid)\nor die \"internaldate failed: $@\\n\";\n\ninternaldate accepts one argument, a message id (or UID if the \"Uid\" parameter is true), and\nreturns that message's internal date or undef if the call fails or internal date is not\nreturned.\n\ngetbodystructure\nExample:\n\nmy $bodyStructObject = $imap->getbodystructure($msgid)\nor die \"Could not getbodystructure: $@\\n\";\n\nThe getbodystructure method accepts one argument, a message sequence number or, if \"Uid\" is\ntrue, a message UID. It obtains the message's body structure and returns a parsed\nMail::IMAPClient::BodyStructure object for the message.\n\ngetenvelope\nExample:\n\nmy $envObject = $imap->getenvelope(@args)\nor die \"Could not getenvelope: $@\\n\";\n\nThe getenvelope method accepts one argument, a message sequence number or, if \"Uid\" is true, a\nmessage UID. It obtains the message's envelope and returns a\nMail::IMAPClient::BodyStructure::Envelope object for the envelope, which is just a version of\nthe envelope that's been parsed into a Perl object.\n\nFor more information on how to use this object once you've gotten it, see the\nMail::IMAPClient::BodyStructure documentation. (As of this writing there is no separate pod\ndocument for Mail::IMAPClient::BodyStructure::Envelope.)\n\ngetacl\nExample:\n\nmy $hash = $imap->getacl($folder)\nor die \"Could not getacl for $folder: $@\\n\";\n\ngetacl accepts one argument, the name of a folder. If no argument is provided then the currently\nselected folder is used as the default. It returns a reference to a hash. The keys of the hash\nare userids that have access to the folder, and the value of each element are the permissions\nfor that user. The permissions are listed in a string in the order returned from the server with\nno white space or punctuation between them.\n\ngetheader\nExample:\n\nmy $messageId = $imap->getheader( $msg, \"Message-Id\" );\n\nThe getheader method accepts two arguments, a message sequence number or UID and the name of an\nRFC822 header (without the trailing colon). It returns the value for that header in the message\nwhose sequence number or UID was passed as the first argument. If no value can be found it\nreturns \"undef\"; if multiple values are found it returns the first one. Its return value is\nalways a scalar. getheader uses case insensitive matching to get the value, so you do not have\nto worry about the case of your second argument.\n\nThe getheader method is a short-cut for:\n\nmy $messageId = $imap->parseheaders($msg,\"Subject\")->{\"Subject\"}[0];\n\ngetquotaroot\nExample:\n\nmy $results = $imap->getquotaroot($mailboxname)\nor die \"Could not getquotaroot for $mailboxname: $@\\n\";\n\nThe getquotaroot method implements the RFC2087 GETQUOTAROOT command. The \"$mailboxname\" defaults\nto \"INBOX\" if no argument is provided.\n\nOn error \"undef\" is returned, otherwise \"Results\" are returned. The results should have the\nuntagged QUOTAROOT response from the server along with the QUOTAROOT's resource usage and limits\nin an untagged QUOTA response.\n\nSee also RFC2087, \"getquota\", \"setquota\", \"quota\" and \"quotausage\".\n\ngetquota\nExample:\n\nmy $results = $imap->getquota($quotaroot)\nor die \"Could not getquota for $quotaroot: $@\\n\";\n\nThe getquota method implements the RFC2087 GETQUOTA command. The \"$quotaroot\" defaults to\n\"user/*User*\" if no argument is provided.\n\nOn error \"undef\" is returned, otherwise \"Results\" are returned. The results from the server\nshould have the untagged QUOTA response from the server.\n\nSee also RFC2087, \"getquotaroot\", \"quota\" and \"quotausage\".\n\nquota\nExample:\n\nmy $limit = $imap->quota($quotaroot)\nor die \"Could not get quota limit for $quotaroot: $@\\n\";\n\nThe quota method takes the \"Results\" from getquota and parses out the \"STORAGE\" limit returned\nby the server. The \"$quotaroot\" defaults to \"INBOX\" if no argument is provided.\n\nOn error \"undef\" is returned, otherwise the integer \"STORAGE\" limit provided by the server is\nreturned.\n\nSee also RFC2087, \"getquotaroot\", \"getquota\" and \"quotausage\".\n\nquotausage\nExample:\n\nmy $usage = $imap->quotausage($quotaroot)\nor die \"Could not get quota usage for $quotaroot: $@\\n\";\n\nThe quotausage method takes the \"Results\" from getquota and parses out the \"STORAGE\" usage\nreturned by the server. The \"$quotaroot\" defaults to \"INBOX\" if no argument is provided.\n\nOn error \"undef\" is returned, otherwise the integer \"STORAGE\" usage provided by the server is\nreturned.\n\nSee also RFC2087, \"getquotaroot\", \"getquota\" and \"quota\".\n\nsetquota\nExample:\n\nmy $results = $imap->setquota( $quotaroot, $resource, $limit )\nor die \"Could not setquota for $quotaroot: $@\\n\";\n\nThe setquota method implements the RFC2087 SETQUOTA command. It accepts multiple pairs of\n$resource and $limit arguments. The \"$quotaroot\" defaults to \"user/*User*\" if not defined.\n\nOn error \"undef\" is returned, otherwise \"Results\" are returned.\n\nSee also RFC2087, \"getquotaroot\" and \"getquota\".\n\nisparent\nExample:\n\nmy $hasKids = $imap->isparent($folder);\n\nThe isparent method accepts one argument, the name of a folder. It returns a value that\nindicates whether or not the folder has children. The value it returns is either:\n\n1 (or a positive integer)\nThe \"\\HasChildren\" attribute is set, indicating that the folder has children.\n\n0 (zero)\nThe \"\\HasNoChildren\" attribute is set, indicating that the folder has no children at this\ntime.\n\n\"undef\"\nThe \"\\NoInferiors\" attribute is set, indicating the folder is not permitted to have\nchildren.\n\nEg:\n\nmy $parenthood = $imap->isparent($folder);\nif ( defined($parenthood) ) {\nif ($parenthood) {\nprint \"$folder has children.\\n\";\n}\nelse {\nprint \"$folder is permitted children, but has none.\\n\";\n}\n}\nelse {\nprint \"$folder is not permitted to have children.\\n\";\n}\n\nlist\nExample:\n\nmy @rawoutput = $imap->list(@args)\nor die \"Could not list: $@\\n\";\n\nThe list method implements the IMAP LIST client command. Arguments are passed to the IMAP server\nas received, separated from each other by spaces. If no arguments are supplied then the default\nlist command \"tag LIST \"\" '*'\" is issued.\n\nThe list method returns an array (or an array reference, if called in a scalar context). The\narray is the unadulterated output of the LIST command. (If you want your output adulterated then\nsee the \"folders\" method, above.)\n\nAn \"undef\" value is returned in case of errors. Be sure to check for it.\n\nlistrights\nExample:\n\n$imap->listrights( $folder, $user )\nor die \"Could not listrights: $@\\n\";\n\nThe listrights method implements the IMAP LISTRIGHTS client command (RFC2086). It accepts two\narguments, the foldername and a user id. It returns the rights the specified user has for the\nspecified folder. If called in a scalar context then the rights are returned a strings, with no\npunctuation or white space or any nonsense like that. If called in array context then listrights\nreturns an array in which each element is one right.\n\nlogin\nExample:\n\n$imap->login or die \"Could not login: $@\\n\";\n\nThe login method implements the IMAP LOGIN client command to log into the server. It\nautomatically calls \"authenticate\" if the *Authmechanism* parameter is set to anything except\n'LOGIN' otherwise a clear text LOGIN is attempted.\n\nThe *User* and *Password* parameters must be set before the login method can be invoked. On\nsuccess, a Mail::IMAPClient object with the Status of *Authenticated* is returned. On failure,\nundef is returned and $@ is set. The methods \"new\", \"connect\", and \"Socket\" may automatically\ninvoke login see the documentation of each method for details.\n\nIf the \"Compress\" parameter is set, the \"compress\" method will automatically be called after\nsuccessful authentication.\n\nSee also \"proxyauth\" and \"Proxy\" for additional information regarding ways of authenticating\nwith a server via SASL and/or PROXYAUTH.\n\nproxyauth\nExample:\n\n$imap->login( \"admin\", \"password\" );\n$imap->proxyauth(\"someuser\");\n\nThe proxyauth method implements the IMAP PROXYAUTH client command. The command is used by\nSun/iPlanet/Netscape IMAP servers to allow an administrative user to masquerade as another user.\n\nlogout\nExample:\n\n$imap->logout or die \"Could not logout: $@\\n\";\n\nThe logout method implements the LOGOUT IMAP client command. This method causes the server to\nend the connection and the IMAPClient client enters the *Unconnected* state. This method does\nnot, destroy the IMAPClient object, thus the \"connect\" and \"login\" methods can be used to\nestablish a new IMAP session.\n\nNote that RFC2683 section 3.1.2 (Severed connections) makes some recommendations on how IMAP\nclients should behave. It is up to the user of this module to decide on the preferred behavior\nand code accordingly.\n\nVersion note: documentation (from 2.x through 3.23) claimed that Mail::IMAPClient would attempt\nto log out of the server during DESTROY if the object is in the \"Connected\" state. This\ndocumentation was apparently incorrect from at least 2.2.2 and possibly earlier versions on up.\n\nlsub\nExample:\n\n$imap->lsub(@args) or die \"Could not lsub: $@\\n\";\n\nThe lsub method implements the IMAP LSUB client command. Arguments are passed to the IMAP server\nas received, separated from each other by spaces. If no arguments are supplied then the default\nlsub command \"tag LSUB \"\" '*'\" is issued.\n\nThe lsub method returns an array (or an array reference, if called in a scalar context). The\narray is the unaltered output of the LSUB command. If you want an array of subscribed folders\nthen see the \"subscribed\" method, below.\n\nmark\nExample:\n\n$imap->mark(@msgs) or die \"Could not mark: $@\\n\";\n\nThe mark method accepts a list of one or more messages sequence numbers, or a single reference\nto an array of one or more message sequence numbers, as its argument(s). It then sets the\n\"\\Flagged\" flag for those message(s). Of course, if the \"Uid\" parameter is set to a true value\nthen those message sequence numbers had better be unique message id's.\n\nNote that specifying \"$imap->see(@msgs)\" is just a shortcut for specifying\n\"$imap->setflag(\"Flagged\",@msgs)\".\n" }, { "name": "Massage", "content": "Example:\n\n$imap->search(HEADER => 'Message-id' => $imap->Massage($msgid,1));\n\nWARNING: This method may be deprecated in the future, consider using \"Quote\" instead of this\nmethod.\n\nThe Massage method accepts a value as an argument and, optionally, a second value that, when\ntrue, indicates that the first argument is not the name of an existing folder.\n\nWARNING: If the first argument has double quotes at the beginning and end of its value, those\ndouble quote will be stripped unless the second argument does not evaluate to true.\n\nIt returns its argument as a correctly quoted string or a literal string.\n\nNote that you should rarely use this on folder names, since methods that accept folder names as\nan argument will call Quote for you.\n\nmessagecount\nExample:\n\nmy $msgcount = $imap->messagecount($folder);\ndefined($msgcount) or die \"messagecount failed: $@\\n\";\n\nThe messagecount method accepts the name of a folder as an argument and returns the number of\nmessages in that folder. Internally, it invokes the \"status\" method (see above) and parses out\nthe results to obtain the number of messages. If you don't supply an argument to messagecount\nthen it will return the number of messages in the currently selected folder (assuming of course\nthat you've used the \"select\" or \"examine\" method to select it instead of trying something\nfunky). Note that RFC2683 contains warnings about the use of the IMAP *STATUS* command (and thus\nthe \"status\" method and therefore the messagecount method) against the currently selected\nfolder. You should carefully consider this before using messagecount on the currently selected\nfolder. You may be better off using \"search\" or one of its variants (especially \"messages\"), and\nthen counting the results. On the other hand, I regularly violate this rule on my server without\nsuffering any dire consequences. Your mileage may vary.\n\nmessagestring\nExample:\n\nmy $string = $imap->messagestring($msgid)\nor die \"messagestring failed: $@\\n\";\n\nThe messagestring method accepts a message sequence number (or message UID if \"Uid\" is true) as\nan argument and returns the message as a string. The returned value contains the entire message\nin one scalar variable, including the message headers. Note that using this method will set the\nmessage's \"\\Seen\" flag as a side effect, unless *Peek* is set to a true value.\n\nmessagetofile\nExample:\n\n$imap->messagetofile( $file, @msgs )\nor die \"messagetofile failed: $@\\n\";\n\nThe messagetofile method accepts a filename or file handle and one or more message sequence\nnumbers (or message UIDs if \"Uid\" is true) as arguments and places the message string(s)\n(including RFC822 headers) into the file named in the first argument (or prints them to the file\nhandle, if a file handle is passed). The returned value is true on success and \"undef\" on\nfailure.\n\nIf the first argument is a reference, it is assumed to be an open file handle and will not be\nclosed when the method completes, If it is a file, it is opened in append mode, written to, then\nclosed.\n\nNote that using this method will set the message's \"\\Seen\" flag as a side effect. But you can\nuse the \"denyseeing\" method to set it back, or set the \"Peek\" parameter to a true value to\nprevent setting the \"\\Seen\" flag at all.\n\nThis method currently works by making some basic assumptions about the server's behavior,\nnotably that the message text will be returned as a literal string but that nothing else will\nbe. If you have a better idea then I'd like to hear it.\n\nmessageuid\nExample:\n\nmy $msguid = $imap->messageuid($msgseqno)\nor die \"Could not get uid for $msgseqno: $@\\n\";\n\nThe messageuid method accepts a message sequence number (or message UID if \"Uid\" is true) as an\nargument and returns the message's UID. Yes, if \"Uid\" is true then it will use the IMAP UID\nFETCH UID client command to obtain and return the very same argument you supplied. This is an\nIMAP feature so don't complain to me about it.\n\nmessages\nExample:\n\n# Get a list of messages in the current folder:\nmy @msgs = $imap->messages or warn \"Could not list messages\\n\";\n# Get a reference to an array of messages in the current folder:\nmy $msgs = $imap->messages or die \"Get messages failed: $@\\n\";\n\nIf called in list context, the messages method returns a list of all the messages in the\ncurrently selected folder. If called in scalar context, it returns a reference to an array\ncontaining all the messages in the folder. This is the same as specifying\n\"$imap->\"search\"(\"ALL\")\".\n\nAn empty list is returned when no messages are found. On failure is returned and\n\"LastError\" is set.\n\nmigrate\nExample:\n\n$imapsrc->migrate( $imapdest, \"ALL\", $targetFolder )\nor die \"Could not migrate: \", $imapsrc->LastError;\n\nThe migrate method copies the indicated message(s) from the currently selected folder to another\nMail::IMAPClient object's session. It requires these arguments:\n\n1. a reference to the target Mail::IMAPClient object (not the calling object, which is\nconnected to the source account);\n\n2. the message(s) to be copied, specified as either a) the message sequence number (or message\nUID if the UID parameter is true) of a single message, b) a reference to an array of message\nsequence numbers (or message UID's if the UID parameter is true) or c) the special string\n\"ALL\", which is a shortcut for the results of \"\"search\"(\"ALL\")\".\n\n3. the name of the destination folder on the target mailbox to receive the message(s). If this\nargument is not supplied or is *undef* then the currently selected folder on the calling\nobject will be used. The destination folder will be automatically created if necessary.\n\nThe target ($imapdest) Mail::IMAPClient object must not be the same object as the source\n($imapsrc).\n\nThis method does not attempt to minimize memory usage. In the future it could be enhanced to\n(optionally) write message data to a temporary file to avoid storing the entire message in\nmemory.\n\nTo work around potential network timeouts on large messages, consider setting \"Reconnectretry\"\nto 1 on both $imapsrc and $imapdest.\n\nSee also \"Supportedflags\".\n\nmove\nExample:\n\nmy $newUid = $imap->move( $newFolder, $oldUid )\nor die \"Could not move: $@\\n\";\n$imap->expunge;\n\nThe move method moves messages from the currently selected folder to the folder specified in the\nfirst argument to move. If the \"Uid\" parameter is not true, then the rest of the arguments\nshould be either:\n\na) a message sequence number,\n\nb) a comma-separated list of message sequence numbers, or\n\nc) a reference to an array of message sequence numbers.\n\nIf the \"Uid\" parameter is true, then the arguments should be:\n\na) a message UID,\n\nb) a comma-separated list of message UID's, or\n\nc) a reference to an array of message UID's.\n\nIf the target folder does not exist then it will be created.\n\nIf move is successful, then it returns a true value. Furthermore, if the Mail::IMAPClient object\nis connected to a server that has the UIDPLUS capability, then the true value will be the\ncomma-separated list of UID's for the newly copied messages. The list will be in the order in\nwhich the messages were moved which should correspond to the order of the message UID provided\nby the caller.\n\nIf the move is not successful then move returns \"undef\".\n\nNote that a move really just involves copying the message to the new folder and then setting the\n*\\Deleted* flag. To actually delete the original message you will need to run \"expunge\" (or\n\"close\").\n\nnamespace\nExample:\n\nmy $refs = $imap->namespace\nor die \"namespace failed: $@\\n\";\n\nThe namespace method runs the NAMESPACE IMAP command (as defined in RFC 2342). When called in a\nlist context, it returns a list of three references. Each reference looks like this:\n\n[\n[ $prefix1, $separator1 ],\n[ $prefix2, $separator2 ],\n[ $prefixn, $separatorn ],\n]\n\nThe first reference provides a list of prefixes and separator characters for the available\npersonal namespaces. The second reference provides a list of prefixes and separator characters\nfor the available shared namespaces. The third reference provides a list of prefixes and\nseparator characters for the available public namespaces.\n\nIf any of the three namespaces are unavailable on the current server then an 'undef' is returned\ninstead of a reference. So for example if shared folders were not supported on the server but\npersonal and public namespaces were both available (with one namespace each), the returned value\nmight resemble this:\n\n[ [ \"\", \"/\" ] , undef, [ \"#news\", \".\" ] ];\n\nIf the namespace method is called in scalar context, it returns a reference to the\nabove-mentioned list of three references, thus creating a single structure that would\npretty-print something like this:\n\n$VAR1 = [\n[\n[ $userprefix1, $userseparator1 ],\n[ $userprefix2, $userseparator2 ],\n[ $userprefixn, $userseparatorn ],\n], # or undef\n[\n[ $sharedprefix1, $sharedseparator1 ],\n[ $sharedprefix2, $sharedseparator2 ],\n[ $sharedprefixn, $sharedseparatorn ],\n], # or undef\n[\n[ $publicprefix1, $publicseparator1 ],\n[ $publicprefix2, $publicseparator2 ],\n[ $publicprefixn, $publicseparatorn ],\n], # or undef\n];\n\non\nExample:\n\nmy @msgs = $imap->on($Rfc3501date)\nor warn \"Could not find messages sent on $Rfc3501date: $@\\n\";\n\nThe on method works just like the \"since\" method, below, except it returns a list of messages\nwhose internal system dates are the same as the date supplied as the argument.\n\nparseheaders\nExample:\n\nmy $hashref = $imap->parseheaders( $msg || \\@msgs, \"Date\", \"Subject\" )\nor die \"Could not parseheaders: $@\\n\";\n\nThe parseheaders method accepts as arguments a message sequence number and a list of header\nfields. It returns a hash reference in which the keys are the header field names (without the\ncolon) and the values are references to arrays of values. On failure is returned and\n\"LastError\" is set.\n\nA picture would look something like this:\n\n$hashref = $imap->parseheaders( 1, \"Date\", \"Received\", \"Subject\", \"To\");\n$hashref = {\n\"Date\" => [ \"Thu, 09 Sep 1999 09:49:04 -0400\" ] ,\n\"Received\" => [ q/\nfrom mailhub ([111.11.111.111]) by mailhost.bigco.com\n(Netscape Messaging Server 3.6) with ESMTP id AAA527D for\n; Fri, 18 Jun 1999 16:29:07 +0000\n/, q/\nfrom directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)\nid <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com\n(ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)\n/, q/\nfrom someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)\nwith ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,\n18 Jun 1999 16:29:05 +0000 (GMT)\n/] ,\n\"Subject\" => [ qw/ Help! I've fallen and I can't get up!/ ] ,\n\"To\" => [ \"Big Shot ] ,\n};\n\nThe text in the example for the \"Received\" array has been formatted to make reading the example\neasier. The actual values returned are just strings of words separated by spaces and with\nnewlines and carriage returns stripped off. The *Received* header is probably the main reason\nthat the parseheaders method creates a hash of lists rather than a hash of values.\n\nIf the second argument to parseheaders is 'ALL' or if it is unspecified then all available\nheaders are included in the returned hash of lists.\n\nIf you're not emotionally prepared to deal with a hash of lists then you can always call the\n\"fetch\" method yourself with the appropriate parameters and parse the data out any way you want\nto. Also, in the case of headers whose contents are also reflected in the envelope, you can use\nthe \"getenvelope\" method as an alternative to \"parseheaders\".\n\nIf the \"Uid\" parameter is true then the first argument will be treated as a message UID. If the\nfirst argument is a reference to an array of message sequence numbers (or UID's if \"Uid\" is\ntrue), then parseheaders will be run against each message in the array. In this case the return\nvalue is a hash, in which the key is the message sequence number (or UID) and the value is a\nreference to a hash as described above.\n\nAn example of using parseheaders to print the date and subject of every message in your demo\nfolder could look like this:\n\nuse Mail::IMAPClient;\nmy $imap = Mail::IMAPClient->new(\nServer => $imaphost, User => $login, Password => $pass, Uid => 1\n);\n\n$imap->select(\"demo\");\n\nmy $msgs = $imap->search(\"ALL\");\nfor my $h (\n\n# get the Subject and Date from every message in folder \"demo\" the\n# first arg is a reference to an array listing all messages in the\n# folder (which is what gets returned by the $imap->search(\"ALL\")\n# method when called in scalar context) and the remaining arguments\n# are the fields to parse out The key is the message number, which\n# in this case we don't care about:\n\nvalues %{ $imap->parseheaders( $msgs , \"Subject\", \"Date\") } )\n{\n# $h is the value of each element in the hash ref returned\n# from parseheaders, and $h is also a reference to a hash.\n# We'll only print the first occurrence of each field because\n# we don't expect more than one Date: or Subject: line per\n# message.\nprint map { \"$:\\t$h->{$}[0]\\n\"} keys %$h;\n}\n\nrecent\nExample:\n\nmy @recent = $imap->recent or warn \"No recent msgs: $@\\n\";\n\nThe recent method performs an IMAP SEARCH RECENT search against the selected folder and returns\nan array of sequence numbers (or UID's, if the \"Uid\" parameter is true) of messages that are\nrecent.\n\nrecentcount\nExample:\n\nmy $count = 0;\ndefined($count = $imap->recentcount($folder))\nor die \"recentcount failed: $@\\n\";\n\nThe recentcount method accepts as an argument a folder name. It returns the number of recent\nmessages in the folder (as returned by the IMAP client command \"STATUS folder RECENT\"), or\n\"undef\" in the case of an error. The recentcount method was contributed by Rob Deker\n(deker@ikimbo.com).\n\nnoop\nExample:\n\n$imap->noop or die \"noop failed: $@\\n\";\n\nThe noop method performs an IMAP NOOP command. Per RFC3501 this command does nothing and always\nsucceeds. However, if a connection times out or other errors occur while communicating with the\nserver, this method can still fail. This command can be used as a periodic poll to check for\n(untagged) status updates (new messages, etc.) from the server and also to reset any\ninactivity/auto-logout timers the server may maintain.\n\nreconnect\nExample:\n\n$imap->noop or $imap->reconnect or die \"noop failed: $@\\n\";\n\nAttempt to reconnect if the IMAP connection unless $imap is already in the IsConnected state.\nThis method calls \"connect\" and optionally \"select\" if a Folder was previously selected. On\nsuccess, returns the (same) $imap object. On failure is returned and \"LastError\" is set.\n\nVersion note: method added in Mail::IMAPClient 3.17\n\nrename\nExample:\n\n$imap->rename( $oldname, $nedwname )\nor die \"rename failed: $@\\n\";\n\nThe rename method accepts two arguments: the name of an existing folder, and a new name for the\nfolder. The existing folder will be renamed to the new name using the RENAME IMAP client\ncommand. rename will return a true value if successful, or \"undef\" if unsuccessful.\n\nrestoremessage\nExample:\n\n$imap->restoremessage(@msgs) or die \"restoremessage failed: $@\\n\";\n\nThe restoremessage method is used to undo a previous \"deletemessage\" operation (but not if\nthere has been an intervening \"expunge\" or \"close\"). The IMAPClient object must be in \"Selected\"\nstatus to use the restoremessage method.\n\nThe restoremessage method accepts a list of arguments. If the \"Uid\" parameter is not set to a\ntrue value, then each item in the list should be either:\n\n> a message sequence number,\n\n> a comma-separated list of message sequence numbers,\n\n> a reference to an array of message sequence numbers, or\n\nIf the \"Uid\" parameter is set to a true value, then each item in the list should be either:\n\n> a message UID,\n\n> a comma-separated list of UID's, or\n\n> a reference to an array of message UID's.\n\nThe messages identified by the sequence numbers or UID's will have their *\\Deleted* flags\ncleared, effectively \"undeleting\" the messages. restoremessage returns the number of messages\nit was able to restore.\n\nNote that restoremessages is similar to calling \"\"unsetflag\"(\"\\Deleted\",@msgs)\", except that\nrestoremessages returns a (slightly) more meaningful value. Also it's easier to type.\n\nrun\nExample:\n\n$imap->run(@args) or die \"run failed: $@\\n\";\n\nThe run method is provided to make those uncommon things possible... however, we would like you\nto contribute the knowledge of missing features with us.\n\nThe run method excepts one or two arguments. The first argument is a string containing an IMAP\nclient command, including a tag and all required arguments. The optional second argument is a\nstring to look for that will indicate success. (The default is \"/OK.*/\"). The run method returns\nan array (or arrayref in scalar context) of output lines from the command, which you are free to\nparse as you see fit.\n\nThe run method does not do any syntax checking, other than rudimentary checking for a tag.\n\nWhen run processes the command, it increments the transaction count and saves the command and\nresponses in the History buffer in the same way other commands do. However, it also creates a\nspecial entry in the History buffer named after the tag supplied in the string passed as the\nfirst argument. If you supply a numeric value as the tag then you may risk overwriting a\nprevious transaction's entry in the History buffer.\n\nIf you want the control of run but you don't want to worry about tags then see \"tagandrun\",\nbelow.\n\nsearch\nExample:\n\nmy $msgs1 = $imap->search(@args);\nif ($msgs1) {\nprint \"search matches: @$msgs1\";\n}\nelse {\nwarn \"Error in search: $@\\n\" if $@;\n}\n\n# or note: be sure to quote string properly\nmy $msgs2 = $imap->search( \\( $imap->Quote($msgid), \"FROM\", q{\"me\"} ) )\nor warn \"search failed: $@\\n\";\n\n# or note: be sure to quote string properly\nmy $msgs3 = $imap->search('TEXT \"string not in mailbox\"')\nor warn \"search failed: $@\\n\";\n\nThe search method implements the SEARCH IMAP client command. Any arguments supplied to search\nare prefixed with a space then appended to the SEARCH IMAP client command. The SEARCH IMAP\nclient command allows for many options and arguments. See RFC3501 for details.\n\nAs of version 3.17 search tries to \"DWIM\" by automatically quoting things that likely need\nquotes when the words do not match any of the following:\n\nALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED\nFROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT\nSEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT\nTEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED\nUNKEYWORD UNSEEN\n\nThe following options exist to avoid the automatic quoting (note: caller is responsible for\nverifying the data sent in these cases is properly escaped/quoted):\n\n* specify a single string/argument in the call to search.\n\n* specify args as scalar references (SCALAR) and the values of those SCALAR refs will be\npassed along as-is.\n\nThe search method returns an array containing sequence numbers of messages that passed the\nSEARCH IMAP client command's search criteria. If the \"Uid\" parameter is true then the array will\ncontain message UID's. If search is called in scalar context then a pointer to the array will be\npassed, instead of the array itself. If no messages meet the criteria then search returns an\nempty list (when in list context) or \"undef\" (in scalar context).\n\nSince a valid, successful search can legitimately return zero matches, you may wish to\ndistinguish between a search that correctly returns zero hits and a search that has failed for\nsome other reason (i.e. invalid search parameters). Therefore, the $@ variable will always be\ncleared before the *SEARCH* command is issued to the server, and will thus remain empty unless\nthe server gives a *BAD* or *NO* response to the *SEARCH* command.\n\nsee\nExample:\n\n$imap->see(@msgs) or die \"see failed: $@\\n\";\n\nThe see method accepts a list of one or more messages sequence numbers, or a single reference to\nan array of one or more message sequence numbers, as its argument(s). It then sets the *\\Seen*\nflag for those message(s). Of course, if the \"Uid\" parameter is set to a true value then those\nmessage sequence numbers had better be unique message id's, but then you already knew that,\ndidn't you?\n\nNote that specifying \"$imap->see(@msgs)\" is just a shortcut for specifying\n\"$imap->\"setflag\"(\"Seen\",@msgs)\".\n\nseen\nExample:\n\nmy @seenMsgs = $imap->seen or warn \"No seen msgs: $@\\n\";\n\nThe seen method performs an IMAP SEARCH SEEN search against the selected folder and returns an\narray of sequence numbers of messages that have already been seen (ie their *\\Seen* flag is\nset). If the \"Uid\" parameter is true then an array of message UID's will be returned instead. If\ncalled in scalar context than a reference to the array (rather than the array itself) will be\nreturned.\n\nselect\nExample:\n\n$imap->select($folder) or die \"select failed: $@\\n\";\n\nThe select method selects a folder and changes the object's state to *Selected*. It accepts one\nargument, which is the name of the folder to select.\n\nselectable\nExample:\n\nforeach my $f ( grep( $imap->selectable($), $imap->folders ) ) {\n$imap->select($f);\n}\n\nThe selectable method accepts one value, a folder name, and returns true if the folder is\nselectable or false if it is not selectable.\n\nsentbefore\nExample:\n\nmy @msgs = $imap->sentbefore($Rfc3501date)\nor warn \"Could not find any msgs sent before $Rfc3501date: $@\\n\";\n\nThe sentbefore method works just like \"sentsince\", below, except it searches for messages that\nwere sent before the date supplied as an argument to the method.\n\nsenton\nExample:\n\nmy @msgs = $imap->senton($Rfc3501date)\nor warn \"Could not find any messages sent on $Rfc3501date: $@\\n\";\n\nThe senton method works just like \"sentsince\", below, except it searches for messages that were\nsent on the exact date supplied as an argument to the method.\n\nsentsince\nExample:\n\nmy @msgs = $imap->sentsince($Rfc3501date)\nor warn \"Could not find any messages sent since $Rfc3501date: $@\\n\";\n\nThe sentsince method accepts one argument, a date in either epoch time format (seconds since\n1/1/1970, or as output by time and as accepted by localtime) or in the *datetext* format as\ndefined in RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for\nthe month).\n\nIt searches for items in the currently selected folder for messages sent since the day whose\ndate is provided as the argument. It uses the RFC822 *Date:* header to determine the *sentsince*\ndate. (Actually, it the server that uses the *Date:* header; this documentation just assumes\nthat the date is coming from the *Date:* header because that's what RFC3501 dictates.)\n\nIn the case of arguments supplied as a number of seconds, the returned result list will include\nitems sent on or after that day, regardless of whether they arrived before the specified time on\nthat day. The IMAP protocol does not support searches at a granularity finer than a day, so\nneither do I. On the other hand, the only thing I check for in a *datetext* argument is that it\nmatches the pattern \"/\\d\\d-\\D\\D\\D-\\d\\d\\d\\d/\" (notice the lack of anchors), so if your server\nlets you add something extra to a *datetext* string then so will Mail::IMAPClient.\n\nIf you'd like, you can use the \"Rfc3501date\" method to convert from epoch time (as returned by\ntime) into an RFC3501 date specification.\n\nseparator\nExample:\n\nmy $sepChar = $imap->separator(@args)\nor die \"Could not get separator: $@\\n\";\n\nThe separator method returns the character used as a separator character in folder hierarchies.\nOn UNIX-based servers, this is often but not necessarily a forward slash (/). It accepts one\nargument, the name of a folder whose hierarchy's separator should be returned. If no folder name\nis supplied then the separator for the INBOX is returned, which probably is good enough.\n\nIf you want your programs to be portable from IMAP server brand X to IMAP server brand Y, then\nyou should never use hard-coded separator characters to specify subfolders. (In fact, it's even\nmore complicated than that, since some server don't allow any subfolders at all, some only allow\nsubfolders under the \"INBOX\" folder, and some forbid subfolders in the inbox but allow them\n\"next\" to the inbox. Furthermore, some server implementations do not allow folders to contain\nboth subfolders and mail messages; other servers allow this.)\n\nsetflag\nExample:\n\n$imap->setflag( \"Seen\", @msgs )\nor die \"Could not set flag: $@\\n\";\n\nThe setflag method accepts the name of a flag as its first argument and a list of one or more\nmessages sequence numbers, or a single reference to an array of one or more message sequence\nnumbers, as its next argument(s). It then sets the flag specified for those message(s). Of\ncourse, if the \"Uid\" parameter is set to a true value then those message sequence numbers had\nbetter be unique message id's, just as you'd expect.\n\nNote that when specifying the flag in question, the preceding backslash (\\) is entirely\noptional. (For you, that is. Mail::IMAPClient still has remember to stick it in there before\npassing the command to the server if the flag is one of the reserved flags specified in RFC3501.\nThis is in fact so important that the method checks its argument and adds the backslash when\nnecessary, which is why you don't have to worry about it overly much.)\n\nsetacl\nExample:\n\n$imap->setacl( $folder, $userid, $aclstring )\nor die \"Could not set acl: $@\\n\";\n\nThe setacl method accepts three input arguments, a folder name, a user id (or authentication\nidentifier, to use the terminology of RFC2086), and an access rights modification string. See\nRFC2086 for more information. (This is somewhat experimental and its implementation may change.)\n\nsince\nExample:\n\nmy @msgs = $imap->since($date)\nor warn \"Could not find any messages since $date: $@\\n\";\n\nThe since method accepts a date in either epoch format (seconds since 1/1/1970, or as output by\n\"time\" in perlfunc and as accepted by \"localtime\" in perlfunc) or in the *datetext* format as\ndefined in RFC3501 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for\nthe month). It searches for items in the currently selected folder for messages whose internal\ndates are on or after the day whose date is provided as the argument. It uses the internal\nsystem date for a message to determine if that message was sent since the given date.\n\nIn the case of arguments supplied as a number of seconds, the returned result list will include\nitems whose internal date is on or after that day, regardless of whether they arrived before the\nspecified time on that day.\n\nIf since is called in a list context then it will return a list of messages meeting the *SEARCH\nSINCE* criterion, or an empty list if no messages meet the criterion.\n\nIf since is called in a scalar context then it will return a reference to an array of messages\nmeeting the *SEARCH SINCE* criterion, or \"undef\" if no messages meet the criterion.\n\nSince since is a front-end to \"search\", some of the same rules apply. For example, the $@\nvariable will always be cleared before the *SEARCH* command is issued to the server, and will\nthus remain empty unless the server gives a *BAD* or *NO* response to the *SEARCH* command.\n\nsize\nExample:\n\nmy $size = $imap->size($msgId)\nor die \"Could not find size of message $msgId: $@\\n\";\n\nThe size method accepts one input argument, a sequence number (or message UID if the \"Uid\"\nparameter is true). It returns the size of the message in the currently selected folder with the\nsupplied sequence number (or UID). The IMAPClient object must be in a *Selected* state in order\nto use this method.\n\nsort\nExample:\n\nmy @msgs = $imap->sort(@args);\nwarn \"Error in sort: $@\\n\" if $@;\n\nThe sort method is just like the \"search\" method, only different. It implements the SORT\nextension as described in https://tools.ietf.org/html/rfc5256. It would be wise to use the\n\"hascapability\" method to verify that the SORT capability is available on your server before\ntrying to use the sort method. If you forget to check and you're connecting to a server that\ndoesn't have the SORT capability then sort will return undef. \"LastError\" will then say you are\n\"BAD\". If your server doesn't support the SORT capability then you'll have to use \"search\" and\nthen sort the results yourself.\n\nThe first argument to sort is a space-delimited list of sorting criteria. The Internet Draft\nthat describes SORT requires that this list be wrapped in parentheses, even if there is only one\nsort criterion. If you forget the parentheses then the sort method will add them. But you have\nto forget both of them, or none. This isn't CMS running under VM!\n\nThe second argument is a character set to use for sorting. Different character sets use\ndifferent sorting orders, so this argument is important. Since all servers must support UTF-8\nand US-ASCII if they support the SORT capability at all, you can use one of those if you don't\nhave some other preferred character set in mind.\n\nThe rest of the arguments are searching criteria, just as you would supply to the \"search\"\nmethod. These are all documented in RFC3501. If you just want all of the messages in the\ncurrently selected folder returned to you in sorted order, use *ALL* as your only search\ncriterion.\n\nThe sort method returns an array containing sequence numbers of messages that passed the SORT\nIMAP client command's search criteria. If the \"Uid\" parameter is true then the array will\ncontain message UID's. If sort is called in scalar context then a pointer to the array will be\npassed, instead of the array itself. The message sequence numbers or unique identifiers are\nordered according to the sort criteria specified. The sort criteria are nested in the order\nspecified; that is, items are sorted first by the first criterion, and within the first\ncriterion they are sorted by the second criterion, and so on.\n\nThe sort method will clear $@ before attempting the *SORT* operation just as the \"search\" method\ndoes.\n\nstarttls\nExample:\n\n$imap->starttls() or die \"starttls failed: $@\\n\";\n\nThe starttls method accepts no arguments. This method is used to upgrade an exiting connection\nwhich is not authenticated to a TLS/SSL connection by using the IMAP STARTTLS command followed\nby using the startSSL class method from IO::Socket::SSL to do the necessary TLS negotiation.\nThe negotiation is done in a blocking fashion with a default Timeout of 30 seconds. The\narguments used in the call to startSSL can be controlled by setting the Mail::IMAPClient\n\"Starttls\" attribute to an ARRAY reference containing the desired arguments.\n\nVersion note: method added in Mail::IMAPClient 3.22\n\nstatus\nExample:\n\nmy @rawdata = $imap->status( $folder, qw/(Messages)/ )\nor die \"Error obtaining status: $@\\n\";\n\nThe status method accepts one argument, the name of a folder (or mailbox, to use RFC3501's\nterminology), and returns an array containing the results of running the IMAP STATUS client\ncommand against that folder. If additional arguments are supplied then they are appended to the\nIMAP STATUS client command string, separated from the rest of the string and each other with\nspaces.\n\nIf status is not called in an array context then it returns a reference to an array rather than\nthe array itself.\n\nThe status method should not be confused with the Status method (with an uppercase 'S'), which\nreturns information about the IMAPClient object. (See the section labeled \"Status Methods\",\nbelow).\n\nstore\nExample:\n\n$imap->store(@args) or die \"Could not store: $@\\n\";\n\nThe store method accepts a message sequence number or comma-separated list of message sequence\nnumbers as a first argument, a message data item name, and a value for the message data item.\nCurrently, data items are the word \"FLAGS\" followed by a space and a list of flags (in parens).\nThe word \"FLAGS\" can be modified by prefixing it with either a \"+\" or a \"-\" (to indicate \"add\nthese flags\" or \"remove these flags\") and by suffixing it with \".SILENT\" (which reduces the\namount of output from the server; very useful with large message sets). Normally you won't need\nto call store because there are oodles of methods that will invoke store for you with the\ncorrect arguments. Furthermore, these methods are friendlier and more flexible with regards to\nhow you specify your arguments. See for example \"see\", \"denyseeing\", \"deletemessage\", and\n\"restoremessage\". Or \"mark\", \"unmark\", \"setflag\", and \"unsetflag\".\n\nsubject\nExample:\n\nmy $subject = $imap->subject($msg);\n\nThe subject method accepts one argument, a message sequence number (or a message UID, if the\n*Uid* parameter is true). The text in the \"Subject\" header of that message is returned (without\nthe \"Subject: \" prefix). This method is a short-cut for:\n\nmy $subject = $imap->getheader($msg, \"Subject\");\n\nsubscribed\nExample:\n\nmy @subscribedFolders = $imap->subscribed\nor warn \"Could not find subscribed folders: $@\\n\";\n\nThe subscribed method works like the folders method, above, except that the returned list (or\narray reference, if called in scalar context) contains only the subscribed folders.\n\nLike \"folders\", you can optionally provide a prefix argument to the subscribed method.\n\ntagandrun\nExample:\n\nmy $output = $imap->tagandrun(@args)\nor die \"Could not tagandrun: $@\\n\";\n\nThe tagandrun method accepts one or two arguments. The first argument is a string containing\nan IMAP client command, without a tag but with all required arguments. The optional second\nargument is a string to look for that will indicate success (without pattern delimiters). The\ndefault is \"OK.*\".\n\nThe tagandrun method will prefix your string (from the first argument) with the next\ntransaction number and run the command. It returns an array of output lines from the command,\nwhich you are free to parse as you see fit. Using this method instead of run (above) will free\nyou from having to worry about handling the tags (and from worrying about the side affects of\nnaming your own tags).\n\nuidexpunge\nExample:\n\n$imap->uidexpunge(@uids) or die \"Could not uidexpunge: $@\\n\";\n\nThe uidexpunge method implements the UID EXPUNGE IMAP (RFC4315 UIDPLUS ext) client command to\npermanently remove all messages that have the \\Deleted flag set and have a UID that is included\nin the list of UIDs.\n\nuidexpunge returns an array or arrayref (scalar context) of output lines returned from the UID\nEXPUNGE command.\n\nuidexpunge returns undef on failure.\n\nIf the server does not support the UIDPLUS extension, this method returns undef.\n\nuidnext\nExample:\n\nmy $nextUid = $imap->uidnext($folder) or die \"uidnext failed: $@\\n\";\n\nThe uidnext method accepts one argument, the name of a folder, and returns the numeric string\nthat is the next available message UID for that folder.\n\nthread\nExample:\n\nmy $thread = $imap->thread( $algorithm, $charset, @searchargs );\n\nThe thread method accepts zero to three arguments. The first argument is the threading algorithm\nto use, generally either *ORDEREDSUBJECT* or *REFERENCES*. The second argument is the character\nset to use, and the third argument is the set of search arguments to use.\n\nIf the algorithm is not supplied, it defaults to *REFERENCES* if available, or *ORDEREDSUBJECT*\nif available. If neither of these is available then the thread method returns undef.\n\nIf the character set is not specified it will default to *UTF-8*.\n\nIf the search arguments are not specified, the default is *ALL*.\n\nIf thread is called for an object connected to a server that does not support the THREADS\nextension then the thread method will return \"undef\".\n\nThe threads method will issue the *THREAD* command as defined in\nhttps://tools.ietf.org/html/rfc5256. It returns an array of threads. Each element in the array\nis either a message id or a reference to another array of (sub)threads.\n\nIf the \"Uid\" parameter is set to a true value then the message id's returned in the thread\nstructure will be message UID's. Otherwise they will be message sequence numbers.\n\nuidvalidity\nExample:\n\nmy $validity = $imap->uidvalidity($folder)\nor die \"uidvalidity failed: $@\\n\";\n\nThe uidvalidity method accepts one argument, the name of a folder, and returns the numeric\nstring that is the unique identifier validity value for the folder.\n\nunmark\nExample:\n\n$imap->unmark(@msgs) or die \"Could not unmark: $@\\n\";\n\nThe unmark method accepts a list of one or more messages sequence numbers, or a single reference\nto an array of one or more message sequence numbers, as its argument(s). It then unsets the\n*\\Flagged* flag for those message(s). Of course, if the \"Uid\" parameter is set to a true value\nthen those message sequence numbers should really be unique message id's.\n\nNote that specifying \"$imap->unmark(@msgs)\" is just a shortcut for specifying\n\"$imap->unsetflag(\"Flagged\",@msgs)\".\n\nNote also that the *\\Flagged* flag is just one of many possible flags. This is a little\nconfusing, but you'll have to get used to the idea that among the reserved flags specified in\nRFC3501 is one name *\\Flagged*. There is no specific meaning for this flag; it means whatever\nthe mailbox owner (or delegate) wants it to mean when it is turned on.\n\nunseen\nExample:\n\nmy @unread = $imap->unseen or warn \"Could not find unseen msgs: $@\\n\";\n\nThe unseen method performs an IMAP SEARCH UNSEEN search against the selected folder and returns\nan array of sequence numbers of messages that have not yet been seen (ie their *\\Seen* flag is\nnot set). If the \"Uid\" parameter is true then an array of message UID's will be returned\ninstead. If called in scalar context than a pointer to the array (rather than the array itself)\nwill be returned.\n\nunseencount\nExample:\n\nforeach my $f ($imap->folders) {\nprint \"The $f folder has \",\n$imap->unseencount($f)||0, \" unseen messages.\\n\";\n}\n\nThe unseencount method accepts the name of a folder as an argument and returns the number of\nunseen messages in that folder. If no folder argument is provided then it returns the number of\nunseen messages in the currently selected Folder.\n\nunsetflag\nExample:\n\n$imap->unsetflag( \"\\Seen\", @msgs )\nor die \"unsetflag failed: $@\\n\";\n\nThe unsetflag method accepts the name of a flag as its first argument and a list of one or more\nmessages sequence numbers, or a single reference to an array of one or more message sequence\nnumbers, as its next argument(s). It then unsets the flag specified for those message(s). Of\ncourse, if the \"Uid\" parameter is set to a true value then those message sequence numbers had\nbetter be unique message id's, just as you'd expect.\n" } ] }, "Other IMAP Client Commands": { "content": "Until release 2.99, when you called a method which did not exist, they where automatically\ntranslated into an IMAP call with the same name via an AUTOLOAD hack. This \"feature\" was removed\nfor various reasons: people made typos in the capitalization of method names, and the program\nstill seemed to work correctly. Besides, it blocked further development of this module, because\npeople did not contribute their private extensions to the protocol implementation.\n\ncopy($msg, $folder)\nCopy a message from the currently selected folder in the folder whose name is in $folder\n\nsubscribe($folder)\nSubscribe to a folder\n\nCAUTION: Once again, remember to quote your quotes (or use the \"Quote\" method) if you want\nquotes to be part of the IMAP command string.\n\nYou can also use the default method to override the behavior of implemented IMAP methods by\nchanging the case of the method name, preferably to all-uppercase so as not to conflict with the\nClass method and accessor method namespace. For example, if you don't want the \"search\" method's\nbehavior (which returns a list of message numbers) but would rather have an array of raw data\nreturned from your \"search\" operation, you can issue the following snippet:\n\nmy @raw = $imap->SEARCH(\"SUBJECT\",\"Whatever...\");\n\nwhich is slightly more efficient than the equivalent:\n\n$imap->search(\"SUBJECT\",\"Whatever...\");\nmy @raw = $imap->Results;\n\nOf course you probably want the search results tucked nicely into a list for you anyway, in\nwhich case you might as well use the \"search\" method.\n", "subsections": [] }, "Parameters": { "content": "There are several parameters that influence the behavior of an IMAPClient object. Each is set by\nspecifying a named value pair during new method invocation as follows:\n\nmy $imap = Mail::IMAPClient->new ( parameter => \"value\",\nparameter2 => \"value\",\n...\n);\n\nParameters can also be set after an object has been instantiated by using the parameter's\neponymous accessor method like this:\n\nmy $imap = Mail::IMAPClient->new;\n$imap->parameter( \"value\");\n$imap->parameter2(\"value\");\n\nThe eponymous accessor methods can also be used without arguments to obtain the current value of\nthe parameter as follows:\n\nmy $imap = Mail::IMAPClient->new;\n$imap->parameter( \"value\");\n$imap->parameter2(\"value\");\n\n... # A whole bunch of awesome Perl code, omitted for brevity\n\nmy $forgot = $imap->parameter;\nmy $forgot2 = $imap->parameter2;\n\nNote that in these examples I'm using 'parameter' and 'parameter2' as generic parameter names.\nThe IMAPClient object doesn't actually have parameters named 'parameter' and 'parameter2'. On\nthe contrary, the available parameters are:\n", "subsections": [ { "name": "Authmechanism", "content": "Example:\n\n$imap->Authmechanism(\"CRAM-MD5\");\n# or\nmy $authmech = $imap->Authmechanism();\n\nIf specified, the *Authmechanism* causes the specified authentication mechanism to be used\nwhenever Mail::IMAPClient would otherwise invoke login. If the value specified for the\n*Authmechanism* parameter is not a valid authentication mechanism for your server then you will\nnever ever be able to log in again for the rest of your Perl script, probably. So you might want\nto check, like this:\n\nmy $authmech = \"CRAM-MD5\";\n$imap->hascapability($authmech) and $imap->Authmechanism($authmech);\n\nOf course if you know your server supports your favorite authentication mechanism then you know,\nso you can then include your *Authmechanism* with your new call, as in:\n\nmy $imap = Mail::IMAPClient->new(\nUser => $user,\nPassord => $passord,\nServer => $server,\nAuthmechanism => $authmech,\n%etc\n);\n\nIf *Authmechanism* is supplied but *Authcallback* is not then you had better be supporting one\nof the authentication mechanisms that Mail::IMAPClient supports \"out of the box\" (such as\nCRAM-MD5).\n" }, { "name": "Authcallback", "content": "Example:\n\n$imap->Authcallback( \\&callback );\n\nThis specifies a default callback to the default authentication mechanism (see \"Authmechanism\",\nabove). Together, these two methods replace automatic calls to login with automatic calls that\nlook like this (sort of):\n\n$imap->authenticate($imap->Authmechanism,$imap->Authcallback);\n\nIf *Authmechanism* is supplied but *Authcallback* is not then you had better be supporting one\nof the authentication mechanisms that Mail::IMAPClient supports \"out of the box\" (such as\nCRAM-MD5).\n" }, { "name": "Authuser", "content": "The *Authuser* parameter is used by the DIGEST-MD5 \"Authmechanism\".\n\nTypically when you authenticate the username specified in the User parameter is used. However,\nwhen using the DIGEST-MD5 *Authmechanism* the *Authuser* can be used to specify a different\nusername for the login.\n\nThis can be useful to mark messages as seen for the *Authuser* if you don't know the password of\nthe user as the seen state is often a per-user state.\n" }, { "name": "Buffer", "content": "Example:\n\n$Buffer = $imap->Buffer();\n# or:\n$imap->Buffer($newvalue);\n\nThe *Buffer* parameter sets the size of a block of I/O. It is ignored unless \"Fastio\", below,\nis set to a true value (the default), or unless you are using the \"migrate\" method. It's value\nshould be the number of bytes to attempt to read in one I/O operation. The default value is\n4096.\n\nWhen using the \"migrate\" method, you can often achieve dramatic improvements in throughput by\nadjusting this number upward. However, doing so also entails a memory cost, so if set too high\nyou risk losing all the benefits of the \"migrate\" method's chunking algorithm. Your program can\nthus terminate with an \"out of memory\" error and you'll have no one but yourself to blame.\n\nNote that, as hinted above, the *Buffer* parameter affects the behavior of the \"migrate\" method\nregardless of whether you have \"Fastio\" turned on. Believe me, you don't want to go around\nmigrating tons of mail without using buffered I/O!\n" }, { "name": "Clear", "content": "Example:\n\n$Clear = $imap->Clear();\n# or:\n$imap->Clear($integer);\n\nThe name of this parameter, for historical reasons, is somewhat misleading. It should be named\n*Wrap*, because it specifies how many transactions are stored in the wrapped history buffer. But\nit didn't always work that way; the buffer used to actually get cleared. The name though remains\nthe same in the interests of backwards compatibility.\n\n*Clear* specifies that the object's history buffer should be wrapped after every *n*\ntransactions, where *n* is the value specified for the *Clear* parameter. Calling the eponymous\nClear method without an argument will return the current value of the *Clear* parameter but will\nnot cause clear the history buffer to wrap.\n\nSetting *Clear* to 0 turns off automatic history buffer wrapping, and setting it to 1 turns off\nthe history buffer facility (except for the last transaction, which cannot be disabled without\nbreaking the IMAPClient module). Setting *Clear* to 0 will not cause an immediate clearing of\nthe history buffer; setting it to 1 (or any other number) will (except of course for that\ninevitable last transaction).\n\nThe default *Clear* value is set to five (5) in order to conserve memory.\n" }, { "name": "Compress", "content": "If set, Mail::IMAPClient attempts to enable use of the RFC4978 COMPRESS DEFLATE extension. This\nrequires that the server supports this CAPABILITY. This attribute can be set to a true value to\nenable or an ARRAYREF to control the arguments used in the call to\nCompress::Zlib::deflateInit().\n\nMail::IMAPClient will automatically use Compress::Zlib to deflate/inflate the data to/from the\nserver. This attribute is used in the \"login\" method.\n\nSee also \"compress\" and \"capability\".\n\nVersion note: attribute added in Mail::IMAPClient 3.30\n" }, { "name": "Debug", "content": "Example:\n\n$Debug = $imap->Debug();\n# or:\n$imap->Debug($trueorfalse);\n\nSets the debugging flag to either a true or false value. Can be supplied with the \"new\" method\ncall or separately by calling the Debug object method. Use of this parameter is strongly\nrecommended when debugging scripts and required when reporting bugs.\n" }, { "name": "Debugfh", "content": "Example:\n\n$Debugfh = $imap->Debugfh();\n# or:\n$imap->Debugfh($fileHandle);\n\nSpecifies the file handle to which debugging information should be printed. It can either a file\nhandle object reference or a file handle glob. The default is to print debugging info to STDERR.\n\nFor example, you can:\n\nuse Mail::IMAPClient;\nuse IO::File;\n# set $user, $pass, and $server here\nmy $dh = IO::File->new(\">debugging.output\")\nor die \"Can't open debugging.output: $!\\n\";\nmy $imap = Mail::IMAPClient->new(\nUser=>$user, Password=>$pass, Server=>$server, Debug=>1, Debugfh => $dh\n);\n\nwhich is the same as:\n\nuse Mail::IMAPClient;\nuse IO::File;\n# set $user, $pass, and $server here\nmy $imap = Mail::IMAPClient->new(\nUser => $user,\nPassword => $pass,\nServer => $server,\nDebug => \"yes, please\",\nDebugfh => IO::File->new(\">debugging.output\")\n|| die \"Can't open debugging.output: $!\\n\"\n);\n\nYou can also:\n\nuse Mail::IMAPClient;\n# set $user, $pass, and $server here\nopen(DBG,\">debugging.output\")\nor die \"Can't open debugging.output: $!\\n\";\nmy $imap = Mail::IMAPClient->new(\nUser=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debugfh => *DBG\n);\n\nSpecifying this parameter is not very useful unless \"Debug\" is set to a true value.\n" }, { "name": "Domain", "content": "The *Domain* parameter is used by the NTLM \"Authmechanism\". The domain is an optional parameter\nfor NTLM authentication.\n" }, { "name": "EnableServerResponseInLiteral", "content": "Removed in 2.9901 (now autodetect)\n" }, { "name": "Fastio", "content": "Example:\n\n$Fastio = $imap->Fastio();\n# or:\n$imap->Fastio($trueorfalse);\n\nThe *Fastio* parameter controls whether or not the Mail::IMAPClient object will attempt to use\nnon-blocking I/O on the IMAP socket. It is turned on by default (unless the caller provides the\nsocket to be used).\n\nSee also \"Buffer\".\n" }, { "name": "Folder", "content": "Example:\n\n$Folder = $imap->Folder();\n# or:\n$imap->Folder($newvalue);\n\nThe *Folder* parameter returns the name of the currently-selected folder (in case you forgot).\nIt can also be used to set the name of the currently selected folder, which is completely\nunnecessary if you used the \"select\" method (or \"select\"'s read-only equivalent, the \"examine\"\nmethod) to select it.\n\nNote that setting the *Folder* parameter does not automatically select a new folder; you use the\n\"select\" or \"examine\" object methods for that. Generally, the *Folder* parameter should only be\nqueried (by using the no-argument form of the Folder method). You will only need to set the\n*Folder* parameter if you use some mysterious technique of your own for selecting a folder,\nwhich you probably won't do.\n" }, { "name": "Ignoresizeerrors", "content": "Certain (caching) servers, like Exchange 2007, often report the wrong message size. Instead of\nchopping the message into a size that it fits the specified size, the reported size will be\nsimply ignored when this parameter is set to 1.\n" }, { "name": "Keepalive", "content": "Some firewalls and network gear like to timeout connections prematurely if the connection sits\nidle. The Keepalive parameter, when set to a true value, affects the behavior of \"new\" and\n\"Socket\" by enabling SOKEEPALIVE on the socket.\n\nVersion note: attribute added in Mail::IMAPClient 3.17\n" }, { "name": "Maxcommandlength", "content": "The Maxcommandlength attribute is used by fetch() to limit length of commands sent to a server.\nThe default is 1000 chars, following the recommendation of RFC2683 section 3.2.1.5.\n\nNote: this attribute should also be used for several other methods but this has not yet been\nimplemented please feel free to file bugs for methods where you run into problems with this.\n\nThis attribute should remove the need for utilities like imapsync to create their own split()\nfunctions and instead allows Mail::IMAPClient to DWIM.\n\nIn practice, this parameter has proven to be useful to overcome a limit of 8000 octets for\nUW-IMAPD and 16384 octets for Courier/Cyrus IMAP servers.\n\nVersion note: attribute added in Mail::IMAPClient 3.17\n" }, { "name": "Maxtemperrors", "content": "Example:\n\n$Maxtemperrors = $imap->Maxtemperrors();\n# or:\n$imap->Maxtemperrors($number);\n\nThe *Maxtemperrors* parameter specifies the number of times a read or write operation is allowed\nto fail on a \"Resource Temporarily Available\" (e.g. EAGAIN) error. The default setting is\n*undef* which means there is no limit.\n\nSetting this parameter to the string \"unlimited\" (instead of undef) to ignore \"Resource\nTemporarily Unavailable\" errors is deprecated.\n\nNote: This setting should be used with caution and may be removed in a future release. Setting\nthis can cause methods to return to the caller before data is received (and then handled)\nproperly thereby possibly then leaving the module in a bad state. In the future, this behavior\nmay be changed in an attempt to avoid this situation.\n" }, { "name": "Password", "content": "Example:\n\n$Password = $imap->Password();\n# or:\n$imap->Password($newvalue);\n\nSpecifies the password to use when logging into the IMAP service on the host specified in the\n*Server* parameter as the user specified in the *User* parameter. Can be supplied with the new\nmethod call or separately by calling the Password object method.\n\nIf *Server*, *User*, and *Password* are all provided to the \"new\" method, then the newly\ninstantiated object will be connected to the host specified in *Server* (at either the port\nspecified in *Port* or the default port 143) and then logged on as the user specified in the\n*User* parameter (using the password provided in the *Password* parameter). See the discussion\nof the \"new\" method, below.\n" }, { "name": "Peek", "content": "Example:\n\n$Peek = $imap->Peek();\n# or:\n$imap->Peek($trueorfalse);\n\nSetting *Peek* to a true value will prevent the \"bodystring\", \"messagestring\" and\n\"messagetofile\" methods from automatically setting the *\\Seen* flag. Setting \"Peek\" to 0\n(zero) will force \"bodystring\", \"messagestring\", \"messagetofile\", and \"parseheaders\" to\nalways set the *\\Seen* flag.\n\nThe default is to set the seen flag whenever you fetch the body of a message but not when you\njust fetch the headers. Passing *undef* to the eponymous Peek method will reset the *Peek*\nparameter to its pristine, default state.\n" }, { "name": "Port", "content": "Example:\n\n$Port = $imap->Port();\n# or:\n$imap->Port($newvalue);\n\nSpecifies the port on which the IMAP server is listening. A default value of 993 (if \"Ssl\" is\ntrue) or 143 is set during a call to \"connect\" if no value is provided by the caller. This\nargument can be supplied with the \"new\" method call or separately by calling the \"Port\" object\nmethod.\n" }, { "name": "Prewritemethod", "content": "*Prewritemethod* parameter should contain a reference to a subroutine that will do \"special\nthings\" to data before it is sent to the IMAP server (such as encryption or signing).\n\nThis method will be called immediately prior to sending an IMAP client command to the server.\nIts first argument is a reference to the *Mail::IMAPClient* object and the second argument is a\nstring containing the command that will be sent to the server. Your *Prewritemethod* should\nreturn a string that has been signed or encrypted or whatever; this returned string is what will\nactually be sent to the server.\n\nYour *Prewritemethod* will probably need to know more than this to do whatever it does. It is\nrecommended that you tuck all other pertinent information into a hash, and store a reference to\nthis hash somewhere where your method can get to it, possibly in the *Mail::IMAPClient* object\nitself.\n\nNote that this method should not actually send anything over the socket connection to the\nserver; it merely converts data prior to sending.\n\nSee also \"Readmethod\".\n" }, { "name": "Ranges", "content": "Example:\n\n$imap->Ranges(1);\n# or:\nmy $search = $imap->search(@searchargs);\nif ( $imap->Ranges) { # $search is a MessageSet object\nprint \"This is my condensed search result: $search\\n\";\nprint \"This is every message in the search result: \",\njoin(\",\",@$search),\"\\n;\n}\n\nIf set to a true value, then the \"search\" method will return a Mail::IMAPClient::MessageSet\nobject if called in a scalar context, instead of the array reference that fetch normally returns\nwhen called in a scalar context. If set to zero or if undefined, then search will continue to\nreturn an array reference when called in scalar context.\n\nThis parameter has no affect on the search method when search is called in a list context.\n" }, { "name": "RawSocket", "content": "Example: $socket = $imap->RawSocket; # or: $imap->RawSocket($socketh);\n\nThe *RawSocket* method can be used to obtain the socket handle of the current connection (say,\nto do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace\nthe current socket with a new handle (for instance an SSL handle, see IO::Socket::SSL, but be\nsure to see the \"Socket\" method as well).\n\nIf you supply a socket handle yourself, either by doing something like:\n\n$imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );\n\nor by doing something like:\n\n$imap = Mail::IMAPClient->new(User => $user,\nPassword => $pass, Server => $host);\n# blah blah blah\n$imap->RawSocket($ssl);\n\nthen it will be up to you to establish the connection AND to authenticate, either via the\n\"login\" method, or the fancier \"authenticate\", or, since you know so much anyway, by just doing\nraw I/O against the socket until you're logged in. If you do any of this then you should also\nset the \"State\" parameter yourself to reflect the current state of the object (i.e. Connected,\nAuthenticated, etc).\n\nNote that no operation will be attempted on the socket when this method is called. In\nparticular, after the TCP connections towards the IMAP server is established, the protocol\nmandates the server to send an initial greeting message, and you will have to explicitly cope\nwith this message before doing any other operation, e.g. trying to call \"login\". Caveat emptor.\n\nFor a more DWIM approach to setting the socket see \"Socket\".\n" }, { "name": "Readmethod", "content": "Example:\n\n$imap->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET\nsub {\nmy ( $self, $handle, $buffer, $count, $offset ) = @;\nmy $rc = sysread( $handle, $$buffer, $count, $offset );\n# do something useful here...\n}\n);\n\nReadmethod should contain a reference to a subroutine that will replace sysread. The subroutine\nwill be passed the following arguments: first the used Mail::IMAPClient object. Second, a\nreference to a socket. Third, a reference to a scalar variable into which data is read (BUFFER).\nThe data placed here should be \"finished data\", so if you are decrypting or removing signatures\nthen be sure to do that before you place data into this buffer. Fourth, the number of bytes\nrequested to be read; the LENGTH of the request. Lastly, the OFFSET into the BUFFER where the\ndata should be read. If not supplied it should default to zero.\n\nNote that this method completely replaces reads from the connection to the server, so if you\ndefine one of these then your subroutine will have to actually do the read. It is for things\nlike this that we have the \"Socket\" parameter and eponymous accessor method.\n\nYour *Readmethod* will probably need to know more than this to do whatever it does. It is\nrecommended that you tuck all other pertinent information into a hash, and store a reference to\nthis hash somewhere where your method can get to it, possibly in the *Mail::IMAPClient* object\nitself.\n\nSee also \"Prewritemethod\".\n" }, { "name": "Readmoremethod", "content": "Readmoremethod should contain a reference to a subroutine that will replace/enhance the behavior\nof the internal readmore() method. The subroutine will be passed the following arguments:\nfirst the used Mail::IMAPClient object. Second, a reference to a socket. Third, a timeout value\nwhich is used as the timeout value for CORE::select() by default. Depending upon\nchanges/features introduced by Readmethod changes may be required here.\n\nVersion note: attribute added in Mail::IMAPClient 3.30\n" }, { "name": "Reconnectretry", "content": "If an IMAP connection sits idle too long, the connection may be closed by the server or\nfirewall, etc. The Reconnectretry parameter, when given a positive integer value, will cause\nMail::IMAPClient to retrying IMAP commands up to X times when an EPIPE or ECONNRESET error\noccurs. This is disabled (0) by default.\n\nSee also \"Keepalive\"\n\nVersion note: attribute added in Mail::IMAPClient 3.17\n" }, { "name": "Server", "content": "Example:\n\n$Server = $imap->Server();\n# or:\n$imap->Server($hostname);\n\nSpecifies the hostname or IP address of the host running the IMAP server. If provided as part of\nthe \"new\" method call, then the new IMAP object will automatically be connected at the time of\ninstantiation. (See the \"new\" method, below.) Can be supplied with the \"new\" method call or\nseparately by calling the Server object method.\n" }, { "name": "Showcredentials", "content": "Normally debugging output will mask the login credentials when the plain text login mechanism is\nused. Setting *Showcredentials* to a true value will suppress this, so that you can see the\nstring being passed back and forth during plain text login. Only set this to true when you are\ndebugging problems with the IMAP LOGIN command, and then turn it off right away when you're\nfinished working on that problem.\n\nExample:\n\nprint \"This is very risky!\\n\" if $imap->Showcredentials();\n# or:\n$imap->Showcredentials(0); # mask credentials again\n" }, { "name": "Socket", "content": "PLEASE NOTE The semantics of this method has changed as of version 2.9904 of this module. If\nyou need the old semantics use \"RawSocket\".\n\nExample:\n\n$Socket = $imap->Socket();\n# or:\n$imap->Socket($socketfh);\n\nThe *Socket* method can be used to obtain the socket handle of the current connection. This may\nbe necessary to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or\nto replace the current socket with a new handle (for instance an SSL handle, see\nIO::Socket::SSL).\n\nIf you supply a socket handle yourself, either by doing something like:\n\n$imap = Mail::IMAPClient->new( Socket => $sock, User => ... );\n\nor by doing something like:\n\n$imap = Mail::IMAPClient->new(\nUser => $user, Password => $pass, Server => $host\n);\n$imap->Socket($ssl);\n\nthen you are responsible for establishing the connection, i.e. make sure that $ssl in the\nexample is a valid and connected socket.\n\nThis method is primarily used to provide a drop-in replacement for IO::Socket::(INET|IP), used\nby \"connect\" by default. In fact, this method is called by \"connect\" itself after having\nestablished a suitable IO::Socket::(INET|IP) socket connection towards the target server; for\nthis reason, this method also carries the normal operations associated with \"connect\", namely:\n\n* read the initial greeting message from the server;\n\n* call \"login\" if the conditions apply (see \"connect\" for details);\n\n* leave the *Mail::IMAPClient* object in a suitable state.\n\nFor these reasons, the following example will work \"out of the box\":\n\nuse IO::Socket::SSL;\nmy $imap = Mail::IMAPClient->new\n( User => 'your-username',\nPassword => 'your-password',\nSocket => IO::Socket::SSL->new\n( Proto => 'tcp',\nPeerAddr => 'some.imap.server',\nPeerPort => 993, # IMAP over SSL standard port\n),\n);\n\nIf you need more control over the socket, e.g. you have to implement a fancier authentication\nmethod, see \"RawSocket\".\n" }, { "name": "Starttls", "content": "If an IMAP connection must start TLS/SSL after connecting to a server then set this attribute.\nIf the value is set to an arrayref then they will be used as arguments to\nIO::Socket::SSL->startSSL. By default this connection is set to blocking while establishing the\nconnection with a timeout of 30 seconds. The socket will be reset to the original\nblocking/non-blocking value after a successful TLS negotiation has occurred. The arguments used\nin the call to startSSL can be controlled by setting this attribute to an ARRAY reference\ncontaining the desired arguments.\n\nVersion note: attribute added in Mail::IMAPClient 3.22\n" }, { "name": "Socketargs", "content": "The arguments used in the call to IO::Socket::{UNIX|INET|IP|SSL}->new can be controlled by\nsetting this attribute to an ARRAY reference containing the desired arguments.\n\nFor example, to always pass MultiHomed => 1 to IO::Socket::...->new the following can be used:\n\n$imap = Mail::IMAPClient->new(\n..., Socketargs => [ MultiHomed => 1 ], ...\n);\n\nSee also \"Ssl\" for specific control of the args to IO::Socket::SSL.\n\nVersion note: attribute added in Mail::IMAPClient 3.34\n" }, { "name": "Ssl", "content": "If an IMAP connection requires SSL you can set the Ssl attribute to '1' and Mail::IMAPClient\nwill automatically use IO::Socket::SSL instead of IO::Socket::(INET|IP) to connect to the\nserver. This attribute is used in the \"connect\" method. The arguments used in the call to\nIO::Socket::SSL->new can be controlled by setting this attribute to an ARRAY reference\ncontaining the desired arguments.\n\nSee also \"connect\" for details on connection initiation and \"Socket\" and \"Rawsocket\" if you need\nto take more control of connection management.\n\nVersion note: attribute added in Mail::IMAPClient 3.18\n" }, { "name": "Supportedflags", "content": "Especially when \"migrate()\" is used, the receiving peer may need to be configured explicitly\nwith the list of supported flags; that may be different from the source IMAP server.\n\nThe names are to be specified as an ARRAY. Black-slashes and casing will be ignored.\n\nYou may also specify a CODE reference, which will be called for each of the flags separately. In\nthis case, the flags are not (yet) normalized. The returned lists of the CODE calls are shape\nthe resulting flag list.\n" }, { "name": "Timeout", "content": "Example:\n\n$Timeout = $imap->Timeout();\n# or:\n$imap->Timeout($seconds);\n\nSpecifies the timeout value in seconds for reads (default is 600). Specifying a *Timeout* will\nprevent Mail::IMAPClient from blocking in a read.\n\nSince timeouts are implemented via the Perl select operator, the *Timeout* parameter may be set\nto a fractional number of seconds. Setting *Timeout* to 0 (zero) disables the timeout feature.\n" }, { "name": "Uid", "content": "Example:\n\n$Uid = $imap->Uid();\n# or:\n$imap->Uid($trueorfalse);\n\nIf \"Uid\" is set to a true value (i.e. 1) then the behavior of the \"fetch\", \"search\", \"copy\", and\n\"store\" methods (and their derivatives) is changed so that arguments that would otherwise be\nmessage sequence numbers are treated as message UID's and so that return values (in the case of\nthe \"search\" method and its derivatives) that would normally be message sequence numbers are\ninstead message UID's.\n\nInternally this is implemented as a switch that, if turned on, causes methods that would\notherwise issue an IMAP FETCH, STORE, SEARCH, or COPY client command to instead issue UID FETCH,\nUID STORE, UID SEARCH, or UID COPY, respectively. The main difference between message sequence\nnumbers and message UID's is that, according to RFC3501, UID's must not change during a session\nand should not change between sessions, and must never be reused. Sequence numbers do not have\nthat same guarantee and in fact may be reused right away.\n\nSince folder names also have a unique identifier (UIDVALIDITY), which is provided when the\nfolder is \"select\"ed or \"examine\"d or by doing something like\n\"$imap->status($folder,\"UIDVALIDITY\"), it is possible to uniquely identify every message on the\nserver, although normally you won't need to bother.\n\nThe methods currently affected by turning on the \"Uid\" flag are:\n\ncopy fetch\nsearch store\nmessagestring messageuid\nbodystring flags\nmove size\nparseheaders thread\n\nNote that if for some reason you only want the \"Uid\" parameter turned on for one command, then\nyou can choose between the following two snippets, which are equivalent:\n\nExample 1:\n\n$imap->Uid(1);\nmy @uids = $imap->search('SUBJECT',\"Just a silly test\"); #\n$imap->Uid(0);\n\nExample 2:\n\nmy @uids;\nforeach $r ($imap->UID(\"SEARCH\",\"SUBJECT\",\"Just a silly test\") {\nchomp $r;\n$r =~ s/\\r$//;\n$r =~ s/^\\*\\s+SEARCH\\s+// or next;\npush @uids, grep(/\\d/,(split(/\\s+/,$r)));\n}\n\nIn the second example, we used the default method to issue the UID IMAP client command, being\ncareful to use an all-uppercase method name so as not to inadvertently call the \"Uid\" accessor\nmethod. Then we parsed out the message UIDs manually, since we don't have the benefit of the\nbuilt-in \"search\" method doing it for us.\n\nPlease be very careful when turning the \"Uid\" parameter on and off throughout a script. If you\nloose track of whether you've got the \"Uid\" parameter turned on you might do something sad, like\ndeleting the wrong message. Remember, like all eponymous accessor methods, the Uid method\nwithout arguments will return the current value for the \"Uid\" parameter, so do yourself a favor\nand check. The safest approach is probably to turn it on at the beginning (or just let it\ndefault to being on) and then leave it on. (Remember that leaving it turned off can lead to\nproblems if changes to a folder's contents cause resequencing.)\n\nBy default, the \"Uid\" parameter is turned on.\n" }, { "name": "User", "content": "Example:\n\n$User = $imap->User();\n# or:\n$imap->User($userid);\n\nSpecifies the userid to use when logging into the IMAP service. Can be supplied with the \"new\"\nmethod call or separately by calling the User object method.\n\nParameters can be set during \"new\" method invocation by passing named parameter/value pairs to\nthe method, or later by calling the parameter's eponymous object method.\n" } ] }, "Status Methods": { "content": "There are several object methods that return the status of the object. They can be used at any\ntime to check the status of an IMAPClient object, but are particularly useful for determining\nthe cause of failure when a connection and login are attempted as part of a single \"new\" method\ninvocation. The status methods are:\n", "subsections": [ { "name": "Escapedhistory", "content": "Example:\n\nmy @history = $imap->Escapedhistory;\n\nThe Escapedhistory method is almost identical to the History method. Unlike the History method,\nhowever, server output transmitted literally will be wrapped in double quotes, with all double\nquotes, backslashes escaped. If called in a scalar context, Escapedhistory returns an array\nreference rather than an array.\n\nEscapedhistory is useful if you are retrieving output and processing it manually, and you are\ndepending on the above special characters to delimit the data. It is not useful when retrieving\nmessage contents; use messagestring or bodystring for that.\n" }, { "name": "Escapedresults", "content": "Example:\n\nmy @results = $imap->Escapedresults;\n\nThe Escapedresults method is almost identical to the Results method. Unlike the Results method,\nhowever, server output transmitted literally will be wrapped in double quotes, with all double\nquotes, backslashes escaped. If called in a scalar context, Escapedresults returns an array\nreference rather than an array.\n\nEscapedresults is useful if you are retrieving output and processing it manually, and you are\ndepending on the above special characters to delimit the data. It is not useful when retrieving\nmessage contents; use messagestring or bodystring for that.\n" }, { "name": "History", "content": "Example:\n\nmy @history = $imap->History;\n\nThe History method is almost identical to the \"Results\" method. Unlike the \"Results\" method,\nhowever, the IMAP command that was issued to create the results being returned is not included\nin the returned results. If called in a scalar context, History returns an array reference\nrather than an array.\n" }, { "name": "IsUnconnected", "content": "returns a true value if the object is currently in an \"Unconnected\" state.\n" }, { "name": "IsConnected", "content": "returns a true value if the object is currently in either a \"Connected\", \"Authenticated\", or\n\"Selected\" state.\n" }, { "name": "IsAuthenticated", "content": "returns a true value if the object is currently in either an \"Authenticated\" or \"Selected\"\nstate.\n" }, { "name": "IsSelected", "content": "returns a true value if the object is currently in a \"Selected\" state.\n" }, { "name": "LastError", "content": "Internally LastError is implemented just like a parameter (as described in \"Parameters\", above).\nThere is a *LastError* attribute and an eponymous accessor method which returns the *LastError*\ntext string describing the last error condition encountered by the server.\n\nNote that some errors are more serious than others, so *LastError*'s value is only meaningful if\nyou encounter an error condition that you don't like. For example, if you use the \"exists\"\nmethod to see if a folder exists and the folder does not exist, then an error message will be\nrecorded in *LastError* even though this is not a particularly serious error. On the other hand,\nif you didn't use \"exists\" and just tried to \"select\" a non-existing folder, then \"select\" would\nreturn \"undef\" after setting *LastError* to something like \"NO SELECT failed: Can't open mailbox\n\"mailbox\": no such mailbox\". At this point it would be useful to print out the contents of\n*LastError* as you die.\n" }, { "name": "LastIMAPCommand", "content": "New in version 2.0.4, LastIMAPCommand returns the exact IMAP command string to be sent to the\nserver. Useful mainly in constructing error messages when \"LastError\" just isn't enough.\n" }, { "name": "Report", "content": "The Report method returns an array containing a history of the IMAP session up to the point that\nReport was called. It is primarily meant to assist in debugging but can also be used to retrieve\nraw output for manual parsing. The value of the \"Clear\" parameter controls how many transactions\nare in the report.\n" }, { "name": "Results", "content": "The Results method returns an array containing the results of one IMAP client command. It\naccepts one argument, the transaction number of the command whose results are to be returned. If\ntransaction number is unspecified then Results returns the results of the last IMAP client\ncommand issued. If called in a scalar context, Results returns an array reference rather than an\narray.\n" }, { "name": "State", "content": "The State method returns a numerical value that indicates the current status of the IMAPClient\nobject. If invoked with an argument, it will set the object's state to that value. If invoked\nwithout an argument, it behaves just like \"Status\", below.\n\nNormally you will not have to invoke this function. An exception is if you are bypassing the\nMail::IMAPClient module's \"connect\" and/or \"login\" modules to set up your own connection (say,\nfor example, over a secure socket), in which case you must manually do what the \"connect\" and\n\"login\" methods would otherwise do for you.\n" }, { "name": "Status", "content": "The Status method returns a numerical value that indicates the current status of the IMAPClient\nobject. (Not to be confused with the \"status\" method, all lower-case, which is the\nimplementation of the *STATUS* IMAP client command.)\n" }, { "name": "Transaction", "content": "The Transaction method returns the tag value (or transaction number) of the last IMAP client\ncommand.\n" } ] }, "Custom Authentication Mechanisms": { "content": "If you just want to use plain text authentication or any of the supported \"Advanced\nAuthentication Mechanisms\" then there is no need to read this section.\n\nThere are a number of methods and parameters that you can use to build your own authentication\nmechanism. All of the methods and parameters discussed in this section are described in more\ndetail elsewhere in this document. This section provides a starting point for building your own\nauthentication mechanism.\n\nThere are *many* authentication mechanisms out there, if your preferred mechanism is not\ncurrently supported but you manage to get it working please consider donating them to this\nmodule. Patches and suggestions are always welcome.\n\nSupport for add-on authentication mechanisms in Mail::IMAPClient is pretty straight forward. You\ncreate a callback to be used to provide the response to the server's challenge. The\n\"Authcallback\" parameter contains a reference to the callback, which can be an anonymous\nsubroutine or a named subroutine. Then, you identify your authentication mechanism, either via\nthe \"Authmechanism\" parameter or as an argument to \"authenticate\".\n\nYou may also need to provide a subroutine to encrypt (or whatever) data before it is sent to the\nserver. The \"Prewritemethod\" parameter must contain a reference to this subroutine. And, you\nwill need to decrypt data from the server; a reference to the subroutine that does this must be\nstored in the \"Readmethod\" parameter.\n\nThis framework is based on the assumptions that a) the mechanism you are using requires a\nchallenge-response exchange, and b) the mechanism does not fundamentally alter the exchange\nbetween client and server but merely wraps the exchange in a layer of encryption. It also\nassumes that the line-oriented nature of the IMAP conversation is preserved; authentication\nmechanisms that break up messages into blocks of a predetermined size may still be possible but\nwill certainly be more difficult to implement.\n\nAlternatively, if you have access to imtest, a utility included in the Cyrus IMAP distribution,\nyou can use that utility to broker your communications with the IMAP server. This is quite easy\nto implement. An example, examples/imtestExample.pl, can be found in the \"examples\" subdirectory\nof the source distribution.\n\nThe following list summarizes the methods and parameters that you may find useful in\nimplementing advanced authentication:\n\nThe authenticate method\nThe \"authenticate\" method uses the \"Authmechanism\" parameter to determine how to\nauthenticate with the server see the method documentation for details.\n\nSocket and RawSocket\nThe \"Socket\" and \"RawSocket\" methods provide access to the socket connection. The socket is\ntypically automatically created by the \"connect\" method, but if you are implementing an\nadvanced authentication technique you may choose to set up your own socket connection and\nthen set this parameter manually, bypassing the connect method completely. This is also\nuseful if you want to use IO::Socket::(INET|IP) alternatives like IO::Socket::SSL and need\nfull control.\n\n\"RawSocket\" simply gets/sets the socket without attempting any interaction on it. In this\ncase, you have to be sure to handle all the preliminary operations and manually set the\nMail::IMAPClient object in sync with its actual status with respect to this socket (see\nbelow for additional parameters regarding this, especially the \"State\" parameter).\n\nUnlike \"RawSocket\", \"Socket\" attempts to carry on preliminary connection phases if the\nconditions apply. If both parameters are present, this takes the precedence over\n\"RawSocket\". If \"Starttls\" is set, then the \"starttls\" method will be called by \"Socket\".\n\nPLEASE NOTE As of version 2.9904 of this module, semantics for \"Socket\" have changed to\nmake it more \"DWIM\". \"RawSocket\" was introduced as a replacement for the \"Socket\" parameter\nin older version.\n\nState, Server, User, Password, Proxy and Domain Parameters\nIf you need to make your own connection to the server and perform your authentication\nmanually, then you can set these parameters to keep your Mail::IMAPClient object in sync\nwith its actual status. Of these, only the \"State\" parameter is always necessary. The others\nneed to be set only if you think your program will need them later.\n\nAuthmechanism\nSet this to the value that AUTHENTICATE should send to the server as the authentication\nmechanism. If you are brokering your own authentication then this parameter may be less\nuseful. It exists primarily so that you can set it when you call \"new\" to instantiate your\nobject. The \"new\" method will call \"connect\", which will call \"login\". If \"login\" sees that\nyou have set an Authmechanism then it will call authenticate, using your Authmechanism and\nAuthcallback parameters as arguments.\n\nAuthcallback\nThe \"Authcallback\", if set, holds a pointer to a subroutine (CODEREF). The \"login\" method\nwill use this as the callback argument to the authenticate method if the Authmechanism and\nAuthcallback parameters are both set. If you set Authmechanism but not Authcallback then the\ndefault callback for your mechanism will be used. All supported authentication mechanisms\nhave a default callback; in every other case not supplying the callback results in an error.\n\nMost advanced authentication mechanisms require a challenge-response exchange. After the\n\"authenticate\" method sends \" AUTHENTICATE \\015\\012\" to the IMAP server,\nthe server replies with a challenge. The \"authenticate\" method then invokes the code whose\nreference is stored in the Authcallback parameter as follows:\n\n$Authcallback->( $challenge, $imap )\n\nwhere $Authcallback is the code reference stored in the Authcallback parameter, $challenge\nis the challenge received from the IMAP server, and $imap is a pointer to the\nMail::IMAPClient object. The return value from the Authcallback routine should be the\nresponse to the challenge, and that return value will be sent by the \"authenticate\" method\nto the server.\n\nPrewritemethod/Readmethod\nThe Prewritemethod can hold a subroutine that will do whatever encryption is necessary and\nthen return the result to the caller so it in turn can be sent to the server.\n\nThe Readmethod can hold a subroutine to be used to replace sysread usually performed by\nMail::IMAPClient.\n\nSee \"Prewritemethod\" and \"Readmethod\" for details.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Please file bug reports via https://github.com/plobbes/mail-imapclient/issues\n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "Copyright (C) 1999-2003 The Kernen Group, Inc.\nCopyright (C) 2007-2009 Mark Overmeer\nCopyright (C) 2010-2021 Phil Pearl (Lobbes)\nAll rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may\nhave available.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See\neither the GNU General Public License or the Artistic License for more details.\n", "subsections": [] } } } }