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

NAME

6       Net::IMAP::Simple - Perl extension for simple IMAP account handling.
7

SYNOPSIS

9           use strict;
10           use warnings;
11           use Net::IMAP::Simple;
12           use Email::Simple;
13
14           # Create the object
15           my $imap = Net::IMAP::Simple->new('imap.example.com') ||
16              die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";
17
18           # Log on
19           if(!$imap->login('user','pass')){
20               print STDERR "Login failed: " . $imap->errstr . "\n";
21               exit(64);
22           }
23
24           # Print the subject's of all the messages in the INBOX
25           my $nm = $imap->select('INBOX');
26
27           for(my $i = 1; $i <= $nm; $i++){
28               if($imap->seen($i)){
29                   print "*";
30               } else {
31                   print " ";
32               }
33
34               my $es = Email::Simple->new(join '', @{ $imap->top($i) } );
35
36               printf("[%03d] %s\n", $i, $es->header('Subject'));
37           }
38
39           $imap->quit;
40

DESCRIPTION

42       This module is a simple way to access IMAP accounts.
43

OBJECT CREATION METHOD

45           my $imap = Net::IMAP::Simple->new( $server [ :port ]);
46
47           # OR
48
49           my $imap = Net::IMAP::Simple->new( $server [, option_name => option_value ] );
50
51   new
52       This class method constructs a new Net::IMAP::Simple object. It takes
53       one required parameter which is the server to connect to, and
54       additional optional parameters.
55
56       The server parameter may specify just the server, or both the server
57       and port number. To specify an alternate port, separate it from the
58       server with a colon (":"), "example.com:5143".
59
60       On success an object is returned. On failure, nothing is returned and
61       an error message is set to $Net::IMAP::Simple.
62
63       See "PREAUTH" below for a special hostname invocation that doesn't use
64       Sockets (internally).
65
66       Options are provided as a hash to "new()":
67
68       port => int
69           Assign the port number (default: 143)
70
71       timeout => int (default: 90)
72           Connection timeout in seconds.
73
74       retry => int (default: 1)
75           Attempt to retry the connection attmpt (x) times before giving up
76
77       retry_delay => int (default: 5)
78           Wait (x) seconds before retrying a connection attempt
79
80       use_v6 => BOOL
81           If set to true, attempt to use IPv6 sockets rather than IPv4
82           sockets.
83
84           This option requires the IO::Socket::INET6 module
85
86       use_ssl => BOOL
87           If set to true, attempt to use IO::Socket::SSL sockets rather than
88           vanilla sockets.
89
90           Note that no attempt is made to check the certificate validity by
91           default.  This is terrible personal security but matches the
92           previous behavior of this module.  Please consider using
93           "find_ssl_defaults" below.
94
95           This option requires the IO::Socket::SSL module
96
97       ssl_version => version
98           This should be one or more of the following (space separated):
99           SSLv3 SSLv2 TLSv1.  If you specify, for example, "SSLv3 SSLv2" then
100           IO::Socket::SSL will attempt auto negotiation.  At the time of this
101           writing, the default string was v3/v2 auto negotiation -- it may
102           have changed by the time you read this.
103
104           Warning: setting this will also set "use_ssl".
105
106       find_ssl_defaults => []
107           Looks in some standard places for CA certificate libraries and if
108           found sets reasonable defaults along the lines of the following.
109
110               ssl_options => [ SSL_ca_path => "/etc/ssl/certs/",
111                   SSL_verify_mode => IO::Socket::SSL::SSL_VERIFY_PEER() ]
112
113           Warning: setting this will also set "use_ssl".
114
115       ssl_options => []
116           You may provide your own IO::Socket::SSL options if you desire to
117           do so.  It is completely overridden by "find_ssl_defaults" above.
118
119       bindaddr => str
120           Assign a local address to bind
121
122       use_select_cache => BOOL
123           Enable "select()" caching internally
124
125       select_cache_ttl => int
126           The number of seconds to allow a select cache result live before
127           running "$imap->select()" again.
128
129       debug => BOOL | \*HANDLE | warn | file:name
130           Enable debugging output. If "\*HANDLE" is a valid file handle,
131           debugging will be written to it.  If it is the string "warn" then
132           the debugging will be written using the warn command.  If it is a
133           string of the form "file:name" then the named file will be opened
134           for append and the debugs written to it.  Otherwise debugging will
135           be written to "STDOUT"
136
137       readline_callback => CODE
138           You may choose to pass a callback function for the purpose of pre-
139           processing lines before they are handed to the rest of the
140           Net::IMAP::Simple internals.  This can be handy for animating a
141           spinner or modifying the IMAP behavior.
142

