{ "content": [ { "type": "text", "text": "# Net::IMAP::Simple (perldoc)\n\n## NAME\n\nNet::IMAP::Simple - Perl extension for simple IMAP account handling.\n\n## SYNOPSIS\n\nuse strict;\nuse warnings;\nuse Net::IMAP::Simple;\nuse Email::Simple;\n# Create the object\nmy $imap = Net::IMAP::Simple->new('imap.example.com') ||\ndie \"Unable to connect to IMAP: $Net::IMAP::Simple::errstr\\n\";\n# Log on\nif(!$imap->login('user','pass')){\nprint STDERR \"Login failed: \" . $imap->errstr . \"\\n\";\nexit(64);\n}\n# Print the subject's of all the messages in the INBOX\nmy $nm = $imap->select('INBOX');\nfor(my $i = 1; $i <= $nm; $i++){\nif($imap->seen($i)){\nprint \"*\";\n} else {\nprint \" \";\n}\nmy $es = Email::Simple->new(join '', @{ $imap->top($i) } );\nprintf(\"[%03d] %s\\n\", $i, $es->header('Subject'));\n}\n$imap->quit;\n\n## DESCRIPTION\n\nThis module is a simple way to access IMAP accounts.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OBJECT CREATION METHOD**\n- **PREAUTH**\n- **METHODS**\n- **SEARCHING**\n- **OTHER NOTES**\n- **AUTHOR**\n- **COPYRIGHT**\n- **LICENSE**\n- **BUGS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Net::IMAP::Simple", "section": "", "mode": "perldoc", "summary": "Net::IMAP::Simple - Perl extension for simple IMAP account handling.", "synopsis": "use strict;\nuse warnings;\nuse Net::IMAP::Simple;\nuse Email::Simple;\n# Create the object\nmy $imap = Net::IMAP::Simple->new('imap.example.com') ||\ndie \"Unable to connect to IMAP: $Net::IMAP::Simple::errstr\\n\";\n# Log on\nif(!$imap->login('user','pass')){\nprint STDERR \"Login failed: \" . $imap->errstr . \"\\n\";\nexit(64);\n}\n# Print the subject's of all the messages in the INBOX\nmy $nm = $imap->select('INBOX');\nfor(my $i = 1; $i <= $nm; $i++){\nif($imap->seen($i)){\nprint \"*\";\n} else {\nprint \" \";\n}\nmy $es = Email::Simple->new(join '', @{ $imap->top($i) } );\nprintf(\"[%03d] %s\\n\", $i, $es->header('Subject'));\n}\n$imap->quit;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 32, "subsections": [] }, { "name": "DESCRIPTION", "lines": 2, "subsections": [] }, { "name": "OBJECT CREATION METHOD", "lines": 88, "subsections": [] }, { "name": "PREAUTH", "lines": 12, "subsections": [] }, { "name": "METHODS", "lines": 475, "subsections": [] }, { "name": "SEARCHING", "lines": 143, "subsections": [] }, { "name": "OTHER NOTES", "lines": 8, "subsections": [] }, { "name": "AUTHOR", "lines": 12, "subsections": [] }, { "name": "COPYRIGHT", "lines": 6, "subsections": [] }, { "name": "LICENSE", "lines": 9, "subsections": [] }, { "name": "BUGS", "lines": 5, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Net::IMAP::Simple - Perl extension for simple IMAP account handling.\n", "subsections": [] }, "SYNOPSIS": { "content": "use strict;\nuse warnings;\nuse Net::IMAP::Simple;\nuse Email::Simple;\n\n# Create the object\nmy $imap = Net::IMAP::Simple->new('imap.example.com') ||\ndie \"Unable to connect to IMAP: $Net::IMAP::Simple::errstr\\n\";\n\n# Log on\nif(!$imap->login('user','pass')){\nprint STDERR \"Login failed: \" . $imap->errstr . \"\\n\";\nexit(64);\n}\n\n# Print the subject's of all the messages in the INBOX\nmy $nm = $imap->select('INBOX');\n\nfor(my $i = 1; $i <= $nm; $i++){\nif($imap->seen($i)){\nprint \"*\";\n} else {\nprint \" \";\n}\n\nmy $es = Email::Simple->new(join '', @{ $imap->top($i) } );\n\nprintf(\"[%03d] %s\\n\", $i, $es->header('Subject'));\n}\n\n$imap->quit;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module is a simple way to access IMAP accounts.\n", "subsections": [] }, "OBJECT CREATION METHOD": { "content": "my $imap = Net::IMAP::Simple->new( $server [ :port ]);\n\n# OR\n\nmy $imap = Net::IMAP::Simple->new( $server [, optionname => optionvalue ] );\n\nnew\nThis class method constructs a new Net::IMAP::Simple object. It takes one required parameter\nwhich is the server to connect to, and additional optional parameters.\n\nThe server parameter may specify just the server, or both the server and port number. To specify\nan alternate port, separate it from the server with a colon (\":\"), \"example.com:5143\".\n\nOn success an object is returned. On failure, nothing is returned and an error message is set to\n$Net::IMAP::Simple.\n\nSee \"PREAUTH\" below for a special hostname invocation that doesn't use Sockets (internally).\n\nOptions are provided as a hash to \"new()\":\n\nport => int\nAssign the port number (default: 143)\n\ntimeout => int (default: 90)\nConnection timeout in seconds.\n\nretry => int (default: 1)\nAttempt to retry the connection attmpt (x) times before giving up\n\nretrydelay => int (default: 5)\nWait (x) seconds before retrying a connection attempt\n\nusev6 => BOOL\nIf set to true, attempt to use IPv6 sockets rather than IPv4 sockets.\n\nThis option requires the IO::Socket::INET6 module\n\nusessl => BOOL\nIf set to true, attempt to use IO::Socket::SSL sockets rather than vanilla sockets.\n\nNote that no attempt is made to check the certificate validity by default. This is terrible\npersonal security but matches the previous behavior of this module. Please consider using\n\"findssldefaults\" below.\n\nThis option requires the IO::Socket::SSL module\n\nsslversion => version\nThis should be one or more of the following (space separated): SSLv3 SSLv2 TLSv1. If you\nspecify, for example, \"SSLv3 SSLv2\" then IO::Socket::SSL will attempt auto negotiation. At\nthe time of this writing, the default string was v3/v2 auto negotiation -- it may have\nchanged by the time you read this.\n\nWarning: setting this will also set \"usessl\".\n\nfindssldefaults => []\nLooks in some standard places for CA certificate libraries and if found sets reasonable\ndefaults along the lines of the following.\n\nssloptions => [ SSLcapath => \"/etc/ssl/certs/\",\nSSLverifymode => IO::Socket::SSL::SSLVERIFYPEER() ]\n\nWarning: setting this will also set \"usessl\".\n\nssloptions => []\nYou may provide your own IO::Socket::SSL options if you desire to do so. It is completely\noverridden by \"findssldefaults\" above.\n\nbindaddr => str\nAssign a local address to bind\n\nuseselectcache => BOOL\nEnable \"select()\" caching internally\n\nselectcachettl => int\nThe number of seconds to allow a select cache result live before running \"$imap->select()\"\nagain.\n\ndebug => BOOL | \\*HANDLE | warn | file:name\nEnable debugging output. If \"\\*HANDLE\" is a valid file handle, debugging will be written to\nit. If it is the string \"warn\" then the debugging will be written using the warn command. If\nit is a string of the form \"file:name\" then the named file will be opened for append and the\ndebugs written to it. Otherwise debugging will be written to \"STDOUT\"\n\nreadlinecallback => CODE\nYou may choose to pass a callback function for the purpose of pre-processing lines before\nthey are handed to the rest of the Net::IMAP::Simple internals. This can be handy for\nanimating a spinner or modifying the IMAP behavior.\n", "subsections": [] }, "PREAUTH": { "content": "Rather than passing a port number and issuing a login, in some situations it may be convenient\nto authenticate with (for example) ssh and simply invoke (for example) dovecot by hand.\n\nIf the server name starts with \"cmd:\", then Net::IMAP::Simple will issue the command rather than\nbuilding sockets. This is a typical setup:\n\nmy $cmd = \"ssh -C mailhost dovecot --exec-mail imap\";\nmy $imap = Net::IMAP::Simple->new(\"cmd:$cmd\");\n# $imap->login(); ... don't need this\n\nmy $numberofmessages = $imap->select(\"INBOX\");\n", "subsections": [] }, "METHODS": { "content": "starttls\n$imap->starttls;\n\nIf you start an IMAP session and wish to upgrade to SSL later, you can use this function to\nstart TLS. This function will try to \"require\" IO::Socket::SSL and Net::SSLeay at runtime.\n\nlogin\nmy $inboxmsgs = $imap->login($user, $passwd);\n\nThis method takes two required parameters, a username and password. This pair is\nauthenticated against the server. If authentication is successful TRUE (1) will be returned\n\nNothing is returned on failure and the \"errstr()\" error handler is set with the error\nmessage.\n\nstatus\nmy $nummessages = $imap->status($folder);\nmy ($unseen, $recent, $nummessages) = $imap->status($folder);\n\nIssue a \"STATUS\" command. The \"STATUS\" command counts messages without altering the state of\nthe named (optionally) mailbox. It returns either the number of messages, or the number of\nunseen messages, recent, and the total number of messages.\n\n$folder is an optional argument. \"status()\" will use the current mailbox or \"INBOX\" if the\n$folder argument is not provided.\n\nThis method does not use caching.\n\nThis method can also query custom status values. The first argument to the function (if any)\nis assumed to be the folder name, so the folder argument is required when trying to query\ncustom status values.\n\nmy ($f1, $f2) = $imap->status($folder, qw(f1 f2));\nmy $f2 = $imap->status($folder, qw(f1 f2));\n\nuidnext\nmy $uidnext = $imap->uidnext($folder);\n\nReturn the \"UIDNEXT\" value for a mailbox. The $folder argument is optional. This is really\njust an alias for\n\nmy $uidnext = $imap->status($folder, qw(uidnext));\n\nwith the mild difference that it can compute the folder argument for you\n\nuidvalidity\nmy $uidvalidity = $imap->uidnext($folder);\n\nReturn the \"UIDVALIDITY\" value for a mailbox. The $folder argument is optional. This is also\nan alias for the status call like \"uidnext()\" above.\n\nuid This function is actually an alias for \"$imap->uidsearch($msgrange)\".\n\nmy($uid)= $imap->uid($msgno);\nmy @uid = $imap->uid($msgrange); # eg 4:14 or 15,4,14\n\nReturn the \"UID\" value(s) for a message. These unique IDs \"*must*\" stay the same during the\nsession and \"*should*\" stay the same between sessions. Whether they stay the same depends on\nthe \"UIDVALIDITY\" value; see: above and RFC3501.\n\nWarning, although you might thing @uid should contain the \"UID\"s for 15, then 4, then 14 in\nthe example above; most IMAP servers seem to return the UIDs in increasing order. Normally\nthe sequence numbers are in increasing order also, so it all maches up.\n\nmy ($uid4, $uid14, $uid15) = $imap->uid(\"15,4,14\"); # warning\n\nOne final note, this gives the size of the search match, not the uid like you might expect:\n\nmy $uidsearchresultlistsize = $imap->uid('3'); # probably always 1\n\nseq\nmy $seq = $imap->seq($uids);\nmy @seq = $imap->seq($uids); # eg 58888:58900\n\nRather like \"uid()\" above, but maps uids to sequence numbers.\n\nselect\nmy $nummessages = $imap->select($folder);\n\nSelects a folder named in the single required parameter. The number of messages in that\nfolder is returned on success. On failure, nothing is returned and the \"errstr()\" error\nhandler is set with the error message.\n\nexamine\nThis is very nearly a synonym for \"select()\". The only real difference is that the EXAMINE\ncommand is sent to the server instead of SELECT. Net::IMAP::Simple is otherwise unaware of\nthe read-only-ness of the mailbox.\n\nclose\n$imap->close;\n\nUn-selects the current mailbox, leaving no mailbox selected.\n\nmessages\nprint \"Messages in Junk Mail -- \" . $imap->messages(\"INBOX.Junk Mail\") . \"\\n\";\n\nThis method is an alias for \"$imap->select\"\n\nflags\nprint \"Available server flags: \" . join(\", \", $imap->flags) . \"\\n\";\n\nThis method accepts an optional folder name and returns the current available server flags\nas a list, for the selected folder. If no folder name is provided the last folder\n\"$imap->select\"'ed will be used.\n\nThis method uses caching.\n\nseparator\nReturns the folder separator (technically \"hierarchy separator\", rfc3501ยง6.3.8) for the\nserver.\n\nrecent\nprint \"Recent messages value: \" . $imap->recent . \"\\n\";\n\nThis method accepts an optional folder name and returns the 'RECENT' value provided durning\na SELECT result set. If no folder name is provided the last folder \"$imap->select\"'ed will\nbe used.\n\nThis method uses caching.\n\nSee also: search\n\nunseen\nprint \"Unseen messages value: \" . $imap->unseen . \"\\n\";\n\nThis method accepts an optional folder name and returns the 'UNSEEN' value provided during a\nSELECT command result. If no folder name is provided the last folder \"$imap->select\"'ed will\nbe used. If a folder name *is* provided, this will issue a SELECT first.\n\nThis method uses caching.\n\nIf the server does not provide UNSEEN during SELECT -- surprisingly common -- this method\nwill fall back and use STATUS to determine the unseen count.\n\nNOTE: This is not the opposite of seen below. The UNSEEN value varies from server to server,\nbut according to the IMAP specification, it should be the *number of the first unseen\nmessage*, in the case the flag is provided. (If the flag is not provided, users would have\nto use the SEARCH command to find it.)\n\nSee also: search\n\ncurrentbox\nprint \"Current Mail Box folder: \" . $imap->currentbox . \"\\n\";\n\nThis method returns the current working mail box folder name.\n\ntop\nmy $header = $imap->top( $messagenumber ); print for @{$header};\n\nThis method accepts a message number as its required parameter. That message will be\nretrieved from the currently selected folder. On success this method returns a list\nreference containing the lines of the header. Nothing is returned on failure and the\n\"errstr()\" error handler is set with the error message.\n\nseen\ndefined( my $seen = $imap->seen( $messagenumber ) )\nor warn \"problem testing for \\Seen: \"\n. $imap->errstr;\n\nprint \"msg #$messagenumber has been \\Seen!\" if $seen;\n\nA message number is the only required parameter for this method. The message's \"\\Seen\" flag\nwill be examined and if the message has been seen a true value is returned. A defined false\nvalue is returned if the message does not have the \"\\Seen\" flag set. The undefined value is\nreturned when an error has occurred while checking the flag status.\n\nNOTE: This is not the opposite of unseen above. This issues a \"FETCH\" command and checks to\nsee if the given message has been \"\\Seen\" before.\n\ndeleted\ndefined( my $deleted = $imap->deleted( $messagenumber ) )\nor warn \"problem testing for \\Deleted: \"\n. $imap->errstr;\n\nprint \"msg #$messagenumber has been \\Deleted!\" if $deleted;\n\nA message number is the only required parameter for this method. The message's \"\\Deleted\"\nflag will be examined and if the message has been deleted a true value is returned. A\ndefined false value is returned if the message does not have the \"\\Deleted\" flag set. The\nundefined value is returned when an error has occurred while checking the flag status.\n\nlist\nmy $messagesize = $imap->list($messagenumber);\nmy $mailboxsizes = $imap->list;\n\nThis method returns size information for a message, as indicated in the single optional\nparameter, or all messages in a mailbox. When querying a single message a scalar value is\nreturned. When listing the entire mailbox a hash is returned. On failure, nothing is\nreturned and the \"errstr()\" error handler is set with the error message.\n\nfetch\nmy $headers = $imap->fetch(\"1:5\")\n\nFetch the headers for messages 1-5 in the current folder.\n\nfor my $midx ( keys %$headers ) {\nfor my $hdr in ($headers->{$midx}) {\nsay \"$hdr\"\n\n# In many situations the headers will be parsed and may not be simple\n# strings (e.g., with the SimpleX RecDescent parse). The simplest\n# way to get a feel for the output is to use a dumper on it.\n}\n}\n\nget\nmy $message = $imap->get( $messagenumber ) or die $imap->errstr;\nmy @messagelines = $map->get( $messagenumber ) or die $imap->errstr;\n\nmy $part = $imap->get( $messagenumber, '1.1' ) or die $imap->errstr;\nmy @partlines = $imap->get( $messagenumber, '1.1' ) or die $imap->errstr;\n\nThis method fetches a message and returns its lines as an array or, the actual message. On\nfailure, either an empty list is returned and the \"errstr()\" error handler is set with the\nerror message.\n\nOptionally, a part can be specified in order to fetch a specific portion of a message. This\nis the raw, encoded body of the message part. The part number is a set of zero or more part\nspecifiers delimited by periods. Every message has at least one part. Specifying a part of\n'1' returns the raw, encoded body. This is only useful if you know the header information\nsuch as encoding.\n\nHistorically, \"get()\" returned the array of lines as a reference to the array instead of\nreturning the message or the array itself. Please note that it still does this, although it\nmay be deprecated in the future.\n\nThe scalar result returned is actually a blessed arrayref with the stringify member\noverloaded. If you're intending to use the resulting message as a string more than once, it\n*may* make sense to force the stringification first.\n\nmy $message = $imap->get(1);\n$message = \"$message\"; # force stringification\n\nIt is not normally necessary to do this.\n\nput\n$imap->put( $mailboxname, $message, @flags ) or warn $imap->errstr;\n\nSave a message to the server under the folder named $mailboxname. You may optionally\nspecify flags for the mail (e.g. \"\\Seen\", \"\\Answered\"), but they must start with a slash.\n\nIf $message is an arrayref, the lines will be printed correctly.\n\nputwithdate\n$imap->putwithdate( $mailboxname, $message, $date, @flags ) or warn $imap->errstr;\n\nSave a message to the server under the folder named $mailboxname just like the put method\nabove, but supplying a date will set the IMAP server internal date for the message if\nsupported per RFC 3501 Section 6.3.11.\n\nNote when using this with Gmail it expects the date format to be: DD-Mon-YYYY hh:mm:ss tz\nfor example 31-Dec-2016 12:59:59 -0500\n\nmsgflags\nmy @flags = $imap->msgflags( $messagenumber );\nmy $flags = $imap->msgflags( $messagenumber );\n\n# aught to come out roughly the same\nprint \"Flags on message #$messagenumber: @flags\\n\";\nprint \"Flags on message #$messagenumber: $flags\\n\";\n\nDetecting errors with this member functions is usually desirable. In the scalar context,\ndetecting an error is synonymous with testing for defined.\n\nif( defined( my $flags = $imap->msgflags($num) ) ) {\n# it has $flags!\n\n} else {\nwarn \"problem listing flags for message #$num: \"\n. $imap->errstr;\n}\n\nIn list context, you must call waserr() to test for success.\n\nmy @flags = $imap->msgflags($num);\nwarn \"problem listing flags for msg #$num: \"\n. $imap->errstr if $imap->waserr;\n\ngetfh\nmy $file = $imap->getfh( $messagenumber ); print <$file>;\n\nOn success this method returns a file handle pointing to the message identified by the\nrequired parameter. On failure, nothing is returned and the \"errstr()\" error handler is set\nwith the error message.\n\nquit\n$imap->quit;\n\nOR\n\n$imap->quit(BOOL);\n\nThis method logs out of the IMAP server, expunges the selected mailbox, and closes the\nconnection. No error message will ever be returned from this method.\n\nOptionally if BOOL is TRUE (1) then a hard quit is performed which closes the socket\nconnection. This hard quit will still issue both EXPUNGE and LOGOUT commands however the\nresponse is ignored and the socket is closed after issuing the commands.\n\nlogout\n$imap->logout;\n\nThis method is just like the quit method except that it does not have a hard quit option and\nit does not expunge the mailbox before it hangs up and closes the socket.\n\nlast\nmy $messagenumber = $imap->last;\n\nThis method returns the message number of the last message in the selected mailbox, since\nthe last time the mailbox was selected. On failure, nothing is returned and the \"errstr()\"\nerror handler is set with the error message.\n\ndelete\nprint \"Gone!\" if $imap->delete( $messagenumber );\n\nThis method sets the \"\\Deleted\" flag on the given message (or messages). On success it\nreturns true, false on failure and the \"errstr()\" error handler is set with the error\nmessage. If the flag was already there, no error is produced. I takes either a message\nnumber or \"sequence set\" as the only argument. Note that messages aren't actually deleted\nuntil they are expunged (see expungemailbox).\n\nundelete\nprint \"Resurrected!\" if $imap->undelete( $messagenumber );\n\nThis method removes the \"\\Deleted\" flag on the given message. On success it returns true,\nfalse on failure and the \"errstr()\" error handler is set with the error message. If the flag\nwasn't there, no error is produced.\n\nsee\nprint \"You've seen message #$msgno\" if $imap->see( $messageno );\n\nThis method sets the \"\\Seen\" flag on the given message. On success it returns true, false on\nfailure and the \"errstr()\" error handler is set with the error message. If the flag was\nalready there, no error is produced.\n\nunsee\nprint \"You've not seen message #$msgno\" if $imap->unsee( $messageno );\n\nThis method removes the \"\\Seen\" flag on the given message. On success it returns true, false\non failure and the \"errstr()\" error handler is set with the error message. If the flag\nwasn't there, no error is produced.\n\naddflags\ndelete and see above really just call this function for those flags.\n\n$imap->addflags( $msgno, qw(\\Seen \\Deleted) )\nor die $imap->errstr;\n\nsubflags\nunsee above really just calls this function for that flag.\n\n$imap->subflags( $msgno, '\\Seen' ) or die $imap->errstr;\n\nmailboxes\nmy @boxes = $imap->mailboxes;\nmy @folders = $imap->mailboxes(\"Mail/%\");\nmy @lists = $imap->mailboxes(\"lists/perl/*\", \"/Mail/\");\n\nThis method returns a list of mailboxes. When called with no arguments it recurses from the\nIMAP root to get all mailboxes. The first optional argument is a mailbox path and the second\nis the path reference. RFC 3501 section 6.3.8 has more information.\n\nOn failure nothing is returned and the \"errstr()\" error handler is set with the error\nmessage.\n\nmailboxessubscribed\nmy @boxes = $imap->mailboxessubscribed;\nmy @folders = $imap->mailboxessubscribed(\"Mail/%\");\nmy @lists = $imap->mailboxessubscribed(\"lists/perl/*\", \"/Mail/\");\n\nThis method returns a list of mailboxes subscribed to. When called with no arguments it\nrecurses from the IMAP root to get all mailboxes. The first optional argument is a mailbox\npath and the second is the path reference. RFC 3501 has more information.\n\nOn failure nothing is returned and the \"errstr()\" error handler is set with the error\nmessage.\n\ncreatemailbox\nprint \"Created\" if $imap->createmailbox( \"/Mail/lists/perl/advocacy\" );\n\nThis method creates the mailbox named in the required argument. Returns true on success,\nfalse on failure and the \"errstr()\" error handler is set with the error message.\n\nexpungemailbox\nmy @expunged = $imap->expungemailbox( \"/Mail/lists/perl/advocacy\" );\ndie $imap->errstr if $imap->waserr;\n\nmy $expunged = $imap->expungemailbox( \"/Mail/lists/perl/advocacy\" )\nor die $imap->errstr;\n\nThis method removes all mail marked as deleted in the mailbox named in the required\nargument. Returns either the number of messages that were expunged, or the indexes of those\nmessages -- which has a questionable usefulness since it tends to return numbers that don't\nrelate to the message numbers marked with the \"\\Deleted\" flags.\n\nIf 0 messages were expunged without error, the function will return 0E0 so it will still\ntest true, but also evaluate to 0.\n\nIn list context, you must call waserr() to test for success.\n\ndeletemailbox\nprint \"Deleted\" if $imap->deletemailbox( \"/Mail/lists/perl/advocacy\" );\n\nThis method deletes the mailbox named in the required argument. Returns true on success,\nfalse on failure and the \"errstr()\" error handler is set with the error message.\n\nrenamemailbox\nprint \"Renamed\" if $imap->renamemailbox( $old => $new );\n\nThis method renames the mailbox in the first required argument to the mailbox named in the\nsecond required argument. Returns true on success, false on failure and the \"errstr()\" error\nhandler is set with the error message.\n\nfoldersubscribe\nprint \"Subscribed\" if $imap->foldersubscribe( \"/Mail/lists/perl/advocacy\" );\n\nThis method subscribes to the folder. Returns true on success, false on failure and the\n\"errstr()\" error handler is set with the error message.\n\nfolderunsubscribe\nprint \"Unsubscribed\" if $imap->folderunsubscribe( \"/Mail/lists/perl/advocacy\" );\n\nThis method un-subscribes to the folder. Returns true on success, false on failure and the\n\"errstr()\" error handler is set with the error message.\n\ncopy\nprint \"copied\" if $imap->copy( $messagenumber, $mailbox );\n\nThis method copies the message number (or \"sequence set\") in the currently selected mailbox\nto the folder specified in the second argument. Both arguments are required. On success this\nmethod returns true. Returns false on failure and the \"errstr()\" error handler is set with\nthe error message.\n\nuidcopy\nprint \"copied\" if $imap->uidcopy( $messageuid, $mailbox );\n\nThis method is identical to \"copy()\" above, except that it uses UID numbers instead of\nsequence numbers.\n\nnoop\n$imap->noop;\n\nPerforms a null operation. This may be needed to get updates on a mailbox, or ensure that\nthe server does not close the connection as idle. RFC 3501 states that servers' idle\ntimeouts must not be less than 30 minutes.\n\nerrstr\nprint \"Login ERROR: \" . $imap->errstr . \"\\n\" if !$imap->login($user, $pass);\n\nReturn the last error string captured for the last operation which failed.\n\nwaserr\nmy @flags = $imap->msgflags(14);\ndie $imap->errstr if $imap->waserr;\n\nBecause \"msgflags()\" can optionally return a list, it's not really possible to detect\nfailure in list context. Therefore, you must call \"waserr()\" if you wish to detect errors.\n\nFew of the Net::IMAP::Simple methods use \"waserr()\". The ones that do will mention it.\n\nlist2range\nSometimes you have a long list of sequence numbers which are consecutive and really want to\nbe an IMAP-style range.\n\nmy @list = (5..9, 13..38, 55,56,57);\nmy $short = $imap->list2range(@list);\n\n# $short how says: 5:9,13:38,55:57\n\nrange2list\nPretty much the opposite of \"list2range\".\n\nmy @list = $imap->range2list(\"1,3,5:9\");\n# @list is (1,3,5,6,7,8,9);\n", "subsections": [] }, "SEARCHING": { "content": "search\nThis function returns an array of message numbers (in list context) or the number of matched\nmessages (in scalar context). It takes a single argument: the search.\n\nIMAP searching can be a little confusing and this function makes no attempt to parse your\nsearches. If you wish to do searches by hand, please see RFC 3501.\n\nIMAP sorting (see RFC 5256) is supported via an optional second argument. The RFC requires\nthe charset be specified, which can be provided via the optional third argument (defaults to\nUTF-8).\n\nHere are a few examples:\n\nmy @ids = $imap->search(\"UNSEEN\");\nmy @ids = $imap->search('SUBJECT \"blarg is \\\"blarg\\\"\"');\nmy @ids = $imap->search('FROM \"joe@aol.com\"');\nmy @ids = $imap->search(\"DELETED\");\n\n# example from RFC 3501, search terms are ANDed together\nmy @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM \"Smith\"');\n# example from RFC 3501, search terms are ORed together\nmy @ids = $imap->search('OR BODY \"blard\" SUBJECT \"blarg\"');\n\n# flagged and ( since x or !from y ):\nmy @ids = $imap->search('FLAGGED OR SINCE x NOT FROM \"y\"');\n# no typo above, see the RFC\n\n# example from RFC 5256, sorted by subject and reverse date\nmy @ids = $imap->search('BODY \"zaphod\"', 'SUBJECT REVERSE DATE');\n\nSince this module is meant to be simple, Net::IMAP::Simple has a few search helpers. If you\nneed fancy booleans and things, you'll have to learn search. If you need a quick search for\nunseen messages, see below.\n\nThese all return an array of messages or count of messages exactly as the search function\ndoes. Some of them take arguments, some do not. They do try to grok your arguments slightly,\nthe mechanics of this (if any) will be mentioned below.\n\nsearchseen\nReturns numbers of messages that have the \\Seen flag.\n\nsearchrecent\nReturns numbers of messages that have the \\Recent flag.\n\nsearchanswered\nReturns numbers of messages that have the \\Answered flag.\n\nsearchdeleted\nReturns numbers of messages that have the \\Deleted flag.\n\nsearchflagged\nReturns numbers of messages that have the \\Flagged flag.\n\nsearchdraft\nReturns numbers of messages that have the \\Draft flag.\n\nsearchunseen\nReturns numbers of messages that do not have the \\Seen flag.\n\nsearchold\nReturns numbers of messages that do not have the \\Recent flag.\n\nsearchunanswered\nReturns numbers of messages that do not have the \\Answered flag.\n\nsearchundeleted\nReturns numbers of messages that do not have the \\Deleted flag.\n\nsearchunflagged\nReturns numbers of messages that do not have the \\Flagged flag.\n\nsearchsmaller\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat are smaller than \"\" octets. This function will try to force your argument to be\na number before passing it to the IMAP server.\n\nsearchlarger\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat are larger than \"\" octets. This function will try to force your argument to be a\nnumber before passing it to the IMAP server.\n\nsearchfrom\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the from header. This function will attempt to force your string into\nthe RFC3501 quoted-string format.\n\nsearchto\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the to header. This function will attempt to force your string into\nthe RFC3501 quoted-string format.\n\nsearchcc\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the cc header. This function will attempt to force your string into\nthe RFC3501 quoted-string format.\n\nsearchbcc\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the bcc header. This function will attempt to force your string into\nthe RFC3501 quoted-string format.\n\nsearchsubject\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the subject header. This function will attempt to force your string\ninto the RFC3501 quoted-string format.\n\nsearchbody\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have \"\" in the message body. This function will attempt to force your string\ninto the RFC3501 quoted-string format.\n\nsearchbefore\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat were received before \"\". If you have Date::Manip installed (optional), this\nfunction will attempt to force the date into the format \"%d-%b-%Y\" (date-monthName-year)\nas RFC3501 requires. If you do not have that module, no attempt will be made to coerce\nyour date into the correct format.\n\nsearchsince\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat were received after \"\". If you have Date::Manip installed (optional), this\nfunction will attempt to force the date into the format \"%d-%m-%Y\" (date-month-year) as\nRFC3501 requires. If you do not have that module, no attempt will be made to coerce your\ndate into the correct format.\n\nsearchsentbefore\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have a header date before \"\". If you have Date::Manip installed (optional), this\nfunction will attempt to force the date into the format \"%d-%m-%Y\" (date-month-year) as\nRFC3501 requires. If you do not have that module, no attempt will be made to coerce your\ndate into the correct format.\n\nsearchsentsince\nThis function takes a single argument we'll call \"\" and returns numbers of messages\nthat have a header date after \"\". If you have Date::Manip installed (optional), this\nfunction will attempt to force the date into the format \"%d-%m-%Y\" (date-month-year) as\nRFC3501 requires. If you do not have that module, no attempt will be made to coerce your\ndate into the correct format.\n\nuidsearch\nThis function works exactly like \"search()\" but it returns UIDs instead of sequence numbers.\nThe convenient shortcuts above are not provided for it.\n", "subsections": [] }, "OTHER NOTES": { "content": "sequence set\nMessage numbers are never checked before being passed to the IMAP server (this is a \"simple\"\nmodule after all), so in most places where a message number is required, you can instead use\nso-called *sequence sets*. Examples:\n\n$imap->copy( \"3,4,9:22\", \"ANOTHERBOX\" ) or die $imap->errstr;\n$imap->delete( \"3,4,9:22\" ) or die $imap->errstr;\n", "subsections": [] }, "AUTHOR": { "content": "Creator\nJoao Fonseca \"\"\n\nMaintainer 2004\nCasey West \"\"\n\nMaintainer 2005\nColin Faber \"\"\n\nMaintainer 2009\nPaul Miller \"\"\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c) 2009-2010 Paul Miller Copyright (c) 2005 Colin Faber Copyright (c) 2004 Casey West\nCopyright (c) 1999 Joao Fonseca\n\nAll rights reserved. This program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n", "subsections": [] }, "LICENSE": { "content": "This module is free software. You can redistribute it and/or modify it under the terms of the\nArtistic License 2.0.\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.\n\n[This software may have had previous licenses, of which the current maintainer is completely\nunaware. If this is so, it is possible the above license is incorrect or invalid.]\n", "subsections": [] }, "BUGS": { "content": "There are probably bugs. But don't worry, the current maintainer takes them very seriously and\nwill usually triage (at least) within a single day.\n\n\n", "subsections": [] }, "SEE ALSO": { "content": "perl, Net::IMAP::Server, IO::Socket::SSL, IO::Socket::INET6\n", "subsections": [] } } } }