.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::IMAP::Client 3pm" .TH Net::IMAP::Client 3pm "2014-07-18" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::IMAP::Client \- Not so simple IMAP client library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::IMAP::Client; \& \& my $imap = Net::IMAP::Client\->new( \& \& server => \*(Aqmail.you.com\*(Aq, \& user => \*(AqUSERID\*(Aq, \& pass => \*(AqPASSWORD\*(Aq, \& ssl => 1, # (use SSL? default no) \& ssl_verify_peer => 1, # (use ca to verify server, default yes) \& ssl_ca_file => \*(Aq/etc/ssl/certs/certa.pm\*(Aq, # (CA file used for verify server) or \& # ssl_ca_path => \*(Aq/etc/ssl/certs/\*(Aq, # (CA path used for SSL) \& port => 993 # (but defaults are sane) \& \& ) or die "Could not connect to IMAP server"; \& \& # everything\*(Aqs useless if you can\*(Aqt login \& $imap\->login or \& die(\*(AqLogin failed: \*(Aq . $imap\->last_error); \& \& # let\*(Aqs see what this server knows (result cached on first call) \& my $capab = $imap\->capability; \& # or \& my $knows_sort = $imap\->capability( qr/^sort/i ); \& \& # get list of folders \& my @folders = $imap\->folders; \& \& # get total # of messages, # of unseen messages etc. (fast!) \& my $status = $imap\->status(@folders); # hash ref! \& \& # select folder \& $imap\->select(\*(AqINBOX\*(Aq); \& \& # get folder hierarchy separator (cached at first call) \& my $sep = $imap\->separator; \& \& # fetch all message ids (as array reference) \& my $messages = $imap\->search(\*(AqALL\*(Aq); \& \& # fetch all ID\-s sorted by subject \& my $messages = $imap\->search(\*(AqALL\*(Aq, \*(AqSUBJECT\*(Aq); \& # or \& my $messages = $imap\->search(\*(AqALL\*(Aq, [ \*(AqSUBJECT\*(Aq ]); \& \& # fetch ID\-s that match criteria, sorted by subject and reverse date \& my $messages = $imap\->search({ \& FROM => \*(Aqfoo\*(Aq, \& SUBJECT => \*(Aqbar\*(Aq, \& }, [ \*(AqSUBJECT\*(Aq, \*(Aq^DATE\*(Aq ]); \& \& # fetch message summaries (actually, a lot more) \& my $summaries = $imap\->get_summaries([ @msg_ids ]); \& \& foreach (@$summaries) { \& print $_\->uid, $_\->subject, $_\->date, $_\->rfc822_size; \& print join(\*(Aq, \*(Aq, @{$_\->from}); # etc. \& } \& \& # fetch full message \& my $data = $imap\->get_rfc822_body($msg_id); \& print $$data; # it\*(Aqs reference to a scalar \& \& # fetch full messages \& my @msgs = $imap\->get_rfc822_body([ @msg_ids ]); \& print $$_ for (@msgs); \& \& # fetch single attachment (message part) \& my $data = $imap\->get_part_body($msg_id, \*(Aq1.2\*(Aq); \& \& # fetch multiple attachments at once \& my $hash = $imap\->get_parts_bodies($msg_id, [ \*(Aq1.2\*(Aq, \*(Aq1.3\*(Aq, \*(Aq2.2\*(Aq ]); \& my $part1_2 = $hash\->{\*(Aq1.2\*(Aq}; \& my $part1_3 = $hash\->{\*(Aq1.3\*(Aq}; \& my $part2_2 = $hash\->{\*(Aq2.2\*(Aq}; \& print $$part1_2; # need to dereference it \& \& # copy messages between folders \& $imap\->select(\*(AqINBOX\*(Aq); \& $imap\->copy(\e@msg_ids, \*(AqArchive\*(Aq); \& \& # delete messages ("Move to Trash") \& $imap\->copy(\e@msg_ids, \*(AqTrash\*(Aq); \& $imap\->add_flags(\e@msg_ids, \*(Aq\e\eDeleted\*(Aq); \& $imap\->expunge; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::IMAP::Client provides methods to access an \s-1IMAP\s0 server. It aims to provide a simple and clean \s-1API,\s0 while employing a rigorous parser for \s-1IMAP\s0 responses in order to create Perl data structures from them. The code is simple, clean and extensible. .PP It started as an effort to improve Net::IMAP::Simple but then I realized that I needed to change a lot of code and \s-1API\s0 so I started it as a fresh module. Still, the design is influenced by Net::IMAP::Simple and I even stole a few lines of code from it ;\-) (very few, honestly). .PP This software was developed for creating a web-based email (\s-1IMAP\s0) client: www.xuheki.com. Xhueki uses Net::IMAP::Client. .SH "API REFERENCE" .IX Header "API REFERENCE" Unless otherwise specified, if a method fails it returns \fIundef\fR and you can inspect the error by calling \f(CW$imap\fR\->last_error. For a successful call most methods will return a meaningful value but definitely not \fIundef\fR. .SS "new(%args) # constructor" .IX Subsection "new(%args) # constructor" .Vb 1 \& my $imap = Net::IMAP::Client\->new(%args); .Ve .PP Pass to the constructor a hash of arguments that can contain: .IP "\- \fBserver\fR (\s-1STRING\s0)" 4 .IX Item "- server (STRING)" Host name or \s-1IP\s0 of the \s-1IMAP\s0 server. .IP "\- \fBuser\fR (\s-1STRING\s0)" 4 .IX Item "- user (STRING)" User \s-1ID \s0(\fIonly \*(L"clear\*(R" login is supported for now!\fR) .IP "\- \fBpass\fR (\s-1STRING\s0)" 4 .IX Item "- pass (STRING)" Password .IP "\- \fBssl\fR (\s-1BOOL,\s0 optional, default \s-1FALSE\s0)" 4 .IX Item "- ssl (BOOL, optional, default FALSE)" Pass a true value if you want to use IO::Socket::SSL .IP "\- \fBssl_verify_peer\fR (\s-1BOOL,\s0 optional, default \s-1TRUE\s0)" 4 .IX Item "- ssl_verify_peer (BOOL, optional, default TRUE)" Pass a false value if you do not want to use \s-1SSL CA\s0 to verify server .Sp only need when you set ssl to true .IP "\- \fBssl_ca_file\fR (\s-1STRING,\s0 optional)" 4 .IX Item "- ssl_ca_file (STRING, optional)" Pass a file path which used as \s-1CA\s0 file to verify server .Sp at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify server .IP "\-\fBssl_ca_path\fR (\s-1STRING,\s0 optional)" 4 .IX Item "-ssl_ca_path (STRING, optional)" Pass a dir which will be used as \s-1CA\s0 file search dir, found \s-1CA\s0 file will be used to verify server .Sp On linux, by default is '/etc/ssl/certs/' .Sp at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify server .IP "\- \fBssl_options\fR (\s-1HASHREF,\s0 optional)" 4 .IX Item "- ssl_options (HASHREF, optional)" Optional arguments to be passed to the IO::Socket::SSL object. .IP "\- \fBuid_mode\fR (\s-1BOOL,\s0 optional, default \s-1TRUE\s0)" 4 .IX Item "- uid_mode (BOOL, optional, default TRUE)" Whether to use \s-1UID\s0 command (see \s-1RFC3501\s0). Recommended. .IP "\- \fBsocket\fR (IO::Handle, optional)" 4 .IX Item "- socket (IO::Handle, optional)" If you already have a socket connected to the \s-1IMAP\s0 server, you can pass it here. .PP The \fBssl_ca_file\fR and \fBssl_ca_path\fR only need when you set \&\fBssl_verify_peer\fR to \s-1TRUE.\s0 .PP If you havn't apply an \fBssl_ca_file\fR and \fBssl_ca_path\fR, on linux, the \fBssl_ca_path\fR will use the value '/etc/ssl/certs/', on other platform \fBssl_verify_peer\fR will be disabled. .PP The constructor doesn't login to the \s-1IMAP\s0 server \*(-- you need to call \&\f(CW$imap\fR\->login for that. .SS "last_error" .IX Subsection "last_error" Returns the last error from the \s-1IMAP\s0 server. .ie n .SS "login($user, $pass)" .el .SS "login($user, \f(CW$pass\fP)" .IX Subsection "login($user, $pass)" Login to the \s-1IMAP\s0 server. You can pass \f(CW$user\fR and \f(CW$pass\fR here if you wish; if not passed, the values used in constructor will be used. .PP Returns \fIundef\fR if login failed. .SS "logout / quit" .IX Subsection "logout / quit" Send \s-1EXPUNGE\s0 and \s-1LOGOUT\s0 then close connection. \f(CW\*(C`quit\*(C'\fR is an alias for \f(CW\*(C`logout\*(C'\fR. .SS "noop" .IX Subsection "noop" \&\*(L"Do nothing\*(R" method that calls the \s-1IMAP \*(L"NOOP\*(R"\s0 command. It returns a true value upon success, \fIundef\fR otherwise. .PP This method fetches any notifications that the server might have for us and you can get them by calling \f(CW$imap\fR\->notifications. See the \&\*(L"\fInotifications()\fR\*(R" method. .SS "\fIcapability()\fP / capability(qr/^SOMETHING/)" .IX Subsection "capability() / capability(qr/^SOMETHING/)" With no arguments, returns an array of all capabilities advertised by the server. If you're interested in a certain capability you can pass a RegExp. E.g. to check if this server knows '\s-1SORT\s0', you can do this: .PP .Vb 3 \& if ($imap\->capability(/^sort$/i)) { \& # speaks it \& } .Ve .PP This data is cached, the server will be only hit once. .SS "select($folder)" .IX Subsection "select($folder)" Selects the current \s-1IMAP\s0 folder. On success this method also records some information about the selected folder in a hash stored in \&\f(CW$self\fR\->{\s-1FOLDERS\s0}{$folder}. You might want to use Data::Dumper to find out exactly what, but at the time of this writing this is: .IP "\- \fBmessages\fR" 4 .IX Item "- messages" Total number of messages in this folder .IP "\- \fBflags\fR" 4 .IX Item "- flags" Flags available for this folder (as array ref) .IP "\- \fBrecent\fR" 4 .IX Item "- recent" Total number of recent messages in this folder .IP "\- \fBsflags\fR" 4 .IX Item "- sflags" Various other flags here, such as \s-1PERMANENTFLAGS\s0 of \s-1UIDVALIDITY. \s0 You might want to take a look at \s-1RFC3501\s0 at this point. :\-p .PP This method is basically stolen from Net::IMAP::Simple. .SS "examine($folder)" .IX Subsection "examine($folder)" Selects the current \s-1IMAP\s0 folder in read-only (\s-1EXAMINE\s0) mode. Otherwise identical to select. .SS "status($folder), status(\e@folders)" .IX Subsection "status($folder), status(@folders)" Returns the status of the given folder(s). .PP If passed an array ref, the return value is a hash ref mapping folder name to folder status (which are hash references in turn). If passed a single folder name, it returns the status of that folder only. .PP .Vb 3 \& my $inbox = $imap\->status(\*(AqINBOX\*(Aq); \& print $inbox\->{UNSEEN}, $inbox\->{MESSAGES}; \& print Data::Dumper::Dumper($inbox); \& \& my $all = $imap\->status($imap\->folders); \& while (my ($name, $status) = each %$all) { \& print "$name : $status\->{MESSAGES}/$status\->{UNSEEN}\en"; \& } .Ve .PP This method is designed to be very fast when passed multiple folders. It's \fIa lot\fR faster to call: .PP .Vb 1 \& $imap\->status(\e@folders); .Ve .PP than: .PP .Vb 1 \& $imap\->status($_) foreach (@folders); .Ve .PP because it sends all the \s-1STATUS\s0 requests to the \s-1IMAP\s0 server before it starts receiving the answers. In my tests with my remote \s-1IMAP\s0 server, for 40 folders this method takes 0.6 seconds, compared to 6+ seconds when called individually for each folder alone. .SS "separator" .IX Subsection "separator" Returns the folder hierarchy separator. This is provided as a result of the following \s-1IMAP\s0 command: .PP .Vb 1 \& FETCH "" "*" .Ve .PP I don't know of any way to change this value on a server so I have to assume it's a constant. Therefore, this method caches the result and it won't hit the server a second time on subsequent calls. .SS "folders" .IX Subsection "folders" Returns a list of all folders available on the server. In scalar context it returns a reference to an array, i.e.: .PP .Vb 3 \& my @a = $imap\->folders; \& my $b = $imap\->folders; \& # now @a == @$b; .Ve .SS "folders_more" .IX Subsection "folders_more" Returns an hash reference containing more information about folders. It maps folder name to an hash ref containing the following: .PP .Vb 3 \& \- flags \-\- folder flags (array ref; i.e. [ \*(Aq\e\eHasChildren\*(Aq ]) \& \- sep \-\- one character containing folder hierarchy separator \& \- name \-\- folder name (same as the key \-\- thus redundant) .Ve .SS "namespace" .IX Subsection "namespace" Returns an hash reference containing the namespaces for this server (see \s-1RFC 2342\s0). Since the \s-1RFC\s0 defines 3 possible types of namespaces, the hash contains the following keys: .PP .Vb 3 \& \- \`personal\*(Aq \-\- the personal namespace \& \- \`other\*(Aq \-\- "other users" namespace \& \- \`shared\*(Aq \-\- shared namespace .Ve .PP Each one can be \fIundef\fR if the server returned \*(L"\s-1NIL\*(R",\s0 or an array reference. If an array reference, each element is in the form: .PP .Vb 4 \& { \& sep => \*(Aq.\*(Aq, \& prefix => \*(AqINBOX.\*(Aq \& } .Ve .PP (\fIsep\fR is the separator for this hierarchy, and \fIprefix\fR is the prefix). .SS "seq_to_uid(@sequence_ids)" .IX Subsection "seq_to_uid(@sequence_ids)" I recommend usage of UID-s only (see \*(L"uid_mode\*(R") but this isn't always possible. Even when \f(CW\*(C`uid_mode\*(C'\fR is on, the server will sometimes return notifications that only contain message sequence numbers. To convert these to UID-s you can use this method. .PP On success it returns an hash reference which maps sequence numbers to message UID-s. Of course, on failure it returns \fIundef\fR. .ie n .SS "search($criteria, $sort, $charset)" .el .SS "search($criteria, \f(CW$sort\fP, \f(CW$charset\fP)" .IX Subsection "search($criteria, $sort, $charset)" Executes the \*(L"\s-1SEARCH\*(R"\s0 or \*(L"\s-1SORT\*(R" IMAP\s0 commands (depending on wether \&\f(CW$sort\fR is \fIundef\fR) and returns the results as an array reference containing message ID-s. .PP Note that if you use \f(CW$sort\fR and the \s-1IMAP\s0 server doesn't have this capability, this method will fail. Use \*(L"capability\*(R" to investigate. .ie n .IP "\- \fB\fB$criteria\fB\fR" 4 .el .IP "\- \fB\f(CB$criteria\fB\fR" 4 .IX Item "- $criteria" Can be a string, in which case it is passed literally to the \s-1IMAP\s0 command (which can be \*(L"\s-1SEARCH\*(R"\s0 or \*(L"\s-1SORT\*(R"\s0). .Sp It can also be an hash reference, in which case keys => values are collected into a string and values are properly quoted, i.e.: .Sp .Vb 2 \& { subject => \*(Aqfoo\*(Aq, \& from => \*(Aqbar\*(Aq } .Ve .Sp will translate to: .Sp .Vb 1 \& \*(AqSUBJECT "foo" FROM "bar"\*(Aq .Ve .Sp which is a valid \s-1IMAP SEARCH\s0 query. .Sp If you want to retrieve all messages (no search criteria) then pass \&'\s-1ALL\s0' here. .ie n .IP "\- \fB\fB$sort\fB\fR" 4 .el .IP "\- \fB\f(CB$sort\fB\fR" 4 .IX Item "- $sort" Can be a string or an array reference. If it's an array, it will simply be joined with a space, so for instance passing the following is equivalent: .Sp .Vb 2 \& \*(AqSUBJECT DATE\*(Aq \& [ \*(AqSUBJECT\*(Aq, \*(AqDATE\*(Aq ] .Ve .Sp The \s-1SORT\s0 command in \s-1IMAP\s0 allows you to prefix a sort criteria with \&'\s-1REVERSE\s0' which would mean descending sorting; this module will allow you to prefix it with '^', so again, here are some equivalent constructs: .Sp .Vb 5 \& \*(AqSUBJECT REVERSE DATE\*(Aq \& \*(AqSUBJECT ^DATE\*(Aq \& [ \*(AqSUBJECT\*(Aq, \*(AqREVERSE\*(Aq, \*(AqDATE\*(Aq ] \& [ \*(Aqsubject\*(Aq, \*(Aqreverse date\*(Aq ] \& [ \*(AqSUBJECT\*(Aq, \*(Aq^DATE\*(Aq ] .Ve .Sp It'll also uppercase whatever you passed here. .Sp If you omit \f(CW$sort\fR (or pass \fIundef\fR) then this method will use the \&\s-1SEARCH\s0 command. Otherwise it uses the \s-1SORT\s0 command. .ie n .IP "\- \fB\fB$charset\fB\fR" 4 .el .IP "\- \fB\f(CB$charset\fB\fR" 4 .IX Item "- $charset" The \s-1IMAP SORT\s0 recommendation [2] requires a charset declaration for \&\s-1SORT,\s0 but not for \s-1SEARCH. \s0 Interesting, huh? .Sp Our module is a bit more paranoid and it will actually add charset for both \s-1SORT\s0 and \s-1SEARCH. \s0 If \f(CW$charset\fR is omitted (or \fIundef\fR) the it will default to \*(L"\s-1UTF\-8\*(R",\s0 which, supposedly, is supported by all \s-1IMAP\s0 servers. .SS "get_rfc822_body($msg_id)" .IX Subsection "get_rfc822_body($msg_id)" Fetch and return the full \s-1RFC822\s0 body of the message. \fB\f(CB$msg_id\fB\fR can be a scalar but also an array of ID-s. If it's an array, then all bodies of those messages will be fetched and the return value will be a list or an array reference (depending how you call it). .PP Note that the actual data is returned as a reference to a scalar, to speed things up. .PP Examples: .PP .Vb 2 \& my $data = $imap\->get_rfc822_body(10); \& print $$data; # need to dereference it \& \& my @more = $imap\->get_rfc822_body([ 11, 12, 13 ]); \& print $$_ foreach @more; \& \& or \& \& my $more = $imap\->get_rfc822_body([ 11, 12, 13 ]); \& print $$_ foreach @$more; .Ve .ie n .SS "get_part_body($msg_id, $part_id)" .el .SS "get_part_body($msg_id, \f(CW$part_id\fP)" .IX Subsection "get_part_body($msg_id, $part_id)" Fetches and returns the body of a certain part of the message. Part ID-s look like '1' or '1.1' or '2.3.1' etc. (see \s-1RFC3501\s0 [1], \*(L"\s-1FETCH\s0 Command\*(R"). .PP \fIScalar reference\fR .IX Subsection "Scalar reference" .PP Note that again, this data is returned as a reference to a scalar rather than the scalar itself. This decision was taken purely to save some time passing around potentially large data from Perl subroutines. .PP \fIUndecoded\fR .IX Subsection "Undecoded" .PP One other thing to note is that the data is not decoded. One simple way to decode it is use Email::MIME::Encodings, i.e.: .PP .Vb 6 \& use Email::MIME::Encodings; \& my $summary = $imap\->get_summaries(10)\->[0]; \& my $part = $summary\->get_subpart(\*(Aq1.1\*(Aq); \& my $body = $imap\->get_part_body(\*(Aq1.1\*(Aq); \& my $cte = $part\->transfer_encoding; # Content\-Transfer\-Encoding \& $body = Email::MIME::Encodings::decode($cte, $$body); \& \& # and now you should have the undecoded (perhaps binary) data. .Ve .PP See get_summaries below. .SS "get_parts_bodies($msg_id, \e@part_ids)" .IX Subsection "get_parts_bodies($msg_id, @part_ids)" Similar to get_part_body, but this method is capable to retrieve more parts at once. It's of course faster than calling get_part_body for each part alone. Returns an hash reference which maps part \s-1ID\s0 to part body (the latter is a reference to a scalar containing the actual data). Again, the data is not unencoded. .PP .Vb 2 \& my $parts = $imap\->get_parts_bodies(10, [ \*(Aq1.1\*(Aq, \*(Aq1.2\*(Aq, \*(Aq2.1\*(Aq ]); \& print ${$parts\->{\*(Aq1.1\*(Aq}}; .Ve .ie n .SS "get_summaries($msg, $headers) / get_summaries(\e@msgs, $headers)" .el .SS "get_summaries($msg, \f(CW$headers\fP) / get_summaries(\e@msgs, \f(CW$headers\fP)" .IX Subsection "get_summaries($msg, $headers) / get_summaries(@msgs, $headers)" (\f(CW$headers\fR is optional). .PP Fetches, parses and returns \*(L"message summaries\*(R". \f(CW$msg\fR can be an array ref, or a single id. The return value is always an array reference, even if a single message is queried. .PP If \f(CW$headers\fR is passed, it must be a string containing name(s) of the header fields to fetch (space separated). Example: .PP .Vb 1 \& $imap\->get_summaries([1, 2, 3], \*(AqReferences X\-Original\-To\*(Aq) .Ve .PP The result contains Net::IMAP::Client::MsgSummary objects. The best way to understand the result is to actually call this function and use Data::Dumper to see its structure. .PP Following is the output for a pretty complicated message, which contains an \s-1HTML\s0 part with an embedded image and an attached message. The attached message in turn contains an \s-1HTML\s0 part and an embedded message. .PP .Vb 10 \& bless( { \& \*(Aqmessage_id\*(Aq => \*(Aq<48A71D17.1000109@foobar.com>\*(Aq, \& \*(Aqdate\*(Aq => \*(AqSat, 16 Aug 2008 21:31:51 +0300\*(Aq, \& \*(Aqto\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => undef, \& \*(Aqmailbox\*(Aq => \*(Aqkwlookup\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqcc\*(Aq => undef, \& \*(Aqfrom\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqflags\*(Aq => [ \& \*(Aq\e\eSeen\*(Aq, \& \*(AqNonJunk\*(Aq, \& \*(Aqfoo_bara\*(Aq \& ], \& \*(Aquid\*(Aq => \*(Aq11\*(Aq, \& \*(Aqsubject\*(Aq => \*(Aqtest with message attachment\*(Aq, \& \*(Aqrfc822_size\*(Aq => \*(Aq12550\*(Aq, \& \*(Aqin_reply_to\*(Aq => undef, \& \*(Aqbcc\*(Aq => undef, \& \*(Aqinternaldate\*(Aq => \*(Aq16\-Aug\-2008 21:29:23 +0300\*(Aq, \& \*(Aqreply_to\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqsender\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqparts\*(Aq => [ \& bless( { \& \*(Aqpart_id\*(Aq => \*(Aq1\*(Aq, \& \*(Aqparts\*(Aq => [ \& bless( { \& \*(Aqparameters\*(Aq => { \& \*(Aqcharset\*(Aq => \*(AqUTF\-8\*(Aq \& }, \& \*(Aqsubtype\*(Aq => \*(Aqhtml\*(Aq, \& \*(Aqpart_id\*(Aq => \*(Aq1.1\*(Aq, \& \*(Aqencoded_size\*(Aq => \*(Aq365\*(Aq, \& \*(Aqcid\*(Aq => undef, \& \*(Aqtype\*(Aq => \*(Aqtext\*(Aq, \& \*(Aqdescription\*(Aq => undef, \& \*(Aqtransfer_encoding\*(Aq => \*(Aq7bit\*(Aq \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ), \& bless( { \& \*(Aqdisposition\*(Aq => { \& \*(Aqinline\*(Aq => { \& \*(Aqfilename\*(Aq => \*(Aqsomeimage.png\*(Aq \& } \& }, \& \*(Aqlanguage\*(Aq => undef, \& \*(Aqencoded_size\*(Aq => \*(Aq4168\*(Aq, \& \*(Aqdescription\*(Aq => undef, \& \*(Aqtransfer_encoding\*(Aq => \*(Aqbase64\*(Aq, \& \*(Aqparameters\*(Aq => { \& \*(Aqname\*(Aq => \*(Aqsomeimage.png\*(Aq \& }, \& \*(Aqsubtype\*(Aq => \*(Aqpng\*(Aq, \& \*(Aqpart_id\*(Aq => \*(Aq1.2\*(Aq, \& \*(Aqtype\*(Aq => \*(Aqimage\*(Aq, \& \*(Aqcid\*(Aq => \*(Aq\*(Aq, \& \*(Aqmd5\*(Aq => undef \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ) \& ], \& \*(Aqmultipart_type\*(Aq => \*(Aqrelated\*(Aq \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ), \& bless( { \& \*(Aqmessage_id\*(Aq => \*(Aq<48A530CE.3050807@foobar.com>\*(Aq, \& \*(Aqdate\*(Aq => \*(AqFri, 15 Aug 2008 10:31:26 +0300\*(Aq, \& \*(Aqencoded_size\*(Aq => \*(Aq6283\*(Aq, \& \*(Aqto\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => undef, \& \*(Aqmailbox\*(Aq => \*(Aqkwlookup\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqsubtype\*(Aq => \*(Aqrfc822\*(Aq, \& \*(Aqcc\*(Aq => undef, \& \*(Aqfrom\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqsubject\*(Aq => \*(AqTest with images\*(Aq, \& \*(Aqin_reply_to\*(Aq => undef, \& \*(Aqdescription\*(Aq => undef, \& \*(Aqtransfer_encoding\*(Aq => \*(Aq7bit\*(Aq, \& \*(Aqparameters\*(Aq => { \& \*(Aqname\*(Aq => \*(AqAttached Message\*(Aq \& }, \& \*(Aqbcc\*(Aq => undef, \& \*(Aqpart_id\*(Aq => \*(Aq2\*(Aq, \& \*(Aqsender\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqreply_to\*(Aq => [ \& bless( { \& \*(Aqat_domain_list\*(Aq => undef, \& \*(Aqname\*(Aq => \*(AqMihai Bazon\*(Aq, \& \*(Aqmailbox\*(Aq => \*(Aqjustme\*(Aq, \& \*(Aqhost\*(Aq => \*(Aqfoobar.com\*(Aq \& }, \*(AqNet::IMAP::Client::MsgAddress\*(Aq ) \& ], \& \*(Aqparts\*(Aq => [ \& bless( { \& \*(Aqparameters\*(Aq => { \& \*(Aqcharset\*(Aq => \*(AqUTF\-8\*(Aq \& }, \& \*(Aqsubtype\*(Aq => \*(Aqhtml\*(Aq, \& \*(Aqpart_id\*(Aq => \*(Aq2.1\*(Aq, \& \*(Aqencoded_size\*(Aq => \*(Aq344\*(Aq, \& \*(Aqcid\*(Aq => undef, \& \*(Aqtype\*(Aq => \*(Aqtext\*(Aq, \& \*(Aqdescription\*(Aq => undef, \& \*(Aqtransfer_encoding\*(Aq => \*(Aq7bit\*(Aq \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ), \& bless( { \& \*(Aqdisposition\*(Aq => { \& \*(Aqinline\*(Aq => { \& \*(Aqfilename\*(Aq => \*(Aqlogo.png\*(Aq \& } \& }, \& \*(Aqlanguage\*(Aq => undef, \& \*(Aqencoded_size\*(Aq => \*(Aq4578\*(Aq, \& \*(Aqdescription\*(Aq => undef, \& \*(Aqtransfer_encoding\*(Aq => \*(Aqbase64\*(Aq, \& \*(Aqparameters\*(Aq => { \& \*(Aqname\*(Aq => \*(Aqlogo.png\*(Aq \& }, \& \*(Aqsubtype\*(Aq => \*(Aqpng\*(Aq, \& \*(Aqpart_id\*(Aq => \*(Aq2.2\*(Aq, \& \*(Aqtype\*(Aq => \*(Aqimage\*(Aq, \& \*(Aqcid\*(Aq => \*(Aq\*(Aq, \& \*(Aqmd5\*(Aq => undef \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ) \& ], \& \*(Aqcid\*(Aq => undef, \& \*(Aqtype\*(Aq => \*(Aqmessage\*(Aq, \& \*(Aqmultipart_type\*(Aq => \*(Aqrelated\*(Aq \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ) \& ], \& \*(Aqmultipart_type\*(Aq => \*(Aqmixed\*(Aq \& }, \*(AqNet::IMAP::Client::MsgSummary\*(Aq ); .Ve .PP As you can see, the parser retrieves all data, including from the embedded messages. .PP There are many other modules you can use to fetch such information. Email::Simple and Email::MIME are great. The only problem is that you have to have fetched already the full (\s-1RFC822\s0) body of the message, which is impractical over \s-1IMAP. \s0 When you want to quickly display a folder summary, the only practical way is to issue a \s-1FETCH\s0 command and retrieve only those headers that you are interested in (instead of full body). \f(CW\*(C`get_summaries\*(C'\fR does exactly that (issues a \&\s-1FETCH \s0(\s-1FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODYSTRUCTURE\s0)). It's acceptably fast even for huge folders. .ie n .SS "fetch($msg_id, $attributes)" .el .SS "fetch($msg_id, \f(CW$attributes\fP)" .IX Subsection "fetch($msg_id, $attributes)" This is a low level interface to \s-1FETCH. \s0 It calls the imap \s-1FETCH\s0 command and returns a somewhat parsed hash of the results. .PP \&\f(CW$msg_id\fR can be a single message \s-1ID\s0 or an array of IDs. If a single \&\s-1ID\s0 is given, the return value will be a hash reference containing the requested values. If \f(CW$msg_id\fR is an array, even if it contains a single it, then the return value will be an array of hashes. .PP \&\f(CW$attributes\fR is a string of attributes to \s-1FETCH,\s0 separated with a space, or an array (ref) of attributes. .PP Examples: .PP # retrieve the \s-1UID\s0 of the most recent message .PP .Vb 1 \& my $last_uid = $imap\->fetch(\*(Aq*\*(Aq, \*(AqUID\*(Aq)\->{UID}; .Ve .PP # fetch the flags of the first message .PP .Vb 1 \& my $flags = $imap\->fetch(1, \*(AqFLAGS\*(Aq)\->{FLAGS}; .Ve .PP # fetch flags and some headers (Subject and From) .PP .Vb 6 \& my $headers = \*(AqBODY[HEADER.FIELDS (Subject From)]\*(Aq; \& my $results = $imap\->fetch([1, 2, 3], "FLAGS $headers"); \& foreach my $hash (@$results) { \& print join(" ", @{$hash\->{FLAGS}}), "\en"; \& print $hash\->{$headers}, "\en"; \& } .Ve .SS "\fInotifications()\fP" .IX Subsection "notifications()" The \s-1IMAP\s0 server may send various notifications upon execution of commands. They are collected in an array which is returned by this method (returns an array ref in scalar context, or a list otherwise). It clears the notifications queue so on second call it will return an empty array (unless new notifications were collected in the meantime). .PP Each element in this array (notification) is a hash reference containing one or more or the following: .PP .Vb 9 \& \- seq : the *sequence number* of the changed message \& \- uid : UID of the changed message (NOT ALWAYS available!) \& \- flags : new flags for this message \& \- deleted : when the \eDeleted flag was set for this message \& \- messages : new number of messages in this folder \& \- recent : number of recent messages in this folder \& \- flags : new flags of this folder (seq is missing) \& \- destroyed : when this message was expunged \& \- folder : the name of the selected folder .Ve .PP \&\f(CW\*(C`folder\*(C'\fR is always present. \f(CW\*(C`seq\*(C'\fR is present when a message was changed some flags (in which case you have \f(CW\*(C`flags\*(C'\fR) or was expunged (in which case \f(CW\*(C`destroyed\*(C'\fR is true). When \f(CW\*(C`flags\*(C'\fR were changed and the \fB\eDeleted\fR flag is present, you also get \f(CW\*(C`deleted\*(C'\fR true. .PP \&\f(CW\*(C`seq\*(C'\fR is a message sequence number. Pretty dumb, I think it's preferable to work with UID-s, but that's what the \s-1IMAP\s0 server reports. In some cases the \s-1UID \s0\fImight\fR be readily available (i.e. my \&\s-1IMAP\s0 server sends notifications in the same body as a response to, say, a \s-1FETCH BODY\s0 command), but when it's not, you have to rely on \&\fIseq_to_uid()\fR. \fBNote\fR that when \f(CW\*(C`destroyed\*(C'\fR is true, the message has been \fBexpunged\fR; there is no way in this case to retrieve the \s-1UID\s0 so you have to rely solely on \f(CW\*(C`seq\*(C'\fR in order to update your caches. .PP When \f(CW\*(C`flags\*(C'\fR is present but no \f(CW\*(C`seq\*(C'\fR, it means that the list of available flags for the \f(CW\*(C`folder\*(C'\fR has changed. .PP You get \f(CW\*(C`messages\*(C'\fR upon an \*(L"\s-1EXISTS\*(R"\s0 notification, which usually means \&\*(L"you have new mail\*(R". It indicates the total number of messages in the folder, not just \*(L"new\*(R" messages. I've yet to come up with a good way to measure the number of new/unseen messages, other than calling \&\f(CW\*(C`status($folder)\*(C'\fR. .PP I rarely got \f(CW\*(C`recent\*(C'\fR from my \s-1IMAP\s0 server in my tests; if more clients are simultaneously logged in as the same \s-1IMAP\s0 user, only one of them will receive \*(L"\s-1RECENT\*(R"\s0 notifications; others will have to rely on \*(L"\s-1EXISTS\*(R"\s0 to tell when new messages have arrived. Therefore I can only say that \*(L"\s-1RECENT\*(R"\s0 is useless and I advise you to ignore it. .ie n .SS "append($folder, \e$rfc822, $flags, $date)" .el .SS "append($folder, \e$rfc822, \f(CW$flags\fP, \f(CW$date\fP)" .IX Subsection "append($folder, $rfc822, $flags, $date)" Appends a message to the given \f(CW$folder\fR. You must pass the full \&\s-1RFC822\s0 body in \f(CW$rfc822\fR. \f(CW$flags\fR and \f(CW$date\fR are optional. If you pass \f(CW$flags\fR, it must be an array of strings specifying the initial flags of the appended message. If \fIundef\fR, the message will be appended with an empty flag set, which amongst other things means that it will be regarded as an \f(CW\*(C`\eUnseen\*(C'\fR message. .PP \&\f(CW$date\fR specifies the \s-1INTERNALDATE\s0 of the appended messge. If \&\fIundef\fR it will default to the current date/time. \fB\s-1NOTE:\s0\fR this functionality is not tested; \f(CW$date\fR should be in a format understood by \s-1IMAP.\s0 .SS "get_flags($msg_id) / get_flags(\e@msg_ids)" .IX Subsection "get_flags($msg_id) / get_flags(@msg_ids)" Returns the flags of one or more messages. The return value is an array (reference) if one message \s-1ID\s0 was passed, or a hash reference if an array (of one or more) message ID-s was passed. .PP When an array was passed, the returned hash will map each message \s-1UID\s0 to an array of flags. .ie n .SS "store($msg, $flag) / store(\e@msgs, \e@flags)" .el .SS "store($msg, \f(CW$flag\fP) / store(\e@msgs, \e@flags)" .IX Subsection "store($msg, $flag) / store(@msgs, @flags)" Resets \s-1FLAGS\s0 of the given message(s) to the given flag(s). \f(CW$msg\fR can be an array of ID-s (or UID-s), or a single (U)ID. \f(CW$flags\fR can be a single string, or an array reference as well. .PP Note that the folder where these messages reside must have been already selected. .PP Examples: .PP .Vb 3 \& $imap\->store(10, \*(Aq\e\eSeen\*(Aq); \& $imap\->store([11, 12], \*(Aq\e\eDeleted\*(Aq); \& $imap\->store(13, [ \*(Aq\e\eSeen\*(Aq, \*(Aq\e\eAnswered\*(Aq ]); .Ve .PP The \s-1IMAP\s0 specification defines certain reserved flags (they all start with a backslash). For example, a message with the flag \f(CW\*(C`\eDeleted\*(C'\fR should be regarded as deleted and will be permanently discarded by an \&\s-1EXPUNGE\s0 command. Although, it is possible to \*(L"undelete\*(R" a message by removing this flag. .PP The following reserved flags are defined by the \s-1IMAP\s0 spec: .PP .Vb 6 \& \eSeen \& \eAnswered \& \eFlagged \& \eDeleted \& \eDraft \& \eRecent .Ve .PP The \f(CW\*(C`\eRecent\*(C'\fR flag is considered \*(L"read-only\*(R" \*(-- you cannot add or remove it manually; the server itself will do this as appropriate. .ie n .SS "add_flags($msg, $flag) / add_flags(\e@msgs, \e@flags)" .el .SS "add_flags($msg, \f(CW$flag\fP) / add_flags(\e@msgs, \e@flags)" .IX Subsection "add_flags($msg, $flag) / add_flags(@msgs, @flags)" Like \fIstore()\fR but it doesn't reset all flags \*(-- it just specifies which flags to \fBadd\fR to the message. .ie n .SS "del_flags($msg, $flag) / del_flags(\e@msgs, \e@flags)" .el .SS "del_flags($msg, \f(CW$flag\fP) / del_flags(\e@msgs, \e@flags)" .IX Subsection "del_flags($msg, $flag) / del_flags(@msgs, @flags)" Like \fIstore()\fR / \fIadd_flags()\fR but it \fBremoves\fR flags. .SS "delete_message($msg) / delete_message(\e@msgs)" .IX Subsection "delete_message($msg) / delete_message(@msgs)" Stores the \eDeleted flag on the given message(s). Equivalent to: .PP .Vb 1 \& $imap\->add_flags(\e@msgs, \*(Aq\e\eDeleted\*(Aq); .Ve .SS "\fIexpunge()\fP" .IX Subsection "expunge()" Permanently removes messages that have the \f(CW\*(C`\eDeleted\*(C'\fR flag set from the current folder. .ie n .SS "copy($msg, $folder) / copy(\e@msg_ids, $folder)" .el .SS "copy($msg, \f(CW$folder\fP) / copy(\e@msg_ids, \f(CW$folder\fP)" .IX Subsection "copy($msg, $folder) / copy(@msg_ids, $folder)" Copies message(s) from the selected folder to the given \f(CW$folder\fR. You can pass a single message \s-1ID,\s0 or an array of message ID-s. .SS "create_folder($folder)" .IX Subsection "create_folder($folder)" Creates the folder with the given name. .SS "delete_folder($folder)" .IX Subsection "delete_folder($folder)" Deletes the folder with the given name. This works a bit different from the \s-1IMAP\s0 specs. The \s-1IMAP\s0 specs says that any subfolders should remain intact. This method actually deletes subfolders recursively. Most of the time, this is What You Want. .PP Note that all messages in \f(CW$folder\fR, as well as in any subfolders, are permanently lost. .ie n .SS "get_threads($algorithm, $msg_id)" .el .SS "get_threads($algorithm, \f(CW$msg_id\fP)" .IX Subsection "get_threads($algorithm, $msg_id)" Returns a \*(L"threaded view\*(R" of the current folder. Both arguments are optional. .PP \&\f(CW$algorithm\fR should be \fIundef\fR, \*(L"\s-1REFERENCES\*(R"\s0 or \*(L"\s-1SUBJECT\*(R". \s0 If undefined, \*(L"\s-1REFERENCES\*(R"\s0 is assumed. This selects the threading algorithm, as per \s-1IMAP THREAD AND SORT\s0 extensions specification. I only tested \*(L"\s-1REFERENCES\*(R".\s0 .PP \&\f(CW$msg_id\fR can be undefined, or a message \s-1ID. \s0 If it's undefined, then a threaded view of the whole folder will be returned. If you pass a message \s-1ID,\s0 then this method will return the top-level thread that contains the message. .PP The return value is an array which actually represents threads. Elements of this array are message ID-s, or other arrays (which in turn contain message ID-s or other arrays, etc.). The first element in an array will represent the start of the thread. Subsequent elements are child messages or subthreads. .PP An example should help (\s-1FIXME\s0). .SH "TODO" .IX Header "TODO" .IP "\- authentication schemes other than plain text (\fBhelp wanted\fR)" 4 .IX Item "- authentication schemes other than plain text (help wanted)" .PD 0 .IP "\- better error handling?" 4 .IX Item "- better error handling?" .PD .SH "SEE ALSO" .IX Header "SEE ALSO" Net::IMAP::Simple, Mail::IMAPClient, Mail::IMAPTalk .PP Email::Simple, Email::MIME .PP \&\s-1RFC3501\s0 [1] is a must read if you want to do anything fancier than what this module already supports. .SH "REFERENCES" .IX Header "REFERENCES" [1] http://ietfreport.isoc.org/rfc/rfc3501.txt .PP [2] http://ietfreport.isoc.org/all\-ids/draft\-ietf\-imapext\-sort\-20.txt .SH "AUTHOR" .IX Header "AUTHOR" Mihai Bazon, http://www.xuheki.com/ http://www.dynarchlib.com/ http://www.bazon.net/mishoo/ .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) Mihai Bazon 2008. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" \&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0 .PP \&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE \s0(\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\s0