PREAUTH

144       Rather than passing a port number and issuing a login, in some
145       situations it may be convenient to authenticate with (for example) ssh
146       and simply invoke (for example) dovecot by hand.
147
148       If the server name starts with "cmd:", then Net::IMAP::Simple will
149       issue the command rather than building sockets.  This is a typical
150       setup:
151
152           my $cmd = "ssh -C mailhost dovecot --exec-mail imap";
153           my $imap = Net::IMAP::Simple->new("cmd:$cmd");
154            # $imap->login(); ... don't need this
155
156           my $number_of_messages = $imap->select("INBOX");
157

METHODS

159       starttls
160               $imap->starttls;
161
162           If you start an IMAP session and wish to upgrade to SSL later, you
163           can use this function to start TLS.  This function will try to
164           "require" IO::Socket::SSL and Net::SSLeay at runtime.
165
166       login
167             my $inbox_msgs = $imap->login($user, $passwd);
168
169           This method takes two required parameters, a username and password.
170           This pair is authenticated against the server. If authentication is
171           successful TRUE (1) will be returned
172
173           Nothing is returned on failure and the "errstr()" error handler is
174           set with the error message.
175
176       status
177               my $num_messages                     = $imap->status($folder);
178               my ($unseen, $recent, $num_messages) = $imap->status($folder);
179
180           Issue a "STATUS" command.  The "STATUS" command counts messages
181           without altering the state of the named (optionally) mailbox.  It
182           returns either the number of messages, or the number of unseen
183           messages, recent, and the total number of messages.
184
185           $folder is an optional argument.  "status()" will use the current
186           mailbox or "INBOX" if the $folder argument is not provided.
187
188           This method does not use caching.
189
190           This method can also query custom status values.  The first
191           argument to the function (if any) is assumed to be the folder name,
192           so the folder argument is required when trying to query custom
193           status values.
194
195               my ($f1, $f2) = $imap->status($folder, qw(f1 f2));
196               my $f2        = $imap->status($folder, qw(f1 f2));
197
198       uidnext
199               my $uidnext = $imap->uidnext($folder);
200
201           Return the "UIDNEXT" value for a mailbox.  The $folder argument is
202           optional.  This is really just an alias for
203
204               my $uidnext = $imap->status($folder, qw(uidnext));
205
206           with the mild difference that it can compute the folder argument
207           for you
208
209       uidvalidity
210               my $uidvalidity = $imap->uidnext($folder);
211
212           Return the "UIDVALIDITY" value for a mailbox.  The $folder argument
213           is optional.  This is also an alias for the status call like
214           "uidnext()" above.
215
216       uid This function is actually an alias for
217           "$imap->uidsearch($msg_range)".
218
219               my($uid)= $imap->uid($msgno);
220               my @uid = $imap->uid($msg_range); # eg 4:14  or 15,4,14
221
222           Return the "UID" value(s) for a message.  These unique IDs "must"
223           stay the same during the session and "should" stay the same between
224           sessions.  Whether they stay the same depends on the "UIDVALIDITY"
225           value; see: above and RFC3501.
226
227           Warning, although you might thing @uid should contain the "UID"s
228           for 15, then 4, then 14 in the example above; most IMAP servers
229           seem to return the UIDs in increasing order.  Normally the sequence
230           numbers are in increasing order also, so it all maches up.
231
232               my ($uid4, $uid14, $uid15) = $imap->uid("15,4,14"); # warning
233
234           One final note, this gives the size of the search match, not the
235           uid like you might expect:
236
237               my $uid_search_result_list_size = $imap->uid('3'); # probably always 1
238
239       seq
240               my $seq = $imap->seq($uids);
241               my @seq = $imap->seq($uids); # eg 58888:58900
242
243           Rather like "uid()" above, but maps uids to sequence numbers.
244
245       select
246               my $num_messages = $imap->select($folder);
247
248           Selects a folder named in the single required parameter. The number
249           of messages in that folder is returned on success. On failure,
250           nothing is returned  and the "errstr()" error handler is set with
251           the error message.
252
253       examine
254           This is very nearly a synonym for "select()".  The only real
255           difference is that the EXAMINE command is sent to the server
256           instead of SELECT.  Net::IMAP::Simple is otherwise unaware of the
257           read-only-ness of the mailbox.
258
259       close
260               $imap->close;
261
262           Un-selects the current mailbox, leaving no mailbox selected.
263
264       messages
265               print "Messages in Junk Mail -- " . $imap->messages("INBOX.Junk Mail") .  "\n";
266
267           This method is an alias for "$imap->select"
268
269       flags
270               print "Available server flags: " . join(", ", $imap->flags) . "\n";
271
272           This method accepts an optional folder name and returns the current
273           available server flags as a list, for the selected folder. If no
274           folder name is provided the last folder "$imap->select"'ed will be
275           used.
276
277           This method uses caching.
278
279       separator
280           Returns the folder separator (technically "hierarchy separator",
281           rfc3501ยง6.3.8) for the server.
282
283       recent
284               print "Recent messages value: " . $imap->recent . "\n";
285
286           This method accepts an optional folder name and returns the
287           'RECENT' value provided durning a SELECT result set. If no folder
288           name is provided the last folder "$imap->select"'ed will be used.
289
290           This method uses caching.
291
292           See also: search
293
294       unseen
295               print "Unseen messages value: " . $imap->unseen . "\n";
296
297           This method accepts an optional folder name and returns the
298           'UNSEEN' value provided during a SELECT command result. If no
299           folder name is provided the last folder "$imap->select"'ed will be
300           used.  If a folder name is provided, this will issue a SELECT
301           first.
302
303           This method uses caching.
304
305           If the server does not provide UNSEEN during SELECT -- surprisingly
306           common -- this method will fall back and use STATUS to determine
307           the unseen count.
308
309           NOTE: This is not the opposite of seen below.  The UNSEEN value
310           varies from server to server, but according to the IMAP
311           specification, it should be the number of the first unseen message,
312           in the case the flag is provided.  (If the flag is not provided,
313           users would have to use the SEARCH command to find it.)
314
315           See also: search
316
317       current_box
318              print "Current Mail Box folder: " . $imap->current_box . "\n";
319
320           This method returns the current working mail box folder name.
321
322       top
323               my $header = $imap->top( $message_number ); print for @{$header};
324
325           This method accepts a message number as its required parameter.
326           That message will be retrieved from the currently selected folder.
327           On success this method returns a list reference containing the
328           lines of the header. Nothing is returned on failure and the
329           "errstr()" error handler is set with the error message.
330
331       seen
332               defined( my $seen = $imap->seen( $message_number ) )
333                   or warn "problem testing for \Seen: "
334                         . $imap->errstr;
335
336               print "msg #$message_number has been \Seen!" if $seen;
337
338           A message number is the only required parameter for this method.
339           The message's "\Seen" flag will be examined and if the message has
340           been seen a true value is returned.  A defined false value is
341           returned if the message does not have the "\Seen" flag set.  The
342           undefined value is returned when an error has occurred while
343           checking the flag status.
344
345           NOTE: This is not the opposite of unseen above.  This issues a
346           "FETCH" command and checks to see if the given message has been
347           "\Seen" before.
348
349       deleted
350               defined( my $deleted = $imap->deleted( $message_number ) )
351                   or warn "problem testing for \Deleted: "
352                         . $imap->errstr;
353
354               print "msg #$message_number has been \Deleted!" if $deleted;
355
356           A message number is the only required parameter for this method.
357           The message's "\Deleted" flag will be examined and if the message
358           has been deleted a true value is returned.  A defined false value
359           is returned if the message does not have the "\Deleted" flag set.
360           The undefined value is returned when an error has occurred while
361           checking the flag status.
362
363       list
364               my $message_size  = $imap->list($message_number);
365               my $mailbox_sizes = $imap->list;
366
367           This method returns size information for a message, as indicated in
368           the single optional parameter, or all messages in a mailbox. When
369           querying a single message a scalar value is returned. When listing
370           the entire mailbox a hash is returned.  On failure, nothing is
371           returned and the "errstr()" error handler is set with the error
372           message.
373
374       fetch
375             my $headers = $imap->fetch("1:5")
376
377           Fetch the headers for messages 1-5 in the current folder.
378
379             for my $midx ( keys %$headers ) {
380                 for my $hdr in ($headers->{$midx}) {
381                     say "$hdr"
382
383                     # In many situations the headers will be parsed and may not be simple
384                     # strings (e.g., with the SimpleX RecDescent parse). The simplest
385                     # way to get a feel for the output is to use a dumper on it.
386                 }
387             }
388
389       get
390             my $message = $imap->get( $message_number ) or die $imap->errstr;
391             my @message_lines = $map->get( $message_number ) or die $imap->errstr;
392
393             my $part = $imap->get( $message_number, '1.1' ) or die $imap->errstr;
394             my @part_lines = $imap->get( $message_number, '1.1' ) or die $imap->errstr;
395
396           This method fetches a message and returns its lines as an array or,
397           the actual message.  On failure, either an empty list is returned
398           and the "errstr()" error handler is set with the error message.
399
400           Optionally, a part can be specified in order to fetch a specific
401           portion of a message.  This is the raw, encoded body of the message
402           part.  The part number is a set of zero or more part specifiers
403           delimited by periods.  Every message has at least one part.
404           Specifying a part of '1' returns the raw, encoded body.  This is
405           only useful if you know the header information such as encoding.
406
407           Historically, "get()" returned the array of lines as a reference to
408           the array instead of returning the message or the array itself.
409           Please note that it still does this, although it may be deprecated
410           in the future.
411
412           The scalar result returned is actually a blessed arrayref with the
413           stringify member overloaded.  If you're intending to use the
414           resulting message as a string more than once, it may make sense to
415           force the stringification first.
416
417               my $message = $imap->get(1);
418                  $message = "$message"; # force stringification
419
420           It is not normally necessary to do this.
421
422       put
423             $imap->put( $mailbox_name, $message, @flags ) or warn $imap->errstr;
424
425           Save a message to the server under the folder named $mailbox_name.
426           You may optionally specify flags for the mail (e.g. "\Seen",
427           "\Answered"), but they must start with a slash.
428
429           If $message is an arrayref, the lines will be printed correctly.
430
431       put_with_date
432             $imap->put_with_date( $mailbox_name, $message, $date, @flags ) or warn $imap->errstr;
433
434           Save a message to the server under the folder named $mailbox_name
435           just like the put method above, but supplying a date will set the
436           IMAP server internal date for the message if supported per RFC 3501
437           Section 6.3.11.
438
439           Note when using this with Gmail it expects the date format to be:
440           DD-Mon-YYYY hh:mm:ss tz  for example  31-Dec-2016 12:59:59 -0500
441
442       msg_flags
443               my @flags = $imap->msg_flags( $message_number );
444               my $flags = $imap->msg_flags( $message_number );
445
446               # aught to come out roughly the same
447               print "Flags on message #$message_number: @flags\n";
448               print "Flags on message #$message_number: $flags\n";
449
450           Detecting errors with this member functions is usually desirable.
451           In the scalar context, detecting an error is synonymous with
452           testing for defined.
453
454               if( defined( my $flags = $imap->msg_flags($num) ) ) {
455                   # it has $flags!
456
457               } else {
458                   warn "problem listing flags for message #$num: "
459                      . $imap->errstr;
460               }
461
462           In list context, you must call waserr() to test for success.
463
464               my @flags = $imap->msg_flags($num);
465               warn "problem listing flags for msg #$num: "
466                  . $imap->errstr if $imap->waserr;
467
468       getfh
469             my $file = $imap->getfh( $message_number ); print <$file>;
470
471           On success this method returns a file handle pointing to the
472           message identified by the required parameter. On failure, nothing
473           is returned and the "errstr()" error handler is set with the error
474           message.
475
476       quit
477             $imap->quit;
478
479             OR
480
481             $imap->quit(BOOL);
482
483           This method logs out of the IMAP server, expunges the selected
484           mailbox, and closes the connection. No error message will ever be
485           returned from this method.
486
487           Optionally if BOOL is TRUE (1) then a hard quit is performed which
488           closes the socket connection. This hard quit will still issue both
489           EXPUNGE and LOGOUT commands however the response is ignored and the
490           socket is closed after issuing the commands.
491
492       logout
493             $imap->logout;
494
495           This method is just like the quit method except that it does not
496           have a hard quit option and it does not expunge the mailbox before
497           it hangs up and closes the socket.
498
499       last
500             my $message_number = $imap->last;
501
502           This method returns the message number of the last message in the
503           selected mailbox, since the last time the mailbox was selected. On
504           failure, nothing is returned and the "errstr()" error handler is
505           set with the error message.
506
507       delete
508             print "Gone!" if $imap->delete( $message_number );
509
510           This method sets the "\Deleted" flag on the given message (or
511           messages). On success it returns true, false on failure and the
512           "errstr()" error handler is set with the error message.  If the
513           flag was already there, no error is produced.  I takes either a
514           message number or "sequence set" as the only argument.  Note that
515           messages aren't actually deleted until they are expunged (see
516           expunge_mailbox).
517
518       undelete
519             print "Resurrected!" if $imap->undelete( $message_number );
520
521           This method removes the "\Deleted" flag on the given message. On
522           success it returns true, false on failure and the "errstr()" error
523           handler is set with the error message.  If the flag wasn't there,
524           no error is produced.
525
526       see
527             print "You've seen message #$msgno" if $imap->see( $messageno );
528
529           This method sets the "\Seen" flag on the given message. On success
530           it returns true, false on failure and the "errstr()" error handler
531           is set with the error message.  If the flag was already there, no
532           error is produced.
533
534       unsee
535             print "You've not seen message #$msgno" if $imap->unsee( $messageno );
536
537           This method removes the "\Seen" flag on the given message. On
538           success it returns true, false on failure and the "errstr()" error
539           handler is set with the error message.  If the flag wasn't there,
540           no error is produced.
541
542       add_flags
543           delete and see above really just call this function for those
544           flags.
545
546              $imap->add_flags( $msgno, qw(\Seen \Deleted) )
547                   or die $imap->errstr;
548
549       sub_flags
550           unsee above really just calls this function for that flag.
551
552              $imap->sub_flags( $msgno, '\Seen' ) or die $imap->errstr;
553
554       mailboxes
555             my @boxes   = $imap->mailboxes;
556             my @folders = $imap->mailboxes("Mail/%");
557             my @lists   = $imap->mailboxes("lists/perl/*", "/Mail/");
558
559           This method returns a list of mailboxes. When called with no
560           arguments it recurses from the IMAP root to get all mailboxes. The
561           first optional argument is a mailbox path and the second is the
562           path reference. RFC 3501 section 6.3.8 has more information.
563
564           On failure nothing is returned and the "errstr()" error handler is
565           set with the error message.
566
567       mailboxes_subscribed
568             my @boxes   = $imap->mailboxes_subscribed;
569             my @folders = $imap->mailboxes_subscribed("Mail/%");
570             my @lists   = $imap->mailboxes_subscribed("lists/perl/*", "/Mail/");
571
572           This method returns a list of mailboxes subscribed to. When called
573           with no arguments it recurses from the IMAP root to get all
574           mailboxes. The first optional argument is a mailbox path and the
575           second is the path reference. RFC 3501 has more information.
576
577           On failure nothing is returned and the "errstr()" error handler is
578           set with the error message.
579
580       create_mailbox
581             print "Created" if $imap->create_mailbox( "/Mail/lists/perl/advocacy" );
582
583           This method creates the mailbox named in the required argument.
584           Returns true on success, false on failure and the "errstr()" error
585           handler is set with the error message.
586
587       expunge_mailbox
588             my @expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );
589             die $imap->errstr if $imap->waserr;
590
591             my $expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" )
592                 or die $imap->errstr;
593
594           This method removes all mail marked as deleted in the mailbox named
595           in the required argument. Returns either the number of messages
596           that were expunged, or the indexes of those messages -- which has a
597           questionable usefulness since it tends to return numbers that don't
598           relate to the message numbers marked with the "\Deleted" flags.
599
600           If 0 messages were expunged without error, the function will return
601           0E0 so it will still test true, but also evaluate to 0.
602
603           In list context, you must call waserr() to test for success.
604
605       delete_mailbox
606             print "Deleted" if $imap->delete_mailbox( "/Mail/lists/perl/advocacy" );
607
608           This method deletes the mailbox named in the required argument.
609           Returns true on success, false on failure and the "errstr()" error
610           handler is set with the error message.
611
612       rename_mailbox
613             print "Renamed" if $imap->rename_mailbox( $old => $new );
614
615           This method renames the mailbox in the first required argument to
616           the mailbox named in the second required argument. Returns true on
617           success, false on failure and the "errstr()" error handler is set
618           with the error message.
619
620       folder_subscribe
621             print "Subscribed" if $imap->folder_subscribe( "/Mail/lists/perl/advocacy" );
622
623           This method subscribes to the folder. Returns true on success,
624           false on failure and the "errstr()" error handler is set with the
625           error message.
626
627       folder_unsubscribe
628             print "Unsubscribed" if $imap->folder_unsubscribe( "/Mail/lists/perl/advocacy" );
629
630           This method un-subscribes to the folder. Returns true on success,
631           false on failure and the "errstr()" error handler is set with the
632           error message.
633
634       copy
635             print "copied" if $imap->copy( $message_number, $mailbox );
636
637           This method copies the message number (or "sequence set") in the
638           currently selected mailbox to the folder specified in the second
639           argument.  Both arguments are required.  On success this method
640           returns true. Returns false on failure and the "errstr()" error
641           handler is set with the error message.
642
643       uidcopy
644             print "copied" if $imap->uidcopy( $message_uid, $mailbox );
645
646           This method is identical to "copy()" above, except that it uses UID
647           numbers instead of sequence numbers.
648
649       noop
650             $imap->noop;
651
652           Performs a null operation.  This may be needed to get updates on a
653           mailbox, or ensure that the server does not close the connection as
654           idle.  RFC 3501 states that servers' idle timeouts must not be less
655           than 30 minutes.
656
657       errstr
658            print "Login ERROR: " . $imap->errstr . "\n" if !$imap->login($user, $pass);
659
660           Return the last error string captured for the last operation which
661           failed.
662
663       waserr
664            my @flags = $imap->msg_flags(14);
665            die $imap->errstr if $imap->waserr;
666
667           Because "msg_flags()" can optionally return a list, it's not really
668           possible to detect failure in list context.  Therefore, you must
669           call "waserr()" if you wish to detect errors.
670
671           Few of the Net::IMAP::Simple methods use "waserr()".  The ones that
672           do will mention it.
673
674       list2range
675           Sometimes you have a long list of sequence numbers which are
676           consecutive and really want to be an IMAP-style range.
677
678               my @list  = (5..9, 13..38, 55,56,57);
679               my $short = $imap->list2range(@list);
680
681               # $short how says: 5:9,13:38,55:57
682
683       range2list
684           Pretty much the opposite of "list2range".
685
686               my @list = $imap->range2list("1,3,5:9");
687               # @list is (1,3,5,6,7,8,9);
688

