1Net::IMAP::Client(3)  User Contributed Perl Documentation Net::IMAP::Client(3)
2
3
4

NAME

6       Net::IMAP::Client - Not so simple IMAP client library
7

SYNOPSIS

9           use Net::IMAP::Client;
10
11           my $imap = Net::IMAP::Client->new(
12
13               server => 'mail.you.com',
14               user   => 'USERID',
15               pass   => 'PASSWORD',
16               ssl    => 1,                              # (use SSL? default no)
17               ssl_verify_peer => 1,                     # (use ca to verify server, default yes)
18               ssl_ca_file => '/etc/ssl/certs/certa.pm', # (CA file used for verify server) or
19             # ssl_ca_path => '/etc/ssl/certs/',         # (CA path used for SSL)
20               port   => 993                             # (but defaults are sane)
21
22           ) or die "Could not connect to IMAP server";
23
24           # everything's useless if you can't login
25           $imap->login or
26             die('Login failed: ' . $imap->last_error);
27
28           # let's see what this server knows (result cached on first call)
29           my $capab = $imap->capability;
30              # or
31           my $knows_sort = $imap->capability( qr/^sort/i );
32
33           # get list of folders
34           my @folders = $imap->folders;
35
36           # get total # of messages, # of unseen messages etc. (fast!)
37           my $status = $imap->status(@folders); # hash ref!
38
39           # select folder
40           $imap->select('INBOX');
41
42           # get folder hierarchy separator (cached at first call)
43           my $sep = $imap->separator;
44
45           # fetch all message ids (as array reference)
46           my $messages = $imap->search('ALL');
47
48           # fetch all ID-s sorted by subject
49           my $messages = $imap->search('ALL', 'SUBJECT');
50              # or
51           my $messages = $imap->search('ALL', [ 'SUBJECT' ]);
52
53           # fetch ID-s that match criteria, sorted by subject and reverse date
54           my $messages = $imap->search({
55               FROM    => 'foo',
56               SUBJECT => 'bar',
57           }, [ 'SUBJECT', '^DATE' ]);
58
59           # fetch message summaries (actually, a lot more)
60           my $summaries = $imap->get_summaries([ @msg_ids ]);
61
62           foreach (@$summaries) {
63               print $_->uid, $_->subject, $_->date, $_->rfc822_size;
64               print join(', ', @{$_->from}); # etc.
65           }
66
67           # fetch full message
68           my $data = $imap->get_rfc822_body($msg_id);
69           print $$data; # it's reference to a scalar
70
71           # fetch full messages
72           my @msgs = $imap->get_rfc822_body([ @msg_ids ]);
73           print $$_ for (@msgs);
74
75           # fetch single attachment (message part)
76           my $data = $imap->get_part_body($msg_id, '1.2');
77
78           # fetch multiple attachments at once
79           my $hash = $imap->get_parts_bodies($msg_id, [ '1.2', '1.3', '2.2' ]);
80           my $part1_2 = $hash->{'1.2'};
81           my $part1_3 = $hash->{'1.3'};
82           my $part2_2 = $hash->{'2.2'};
83           print $$part1_2;              # need to dereference it
84
85           # copy messages between folders
86           $imap->select('INBOX');
87           $imap->copy(\@msg_ids, 'Archive');
88
89           # delete messages ("Move to Trash")
90           $imap->copy(\@msg_ids, 'Trash');
91           $imap->add_flags(\@msg_ids, '\\Deleted');
92           $imap->expunge;
93

DESCRIPTION

95       Net::IMAP::Client provides methods to access an IMAP server.  It aims
96       to provide a simple and clean API, while employing a rigorous parser
97       for IMAP responses in order to create Perl data structures from them.
98       The code is simple, clean and extensible.
99
100       It started as an effort to improve Net::IMAP::Simple but then I
101       realized that I needed to change a lot of code and API so I started it
102       as a fresh module.  Still, the design is influenced by
103       Net::IMAP::Simple and I even stole a few lines of code from it ;-)
104       (very few, honestly).
105
106       This software was developed for creating a web-based email (IMAP)
107       client: www.xuheki.com.  Xhueki uses Net::IMAP::Client.
108

