1Net::IMAP::Client(3) User Contributed Perl Documentation Net::IMAP::Client(3)
2
6 Net::IMAP::Client - Not so simple IMAP client library
7
9 use Net::IMAP::Client;
10 my $imap = Net::IMAP::Client->new(
12 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 ) or die "Could not connect to IMAP server";
23 # everything's useless if you can't login
25 $imap->login or
26 die('Login failed: ' . $imap->last_error);
27 # 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 # get list of folders
34 my @folders = $imap->folders;
35 # get total # of messages, # of unseen messages etc. (fast!)
37 my $status = $imap->status(@folders); # hash ref!
38 # select folder
40 $imap->select('INBOX');
41 # get folder hierarchy separator (cached at first call)
43 my $sep = $imap->separator;
44 # fetch all message ids (as array reference)
46 my $messages = $imap->search('ALL');
47 # fetch all ID-s sorted by subject
49 my $messages = $imap->search('ALL', 'SUBJECT');
50 # or
51 my $messages = $imap->search('ALL', [ 'SUBJECT' ]);
52 # 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 # fetch message summaries (actually, a lot more)
60 my $summaries = $imap->get_summaries([ @msg_ids ]);
61 foreach (@$summaries) {
63 print $_->uid, $_->subject, $_->date, $_->rfc822_size;
64 print join(', ', @{$_->from}); # etc.
65 }
66 # fetch full message
68 my $data = $imap->get_rfc822_body($msg_id);
69 print $$data; # it's reference to a scalar
70 # fetch full messages
72 my @msgs = $imap->get_rfc822_body([ @msg_ids ]);
73 print $$_ for (@msgs);
74 # fetch single attachment (message part)
76 my $data = $imap->get_part_body($msg_id, '1.2');
77 # 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 # copy messages between folders
86 $imap->select('INBOX');
87 $imap->copy(\@msg_ids, 'Archive');
88 # 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 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 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 new(%args) # constructor
116 my $imap = Net::IMAP::Client->new(%args);
117 Pass to the constructor a hash of arguments that can contain:
119 - server (STRING)
121 Host name or IP of the IMAP server.
122 - user (STRING)
124 User ID (only "clear" login is supported for now!)
125 - pass (STRING)
127 Password
128 - ssl (BOOL, optional, default FALSE)
130 Pass a true value if you want to use IO::Socket::SSL
131 - 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 only need when you set ssl to true
137 - ssl_ca_file (STRING, optional)
139 Pass a file path which used as CA file to verify server
140 at least one of ssl_ca_file and ssl_ca_path is needed for ssl
142 verify
143 server
144 -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 On linux, by default is '/etc/ssl/certs/'
150 at least one of ssl_ca_file and ssl_ca_path is needed for ssl
152 verify
153 server
154 - ssl_options (HASHREF, optional)
156 Optional arguments to be passed to the IO::Socket::SSL object.
157 - uid_mode (BOOL, optional, default TRUE)
159 Whether to use UID command (see RFC3501). Recommended.
160 - socket (IO::Handle, optional)
162 If you already have a socket connected to the IMAP server, you can
163 pass it here.
164 The ssl_ca_file and ssl_ca_path only need when you set ssl_verify_peer
166 to TRUE.
167 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 The constructor doesn't login to the IMAP server -- you need to call
173 $imap->login for that.
174 last_error
176 Returns the last error from the IMAP server.
177 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 Returns undef if login failed.
183 logout / quit
185 Send EXPUNGE and LOGOUT then close connection. "quit" is an alias for
186 "logout".
187 noop
189 "Do nothing" method that calls the IMAP "NOOP" command. It returns a
190 true value upon success, undef otherwise.
191 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 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 if ($imap->capability(/^sort$/i)) {
202 # speaks it
203 }
204 This data is cached, the server will be only hit once.
206 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 - messages
214 Total number of messages in this folder
215 - flags
217 Flags available for this folder (as array ref)
218 - recent
220 Total number of recent messages in this folder
221 - 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 This method is basically stolen from Net::IMAP::Simple.
227 examine($folder)
229 Selects the current IMAP folder in read-only (EXAMINE) mode. Otherwise
230 identical to select.
231 status($folder), status(\@folders)
233 Returns the status of the given folder(s).
234 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 my $inbox = $imap->status('INBOX');
240 print $inbox->{UNSEEN}, $inbox->{MESSAGES};
241 print Data::Dumper::Dumper($inbox);
242 my $all = $imap->status($imap->folders);
244 while (my ($name, $status) = each %$all) {
245 print "$name : $status->{MESSAGES}/$status->{UNSEEN}\n";
246 }
247 This method is designed to be very fast when passed multiple folders.
249 It's a lot faster to call:
250 $imap->status(\@folders);
252 than:
254 $imap->status($_) foreach (@folders);
256 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 separator
263 Returns the folder hierarchy separator. This is provided as a result
264 of the following IMAP command:
265 FETCH "" "*"
267 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 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 my @a = $imap->folders;
277 my $b = $imap->folders;
278 # now @a == @$b;
279 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 - 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 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 - `personal' -- the personal namespace
294 - `other' -- "other users" namespace
295 - `shared' -- shared namespace
296 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 {
301 sep => '.',
302 prefix => 'INBOX.'
303 }
304 (sep is the separator for this hierarchy, and prefix is the prefix).
306 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 On success it returns an hash reference which maps sequence numbers to
314 message UID-s. Of course, on failure it returns undef.
315 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 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 - $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 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 { subject => 'foo',
332 from => 'bar' }
333 will translate to:
335 'SUBJECT "foo" FROM "bar"'
337 which is a valid IMAP SEARCH query.
339 If you want to retrieve all messages (no search criteria) then pass
341 'ALL' here.
342 - $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 'SUBJECT DATE'
349 [ 'SUBJECT', 'DATE' ]
350 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 'SUBJECT REVERSE DATE'
357 'SUBJECT ^DATE'
358 [ 'SUBJECT', 'REVERSE', 'DATE' ]
359 [ 'subject', 'reverse date' ]
360 [ 'SUBJECT', '^DATE' ]
361 It'll also uppercase whatever you passed here.
363 If you omit $sort (or pass undef) then this method will use the
365 SEARCH command. Otherwise it uses the SORT command.
366 - $charset
368 The IMAP SORT recommendation [2] requires a charset declaration for
369 SORT, but not for SEARCH. Interesting, huh?
370 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 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 Note that the actual data is returned as a reference to a scalar, to
383 speed things up.
384 Examples:
386 my $data = $imap->get_rfc822_body(10);
388 print $$data; # need to dereference it
389 my @more = $imap->get_rfc822_body([ 11, 12, 13 ]);
391 print $$_ foreach @more;
392 or
394 my $more = $imap->get_rfc822_body([ 11, 12, 13 ]);
396 print $$_ foreach @$more;
397 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 Scalar reference
404 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 Undecoded
410 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 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 # and now you should have the undecoded (perhaps binary) data.
422 See get_summaries below.
424 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 my $parts = $imap->get_parts_bodies(10, [ '1.1', '1.2', '2.1' ]);
433 print ${$parts->{'1.1'}};
434 get_summaries($msg, $headers) / get_summaries(\@msgs, $headers)
436 ($headers is optional).
437 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 If $headers is passed, it must be a string containing name(s) of the
443 header fields to fetch (space separated). Example:
444 $imap->get_summaries([1, 2, 3], 'References X-Original-To')
446 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 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 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 As you can see, the parser retrieves all data, including from the
630 embedded messages.
631 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 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 $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 $attributes is a string of attributes to FETCH, separated with a space,
652 or an array (ref) of attributes.
653 Examples:
655 # retrieve the UID of the most recent message
657 my $last_uid = $imap->fetch('*', 'UID')->{UID};
659 # fetch the flags of the first message
661 my $flags = $imap->fetch(1, 'FLAGS')->{FLAGS};
663 # fetch flags and some headers (Subject and From)
665 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 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 Each element in this array (notification) is a hash reference
681 containing one or more or the following:
682 - 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 "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 "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 When "flags" is present but no "seq", it means that the list of
708 available flags for the "folder" has changed.
709 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 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 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 $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 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 When an array was passed, the returned hash will map each message UID
740 to an array of flags.
741 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 Note that the folder where these messages reside must have been already
748 selected.
749 Examples:
751 $imap->store(10, '\\Seen');
753 $imap->store([11, 12], '\\Deleted');
754 $imap->store(13, [ '\\Seen', '\\Answered' ]);
755 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 The following reserved flags are defined by the IMAP spec:
763 \Seen
765 \Answered
766 \Flagged
767 \Deleted
768 \Draft
769 \Recent
770 The "\Recent" flag is considered "read-only" -- you cannot add or
772 remove it manually; the server itself will do this as appropriate.
773 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 del_flags($msg, $flag) / del_flags(\@msgs, \@flags)
779 Like store() / add_flags() but it removes flags.
780 delete_message($msg) / delete_message(\@msgs)
782 Stores the \Deleted flag on the given message(s). Equivalent to:
783 $imap->add_flags(\@msgs, '\\Deleted');
785 expunge()
787 Permanently removes messages that have the "\Deleted" flag set from the
788 current folder.
789 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 create_folder($folder)
795 Creates the folder with the given name.
796 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 Note that all messages in $folder, as well as in any subfolders, are
804 permanently lost.
805 get_threads($algorithm, $msg_id)
807 Returns a "threaded view" of the current folder. Both arguments are
808 optional.
809 $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 $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 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 An example should help (FIXME).
827
829 - authentication schemes other than plain text (help wanted)
830 - better error handling?
831
833 Net::IMAP::Simple, Mail::IMAPClient, Mail::IMAPTalk
834 Email::Simple, Email::MIME
836 RFC3501 [1] is a must read if you want to do anything fancier than what
838 this module already supports.
839
841 [1] http://ietfreport.isoc.org/rfc/rfc3501.txt
842 [2] http://ietfreport.isoc.org/all-ids/draft-ietf-imapext-sort-20.txt
844
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 This module is free software; you can redistribute it and/or modify it
855 under the same terms as Perl itself.
856
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 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.
878perl v5.32.1 2021-01-27 Net::IMAP::Client(3)