SEARCHING

690       search
691           This function returns an array of message numbers (in list context)
692           or the number of matched messages (in scalar context).  It takes a
693           single argument: the search.
694
695           IMAP searching can be a little confusing and this function makes no
696           attempt to parse your searches.  If you wish to do searches by
697           hand, please see RFC 3501.
698
699           IMAP sorting (see RFC 5256) is supported via an optional second
700           argument.  The RFC requires the charset be specified, which can be
701           provided via the optional third argument (defaults to UTF-8).
702
703           Here are a few examples:
704
705               my @ids = $imap->search("UNSEEN");
706               my @ids = $imap->search('SUBJECT "blarg is \"blarg\""');
707               my @ids = $imap->search('FROM "joe@aol.com"');
708               my @ids = $imap->search("DELETED");
709
710               # example from RFC 3501, search terms are ANDed together
711               my @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"');
712               # example from RFC 3501, search terms are ORed together
713               my @ids = $imap->search('OR BODY "blard" SUBJECT "blarg"');
714
715               # flagged and ( since x or !from y ):
716               my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
717                 # no typo above, see the RFC
718
719               # example from RFC 5256, sorted by subject and reverse date
720               my @ids = $imap->search('BODY "zaphod"', 'SUBJECT REVERSE DATE');
721
722           Since this module is meant to be simple, Net::IMAP::Simple has a
723           few search helpers.  If you need fancy booleans and things, you'll
724           have to learn search.  If you need a quick search for unseen
725           messages, see below.
726
727           These all return an array of messages or count of messages exactly
728           as the search function does.  Some of them take arguments, some do
729           not.  They do try to grok your arguments slightly, the mechanics of
730           this (if any) will be mentioned below.
731
732           search_seen
733               Returns numbers of messages that have the \Seen flag.
734
735           search_recent
736               Returns numbers of messages that have the \Recent flag.
737
738           search_answered
739               Returns numbers of messages that have the \Answered flag.
740
741           search_deleted
742               Returns numbers of messages that have the \Deleted flag.
743
744           search_flagged
745               Returns numbers of messages that have the \Flagged flag.
746
747           search_draft
748               Returns numbers of messages that have the \Draft flag.
749
750           search_unseen
751               Returns numbers of messages that do not have the \Seen flag.
752
753           search_old
754               Returns numbers of messages that do not have the \Recent flag.
755
756           search_unanswered
757               Returns numbers of messages that do not have the \Answered
758               flag.
759
760           search_undeleted
761               Returns numbers of messages that do not have the \Deleted flag.
762
763           search_unflagged
764               Returns numbers of messages that do not have the \Flagged flag.
765
766           search_smaller
767               This function takes a single argument we'll call "<x>" and
768               returns numbers of messages that are smaller than "<x>" octets.
769               This function will try to force your argument to be a number
770               before passing it to the IMAP server.
771
772           search_larger
773               This function takes a single argument we'll call "<x>" and
774               returns numbers of messages that are larger than "<x>" octets.
775               This function will try to force your argument to be a number
776               before passing it to the IMAP server.
777
778           search_from
779               This function takes a single argument we'll call "<x>" and
780               returns numbers of messages that have "<x>" in the from header.
781               This function will attempt to force your string into the
782               RFC3501 quoted-string format.
783
784           search_to
785               This function takes a single argument we'll call "<x>" and
786               returns numbers of messages that have "<x>" in the to header.
787               This function will attempt to force your string into the
788               RFC3501 quoted-string format.
789
790           search_cc
791               This function takes a single argument we'll call "<x>" and
792               returns numbers of messages that have "<x>" in the cc header.
793               This function will attempt to force your string into the
794               RFC3501 quoted-string format.
795
796           search_bcc
797               This function takes a single argument we'll call "<x>" and
798               returns numbers of messages that have "<x>" in the bcc header.
799               This function will attempt to force your string into the
800               RFC3501 quoted-string format.
801
802           search_subject
803               This function takes a single argument we'll call "<x>" and
804               returns numbers of messages that have "<x>" in the subject
805               header.  This function will attempt to force your string into
806               the RFC3501 quoted-string format.
807
808           search_body
809               This function takes a single argument we'll call "<x>" and
810               returns numbers of messages that have "<x>" in the message
811               body.  This function will attempt to force your string into the
812               RFC3501 quoted-string format.
813
814           search_before
815               This function takes a single argument we'll call "<x>" and
816               returns numbers of messages that were received before "<x>".
817               If you have Date::Manip installed (optional), this function
818               will attempt to force the date into the format "%d-%b-%Y"
819               (date-monthName-year) as RFC3501 requires.  If you do not have
820               that module, no attempt will be made to coerce your date into
821               the correct format.
822
823           search_since
824               This function takes a single argument we'll call "<x>" and
825               returns numbers of messages that were received after "<x>".  If
826               you have Date::Manip installed (optional), this function will
827               attempt to force the date into the format "%d-%m-%Y" (date-
828               month-year) as RFC3501 requires.  If you do not have that
829               module, no attempt will be made to coerce your date into the
830               correct format.
831
832           search_sent_before
833               This function takes a single argument we'll call "<x>" and
834               returns numbers of messages that have a header date before
835               "<x>".  If you have Date::Manip installed (optional), this
836               function will attempt to force the date into the format
837               "%d-%m-%Y" (date-month-year) as RFC3501 requires.  If you do
838               not have that module, no attempt will be made to coerce your
839               date into the correct format.
840
841           search_sent_since
842               This function takes a single argument we'll call "<x>" and
843               returns numbers of messages that have a header date after
844               "<x>".  If you have Date::Manip installed (optional), this
845               function will attempt to force the date into the format
846               "%d-%m-%Y" (date-month-year) as RFC3501 requires.  If you do
847               not have that module, no attempt will be made to coerce your
848               date into the correct format.
849
850       uidsearch
851           This function works exactly like "search()" but it returns UIDs
852           instead of sequence numbers.  The convenient shortcuts above are
853           not provided for it.
854