API REFERENCE

110       Unless otherwise specified, if a method fails it returns undef and you
111       can inspect the error by calling $imap->last_error.  For a successful
112       call most methods will return a meaningful value but definitely not
113       undef.
114
115   new(%args)  # constructor
116           my $imap = Net::IMAP::Client->new(%args);
117
118       Pass to the constructor a hash of arguments that can contain:
119
120       - server (STRING)
121           Host name or IP of the IMAP server.
122
123       - user (STRING)
124           User ID (only "clear" login is supported for now!)
125
126       - pass (STRING)
127           Password
128
129       - ssl (BOOL, optional, default FALSE)
130           Pass a true value if you want to use IO::Socket::SSL
131
132       - ssl_verify_peer (BOOL, optional, default TRUE)
133           Pass a false value if you do not want to use SSL CA to verify
134           server
135
136           only need when you set ssl to true
137
138       - ssl_ca_file (STRING, optional)
139           Pass a file path which used as CA file to verify server
140
141           at least one of ssl_ca_file and ssl_ca_path is needed for ssl
142           verify
143            server
144
145       -ssl_ca_path (STRING, optional)
146           Pass a dir which will be used as CA file search dir, found CA file
147           will be used to verify server
148
149           On linux, by default is '/etc/ssl/certs/'
150
151           at least one of ssl_ca_file and ssl_ca_path is needed for ssl
152           verify
153            server
154
155       - ssl_options (HASHREF, optional)
156           Optional arguments to be passed to the IO::Socket::SSL object.
157
158       - uid_mode (BOOL, optional, default TRUE)
159           Whether to use UID command (see RFC3501).  Recommended.
160
161       - socket (IO::Handle, optional)
162           If you already have a socket connected to the IMAP server, you can
163           pass it here.
164
165       The ssl_ca_file and ssl_ca_path only need when you set ssl_verify_peer
166       to TRUE.
167
168       If you havn't apply an ssl_ca_file and ssl_ca_path, on linux, the
169       ssl_ca_path will use the value '/etc/ssl/certs/', on other platform
170       ssl_verify_peer will be disabled.
171
172       The constructor doesn't login to the IMAP server -- you need to call
173       $imap->login for that.
174
175   last_error
176       Returns the last error from the IMAP server.
177
178   login($user, $pass)
179       Login to the IMAP server.  You can pass $user and $pass here if you
180       wish; if not passed, the values used in constructor will be used.
181
182       Returns undef if login failed.
183
184   logout / quit
185       Send EXPUNGE and LOGOUT then close connection.  "quit" is an alias for
186       "logout".
187
188   noop
189       "Do nothing" method that calls the IMAP "NOOP" command.  It returns a
190       true value upon success, undef otherwise.
191
192       This method fetches any notifications that the server might have for us
193       and you can get them by calling $imap->notifications.  See the
194       "notifications()" method.
195
196   capability() / capability(qr/^SOMETHING/)
197       With no arguments, returns an array of all capabilities advertised by
198       the server.  If you're interested in a certain capability you can pass
199       a RegExp.  E.g. to check if this server knows 'SORT', you can do this:
200
201           if ($imap->capability(/^sort$/i)) {
202               # speaks it
203           }
204
205       This data is cached, the server will be only hit once.
206
207   select($folder)
208       Selects the current IMAP folder.  On success this method also records
209       some information about the selected folder in a hash stored in
210       $self->{FOLDERS}{$folder}.  You might want to use Data::Dumper to find
211       out exactly what, but at the time of this writing this is:
212
213       - messages
214           Total number of messages in this folder
215
216       - flags
217           Flags available for this folder (as array ref)
218
219       - recent
220           Total number of recent messages in this folder
221
222       - sflags
223           Various other flags here, such as PERMANENTFLAGS of UIDVALIDITY.
224           You might want to take a look at RFC3501 at this point. :-p
225
226       This method is basically stolen from Net::IMAP::Simple.
227
228   examine($folder)
229       Selects the current IMAP folder in read-only (EXAMINE) mode.  Otherwise
230       identical to select.
231
232   status($folder), status(\@folders)
233       Returns the status of the given folder(s).
234
235       If passed an array ref, the return value is a hash ref mapping folder
236       name to folder status (which are hash references in turn).  If passed a
237       single folder name, it returns the status of that folder only.
238
239           my $inbox = $imap->status('INBOX');
240           print $inbox->{UNSEEN}, $inbox->{MESSAGES};
241           print Data::Dumper::Dumper($inbox);
242
243           my $all = $imap->status($imap->folders);
244           while (my ($name, $status) = each %$all) {
245               print "$name : $status->{MESSAGES}/$status->{UNSEEN}\n";
246           }
247
248       This method is designed to be very fast when passed multiple folders.
249       It's a lot faster to call:
250
251           $imap->status(\@folders);
252
253       than:
254
255           $imap->status($_) foreach (@folders);
256
257       because it sends all the STATUS requests to the IMAP server before it
258       starts receiving the answers.  In my tests with my remote IMAP server,
259       for 40 folders this method takes 0.6 seconds, compared to 6+ seconds
260       when called individually for each folder alone.
261
262   separator
263       Returns the folder hierarchy separator.  This is provided as a result
264       of the following IMAP command:
265
266           FETCH "" "*"
267
268       I don't know of any way to change this value on a server so I have to
269       assume it's a constant.  Therefore, this method caches the result and
270       it won't hit the server a second time on subsequent calls.
271
272   folders
273       Returns a list of all folders available on the server.  In scalar
274       context it returns a reference to an array, i.e.:
275
276           my @a = $imap->folders;
277           my $b = $imap->folders;
278           # now @a == @$b;
279
280   folders_more
281       Returns an hash reference containing more information about folders.
282       It maps folder name to an hash ref containing the following:
283
284         - flags -- folder flags (array ref; i.e. [ '\\HasChildren' ])
285         - sep   -- one character containing folder hierarchy separator
286         - name  -- folder name (same as the key -- thus redundant)
287
288   namespace
289       Returns an hash reference containing the namespaces for this server
290       (see RFC 2342).  Since the RFC defines 3 possible types of namespaces,
291       the hash contains the following keys:
292
293        - `personal' -- the personal namespace
294        - `other' -- "other users" namespace
295        - `shared' -- shared namespace
296
297       Each one can be undef if the server returned "NIL", or an array
298       reference.  If an array reference, each element is in the form:
299
300        {
301           sep    => '.',
302           prefix => 'INBOX.'
303        }
304
305       (sep is the separator for this hierarchy, and prefix is the prefix).
306
307   seq_to_uid(@sequence_ids)
308       I recommend usage of UID-s only (see "uid_mode") but this isn't always
309       possible.  Even when "uid_mode" is on, the server will sometimes return
310       notifications that only contain message sequence numbers.  To convert
311       these to UID-s you can use this method.
312
313       On success it returns an hash reference which maps sequence numbers to
314       message UID-s.  Of course, on failure it returns undef.
315
316   search($criteria, $sort, $charset)
317       Executes the "SEARCH" or "SORT" IMAP commands (depending on wether
318       $sort is undef) and returns the results as an array reference
319       containing message ID-s.
320
321       Note that if you use $sort and the IMAP server doesn't have this
322       capability, this method will fail.  Use "capability" to investigate.
323
324       - $criteria
325           Can be a string, in which case it is passed literally to the IMAP
326           command (which can be "SEARCH" or "SORT").
327
328           It can also be an hash reference, in which case keys => values are
329           collected into a string and values are properly quoted, i.e.:
330
331              { subject => 'foo',
332                from    => 'bar' }
333
334           will translate to:
335
336              'SUBJECT "foo" FROM "bar"'
337
338           which is a valid IMAP SEARCH query.
339
340           If you want to retrieve all messages (no search criteria) then pass
341           'ALL' here.
342
343       - $sort
344           Can be a string or an array reference.  If it's an array, it will
345           simply be joined with a space, so for instance passing the
346           following is equivalent:
347
348               'SUBJECT DATE'
349               [ 'SUBJECT', 'DATE' ]
350
351           The SORT command in IMAP allows you to prefix a sort criteria with
352           'REVERSE' which would mean descending sorting; this module will
353           allow you to prefix it with '^', so again, here are some equivalent
354           constructs:
355
356               'SUBJECT REVERSE DATE'
357               'SUBJECT ^DATE'
358               [ 'SUBJECT', 'REVERSE', 'DATE' ]
359               [ 'subject', 'reverse date' ]
360               [ 'SUBJECT', '^DATE' ]
361
362           It'll also uppercase whatever you passed here.
363
364           If you omit $sort (or pass undef) then this method will use the
365           SEARCH command.  Otherwise it uses the SORT command.
366
367       - $charset
368           The IMAP SORT recommendation [2] requires a charset declaration for
369           SORT, but not for SEARCH.  Interesting, huh?
370
371           Our module is a bit more paranoid and it will actually add charset
372           for both SORT and SEARCH.  If $charset is omitted (or undef) the it
373           will default to "UTF-8", which, supposedly, is supported by all
374           IMAP servers.
375
376   get_rfc822_body($msg_id)
377       Fetch and return the full RFC822 body of the message.  $msg_id can be a
378       scalar but also an array of ID-s.  If it's an array, then all bodies of
379       those messages will be fetched and the return value will be a list or
380       an array reference (depending how you call it).
381
382       Note that the actual data is returned as a reference to a scalar, to
383       speed things up.
384
385       Examples:
386
387           my $data = $imap->get_rfc822_body(10);
388           print $$data;   # need to dereference it
389
390           my @more = $imap->get_rfc822_body([ 11, 12, 13 ]);
391           print $$_ foreach @more;
392
393               or
394
395           my $more = $imap->get_rfc822_body([ 11, 12, 13 ]);
396           print $$_ foreach @$more;
397
398   get_part_body($msg_id, $part_id)
399       Fetches and returns the body of a certain part of the message.  Part
400       ID-s look like '1' or '1.1' or '2.3.1' etc. (see RFC3501 [1], "FETCH
401       Command").
402
403       Scalar reference
404
405       Note that again, this data is returned as a reference to a scalar
406       rather than the scalar itself.  This decision was taken purely to save
407       some time passing around potentially large data from Perl subroutines.
408
409       Undecoded
410
411       One other thing to note is that the data is not decoded.  One simple
412       way to decode it is use Email::MIME::Encodings, i.e.:
413
414           use Email::MIME::Encodings;
415           my $summary = $imap->get_summaries(10)->[0];
416           my $part = $summary->get_subpart('1.1');
417           my $body = $imap->get_part_body('1.1');
418           my $cte = $part->transfer_encoding;  # Content-Transfer-Encoding
419           $body = Email::MIME::Encodings::decode($cte, $$body);
420
421           # and now you should have the undecoded (perhaps binary) data.
422
423       See get_summaries below.
424
425   get_parts_bodies($msg_id, \@part_ids)
426       Similar to get_part_body, but this method is capable to retrieve more
427       parts at once.  It's of course faster than calling get_part_body for
428       each part alone.  Returns an hash reference which maps part ID to part
429       body (the latter is a reference to a scalar containing the actual
430       data).  Again, the data is not unencoded.
431
432           my $parts = $imap->get_parts_bodies(10, [ '1.1', '1.2', '2.1' ]);
433           print ${$parts->{'1.1'}};
434
435   get_summaries($msg, $headers) / get_summaries(\@msgs, $headers)
436       ($headers is optional).
437
438       Fetches, parses and returns "message summaries".  $msg can be an array
439       ref, or a single id.  The return value is always an array reference,
440       even if a single message is queried.
441
442       If $headers is passed, it must be a string containing name(s) of the
443       header fields to fetch (space separated).  Example:
444
445           $imap->get_summaries([1, 2, 3], 'References X-Original-To')
446
447       The result contains Net::IMAP::Client::MsgSummary objects.  The best
448       way to understand the result is to actually call this function and use
449       Data::Dumper to see its structure.
450
451       Following is the output for a pretty complicated message, which
452       contains an HTML part with an embedded image and an attached message.
453       The attached message in turn contains an HTML part and an embedded
454       message.
455
456         bless( {
457           'message_id' => '<48A71D17.1000109@foobar.com>',
458           'date' => 'Sat, 16 Aug 2008 21:31:51 +0300',
459           'to' => [
460               bless( {
461                   'at_domain_list' => undef,
462                   'name' => undef,
463                   'mailbox' => 'kwlookup',
464                   'host' => 'foobar.com'
465               }, 'Net::IMAP::Client::MsgAddress' )
466           ],
467           'cc' => undef,
468           'from' => [
469               bless( {
470                   'at_domain_list' => undef,
471                   'name' => 'Mihai Bazon',
472                   'mailbox' => 'justme',
473                   'host' => 'foobar.com'
474               }, 'Net::IMAP::Client::MsgAddress' )
475           ],
476           'flags' => [
477               '\\Seen',
478               'NonJunk',
479               'foo_bara'
480           ],
481           'uid' => '11',
482           'subject' => 'test with message attachment',
483           'rfc822_size' => '12550',
484           'in_reply_to' => undef,
485           'bcc' => undef,
486           'internaldate' => '16-Aug-2008 21:29:23 +0300',
487           'reply_to' => [
488               bless( {
489                   'at_domain_list' => undef,
490                   'name' => 'Mihai Bazon',
491                   'mailbox' => 'justme',
492                   'host' => 'foobar.com'
493               }, 'Net::IMAP::Client::MsgAddress' )
494           ],
495           'sender' => [
496               bless( {
497                   'at_domain_list' => undef,
498                   'name' => 'Mihai Bazon',
499                   'mailbox' => 'justme',
500                   'host' => 'foobar.com'
501               }, 'Net::IMAP::Client::MsgAddress' )
502           ],
503           'parts' => [
504               bless( {
505                   'part_id' => '1',
506                   'parts' => [
507                       bless( {
508                           'parameters' => {
509                               'charset' => 'UTF-8'
510                           },
511                           'subtype' => 'html',
512                           'part_id' => '1.1',
513                           'encoded_size' => '365',
514                           'cid' => undef,
515                           'type' => 'text',
516                           'description' => undef,
517                           'transfer_encoding' => '7bit'
518                       }, 'Net::IMAP::Client::MsgSummary' ),
519                       bless( {
520                           'disposition' => {
521                               'inline' => {
522                                   'filename' => 'someimage.png'
523                               }
524                           },
525                           'language' => undef,
526                           'encoded_size' => '4168',
527                           'description' => undef,
528                           'transfer_encoding' => 'base64',
529                           'parameters' => {
530                               'name' => 'someimage.png'
531                           },
532                           'subtype' => 'png',
533                           'part_id' => '1.2',
534                           'type' => 'image',
535                           'cid' => '<part1.02030404.05090202@foobar.com>',
536                           'md5' => undef
537                       }, 'Net::IMAP::Client::MsgSummary' )
538                   ],
539                   'multipart_type' => 'related'
540               }, 'Net::IMAP::Client::MsgSummary' ),
541               bless( {
542                   'message_id' => '<48A530CE.3050807@foobar.com>',
543                   'date' => 'Fri, 15 Aug 2008 10:31:26 +0300',
544                   'encoded_size' => '6283',
545                   'to' => [
546                       bless( {
547                           'at_domain_list' => undef,
548                           'name' => undef,
549                           'mailbox' => 'kwlookup',
550                           'host' => 'foobar.com'
551                       }, 'Net::IMAP::Client::MsgAddress' )
552                   ],
553                   'subtype' => 'rfc822',
554                   'cc' => undef,
555                   'from' => [
556                       bless( {
557                           'at_domain_list' => undef,
558                           'name' => 'Mihai Bazon',
559                           'mailbox' => 'justme',
560                           'host' => 'foobar.com'
561                       }, 'Net::IMAP::Client::MsgAddress' )
562                   ],
563                   'subject' => 'Test with images',
564                   'in_reply_to' => undef,
565                   'description' => undef,
566                   'transfer_encoding' => '7bit',
567                   'parameters' => {
568                       'name' => 'Attached Message'
569                   },
570                   'bcc' => undef,
571                   'part_id' => '2',
572                   'sender' => [
573                       bless( {
574                           'at_domain_list' => undef,
575                           'name' => 'Mihai Bazon',
576                           'mailbox' => 'justme',
577                           'host' => 'foobar.com'
578                       }, 'Net::IMAP::Client::MsgAddress' )
579                   ],
580                   'reply_to' => [
581                       bless( {
582                           'at_domain_list' => undef,
583                           'name' => 'Mihai Bazon',
584                           'mailbox' => 'justme',
585                           'host' => 'foobar.com'
586                       }, 'Net::IMAP::Client::MsgAddress' )
587                   ],
588                   'parts' => [
589                       bless( {
590                           'parameters' => {
591                               'charset' => 'UTF-8'
592                           },
593                           'subtype' => 'html',
594                           'part_id' => '2.1',
595                           'encoded_size' => '344',
596                           'cid' => undef,
597                           'type' => 'text',
598                           'description' => undef,
599                           'transfer_encoding' => '7bit'
600                       }, 'Net::IMAP::Client::MsgSummary' ),
601                       bless( {
602                           'disposition' => {
603                               'inline' => {
604                                   'filename' => 'logo.png'
605                               }
606                           },
607                           'language' => undef,
608                           'encoded_size' => '4578',
609                           'description' => undef,
610                           'transfer_encoding' => 'base64',
611                           'parameters' => {
612                               'name' => 'logo.png'
613                           },
614                           'subtype' => 'png',
615                           'part_id' => '2.2',
616                           'type' => 'image',
617                           'cid' => '<part1.02060209.09080406@foobar.com>',
618                           'md5' => undef
619                       }, 'Net::IMAP::Client::MsgSummary' )
620                   ],
621                   'cid' => undef,
622                   'type' => 'message',
623                   'multipart_type' => 'related'
624               }, 'Net::IMAP::Client::MsgSummary' )
625           ],
626           'multipart_type' => 'mixed'
627         }, 'Net::IMAP::Client::MsgSummary' );
628
629       As you can see, the parser retrieves all data, including from the
630       embedded messages.
631
632       There are many other modules you can use to fetch such information.
633       Email::Simple and Email::MIME are great.  The only problem is that you
634       have to have fetched already the full (RFC822) body of the message,
635       which is impractical over IMAP.  When you want to quickly display a
636       folder summary, the only practical way is to issue a FETCH command and
637       retrieve only those headers that you are interested in (instead of full
638       body).  "get_summaries" does exactly that (issues a FETCH (FLAGS
639       INTERNALDATE RFC822.SIZE ENVELOPE BODYSTRUCTURE)).  It's acceptably
640       fast even for huge folders.
641
642   fetch($msg_id, $attributes)
643       This is a low level interface to FETCH.  It calls the imap FETCH
644       command and returns a somewhat parsed hash of the results.
645
646       $msg_id can be a single message ID or an array of IDs.  If a single ID
647       is given, the return value will be a hash reference containing the
648       requested values.  If $msg_id is an array, even if it contains a single
649       it, then the return value will be an array of hashes.
650
651       $attributes is a string of attributes to FETCH, separated with a space,
652       or an array (ref) of attributes.
653
654       Examples:
655
656       # retrieve the UID of the most recent message
657
658           my $last_uid = $imap->fetch('*', 'UID')->{UID};
659
660       # fetch the flags of the first message
661
662           my $flags = $imap->fetch(1, 'FLAGS')->{FLAGS};
663
664       # fetch flags and some headers (Subject and From)
665
666           my $headers = 'BODY[HEADER.FIELDS (Subject From)]';
667           my $results = $imap->fetch([1, 2, 3], "FLAGS $headers");
668           foreach my $hash (@$results) {
669               print join(" ", @{$hash->{FLAGS}}), "\n";
670               print $hash->{$headers}, "\n";
671           }
672
673   notifications()
674       The IMAP server may send various notifications upon execution of
675       commands.  They are collected in an array which is returned by this
676       method (returns an array ref in scalar context, or a list otherwise).
677       It clears the notifications queue so on second call it will return an
678       empty array (unless new notifications were collected in the meantime).
679
680       Each element in this array (notification) is a hash reference
681       containing one or more or the following:
682
683         - seq       : the *sequence number* of the changed message
684         - uid       : UID of the changed message (NOT ALWAYS available!)
685         - flags     : new flags for this message
686         - deleted   : when the \Deleted flag was set for this message
687         - messages  : new number of messages in this folder
688         - recent    : number of recent messages in this folder
689         - flags     : new flags of this folder (seq is missing)
690         - destroyed : when this message was expunged
691         - folder    : the name of the selected folder
692
693       "folder" is always present.  "seq" is present when a message was
694       changed some flags (in which case you have "flags") or was expunged (in
695       which case "destroyed" is true).  When "flags" were changed and the
696       \Deleted flag is present, you also get "deleted" true.
697
698       "seq" is a message sequence number.  Pretty dumb, I think it's
699       preferable to work with UID-s, but that's what the IMAP server reports.
700       In some cases the UID might be readily available (i.e. my IMAP server
701       sends notifications in the same body as a response to, say, a FETCH
702       BODY command), but when it's not, you have to rely on seq_to_uid().
703       Note that when "destroyed" is true, the message has been expunged;
704       there is no way in this case to retrieve the UID so you have to rely
705       solely on "seq" in order to update your caches.
706
707       When "flags" is present but no "seq", it means that the list of
708       available flags for the "folder" has changed.
709
710       You get "messages" upon an "EXISTS" notification, which usually means
711       "you have new mail".  It indicates the total number of messages in the
712       folder, not just "new" messages.  I've yet to come up with a good way
713       to measure the number of new/unseen messages, other than calling
714       "status($folder)".
715
716       I rarely got "recent" from my IMAP server in my tests; if more clients
717       are simultaneously logged in as the same IMAP user, only one of them
718       will receive "RECENT" notifications; others will have to rely on
719       "EXISTS" to tell when new messages have arrived.  Therefore I can only
720       say that "RECENT" is useless and I advise you to ignore it.
721
722   append($folder, \$rfc822, $flags, $date)
723       Appends a message to the given $folder.  You must pass the full RFC822
724       body in $rfc822.  $flags and $date are optional.  If you pass $flags,
725       it must be an array of strings specifying the initial flags of the
726       appended message.  If undef, the message will be appended with an empty
727       flag set, which amongst other things means that it will be regarded as
728       an "\Unseen" message.
729
730       $date specifies the INTERNALDATE of the appended messge.  If undef it
731       will default to the current date/time.  NOTE: this functionality is not
732       tested; $date should be in a format understood by IMAP.
733
734   get_flags($msg_id) / get_flags(\@msg_ids)
735       Returns the flags of one or more messages.  The return value is an
736       array (reference) if one message ID was passed, or a hash reference if
737       an array (of one or more) message ID-s was passed.
738
739       When an array was passed, the returned hash will map each message UID
740       to an array of flags.
741
742   store($msg, $flag) / store(\@msgs, \@flags)
743       Resets FLAGS of the given message(s) to the given flag(s).  $msg can be
744       an array of ID-s (or UID-s), or a single (U)ID.  $flags can be a single
745       string, or an array reference as well.
746
747       Note that the folder where these messages reside must have been already
748       selected.
749
750       Examples:
751
752           $imap->store(10, '\\Seen');
753           $imap->store([11, 12], '\\Deleted');
754           $imap->store(13, [ '\\Seen', '\\Answered' ]);
755
756       The IMAP specification defines certain reserved flags (they all start
757       with a backslash).  For example, a message with the flag "\Deleted"
758       should be regarded as deleted and will be permanently discarded by an
759       EXPUNGE command.  Although, it is possible to "undelete" a message by
760       removing this flag.
761
762       The following reserved flags are defined by the IMAP spec:
763
764           \Seen
765           \Answered
766           \Flagged
767           \Deleted
768           \Draft
769           \Recent
770
771       The "\Recent" flag is considered "read-only" -- you cannot add or
772       remove it manually; the server itself will do this as appropriate.
773
774   add_flags($msg, $flag) / add_flags(\@msgs, \@flags)
775       Like store() but it doesn't reset all flags -- it just specifies which
776       flags to add to the message.
777
778   del_flags($msg, $flag) / del_flags(\@msgs, \@flags)
779       Like store() / add_flags() but it removes flags.
780
781   delete_message($msg) / delete_message(\@msgs)
782       Stores the \Deleted flag on the given message(s).  Equivalent to:
783
784           $imap->add_flags(\@msgs, '\\Deleted');
785
786   expunge()
787       Permanently removes messages that have the "\Deleted" flag set from the
788       current folder.
789
790   copy($msg, $folder) / copy(\@msg_ids, $folder)
791       Copies message(s) from the selected folder to the given $folder.  You
792       can pass a single message ID, or an array of message ID-s.
793
794   create_folder($folder)
795       Creates the folder with the given name.
796
797   delete_folder($folder)
798       Deletes the folder with the given name.  This works a bit different
799       from the IMAP specs.  The IMAP specs says that any subfolders should
800       remain intact.  This method actually deletes subfolders recursively.
801       Most of the time, this is What You Want.
802
803       Note that all messages in $folder, as well as in any subfolders, are
804       permanently lost.
805
806   get_threads($algorithm, $msg_id)
807       Returns a "threaded view" of the current folder.  Both arguments are
808       optional.
809
810       $algorithm should be undef, "REFERENCES" or "SUBJECT".  If undefined,
811       "REFERENCES" is assumed.  This selects the threading algorithm, as per
812       IMAP THREAD AND SORT extensions specification.  I only tested
813       "REFERENCES".
814
815       $msg_id can be undefined, or a message ID.  If it's undefined, then a
816       threaded view of the whole folder will be returned.  If you pass a
817       message ID, then this method will return the top-level thread that
818       contains the message.
819
820       The return value is an array which actually represents threads.
821       Elements of this array are message ID-s, or other arrays (which in turn
822       contain message ID-s or other arrays, etc.).  The first element in an
823       array will represent the start of the thread.  Subsequent elements are
824       child messages or subthreads.
825
826       An example should help (FIXME).
827

TODO

829       - authentication schemes other than plain text (help wanted)
830       - better error handling?
831

SEE ALSO

833       Net::IMAP::Simple, Mail::IMAPClient, Mail::IMAPTalk
834
835       Email::Simple, Email::MIME
836
837       RFC3501 [1] is a must read if you want to do anything fancier than what
838       this module already supports.
839

REFERENCES

841       [1] http://ietfreport.isoc.org/rfc/rfc3501.txt
842
843       [2] http://ietfreport.isoc.org/all-ids/draft-ietf-imapext-sort-20.txt
844

AUTHOR

846       Mihai Bazon, <mihai.bazon@gmail.com>
847           http://www.xuheki.com/
848           http://www.dynarchlib.com/
849           http://www.bazon.net/mishoo/
850
852       Copyright (c) Mihai Bazon 2008.  All rights reserved.
853
854       This module is free software; you can redistribute it and/or modify it
855       under the same terms as Perl itself.
856

DISCLAIMER OF WARRANTY

858       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
859       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
860       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
861       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
862       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
863       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
864       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
865       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
866       NECESSARY SERVICING, REPAIR, OR CORRECTION.
867
868       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
869       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
870       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
871       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
872       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
873       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
874       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
875       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
876       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
877       DAMAGES.
878
879
880
881perl v5.34.0                      2021-07-22              Net::IMAP::Client(3)
Impressum