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