OTHER NOTES

856       sequence set
857           Message numbers are never checked before being passed to the IMAP
858           server (this is a "simple" module after all), so in most places
859           where a message number is required, you can instead use so-called
860           sequence sets.  Examples:
861
862               $imap->copy(   "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
863               $imap->delete( "3,4,9:22" ) or die $imap->errstr;
864

AUTHOR

866       Creator
867           Joao Fonseca "<joao_g_fonseca@yahoo.com>"
868
869       Maintainer 2004
870           Casey West "<casey@geeknst.com>"
871
872       Maintainer 2005
873           Colin Faber "<cfaber@fpsn.net>"
874
875       Maintainer 2009
876           Paul Miller "<jettero@cpan.org>"
877
879       Copyright (c) 2009-2010 Paul Miller Copyright (c) 2005 Colin Faber
880       Copyright (c) 2004 Casey West Copyright (c) 1999 Joao Fonseca
881
882       All rights reserved. This program is free software; you can
883       redistribute it and/or modify it under the same terms as Perl itself.
884

LICENSE

886       This module is free software.  You can redistribute it and/or modify it
887       under the terms of the Artistic License 2.0.
888
889       This program is distributed in the hope that it will be useful, but
890       without any warranty; without even the implied warranty of
891       merchantability or fitness for a particular purpose.
892
893       [This software may have had previous licenses, of which the current
894       maintainer is completely unaware.  If this is so, it is possible the
895       above license is incorrect or invalid.]
896

BUGS

898       There are probably bugs.  But don't worry, the current maintainer takes
899       them very seriously and will usually triage (at least) within a single
900       day.
901
902       <https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>
903

SEE ALSO

905       perl, Net::IMAP::Server, IO::Socket::SSL, IO::Socket::INET6
906
907
908
909perl v5.34.0                      2021-07-22              Net::IMAP::Simple(3)
Impressum