1Simple(3) User Contributed Perl Documentation Simple(3)
2
6 Net::IMAP::Simple - Perl extension for simple IMAP account handling.
7
9 use strict;
10 use warnings;
11 use Net::IMAP::Simple;
12 use Email::Simple;
13 # 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 # Log on
19 if(!$imap->login('user','pass')){
20 print STDERR "Login failed: " . $imap->errstr . "\n";
21 exit(64);
22 }
23 # Print the subject's of all the messages in the INBOX
25 my $nm = $imap->select('INBOX');
26 for(my $i = 1; $i <= $nm; $i++){
28 if($imap->seen($i)){
29 print "*";
30 } else {
31 print " ";
32 }
33 my $es = Email::Simple->new(join '', @{ $imap->top($i) } );
35 printf("[%03d] %s\n", $i, $es->header('Subject'));
37 }
38 $imap->quit;
40
42 This module is a simple way to access IMAP accounts.
43
45 my $imap = Net::IMAP::Simple->new( $server [ :port ]);
46 # OR
48 my $imap = Net::IMAP::Simple->new( $server [, option_name => option_value ] );
50 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 The server parameter may specify just the server, or both the server
57 and port number. To specify an alternate port, seperate it from the
58 server with a colon (":"), "example.com:5143".
59 On success an object is returned. On failure, nothing is returned and
61 an error message is set to $Net::IMAP::Simple.
62 Options are provided as a hash to "new()":
64 port => int
66 Assign the port number (default: 143)
67 timeout => int (default: 90)
69 Connection timeout in seconds.
70 retry => int (default: 1)
72 Attempt to retry the connection attmpt (x) times before giving up
73 retry_delay => int (default: 5)
75 Wait (x) seconds before retrying a connection attempt
76 use_v6 => BOOL
78 If set to true, attempt to use IPv6 sockets rather than IPv4
79 sockets.
80 This option requires the IO::Socket::INET6 module
82 use_ssl => BOOL
84 If set to true, attempt to use IO::Socket::SSL sockets rather than
85 vanilla sockets.
86 This option requires the IO::Socket::SSL module
88 bindaddr => str
90 Assign a local address to bind
91 use_select_cache => BOOL
93 Enable "select()" caching internally
94 select_cache_ttl => int
96 The number of seconds to allow a select cache result live before
97 running "$imap-"select()> again.
98 debug => BOOL | \*HANDLE
100 Enable debugging output. If "\*HANDLE" is a valid file handle,
101 debugging will be written to it. Otherwise debugging will be
102 written to "STDOUT"
103
105 starttls
106 $imap->starttls;
107 If you start an IMAP session and wish to upgrade to SSL later, you
109 can use this function to start TLS. This function will try to
110 "require" IO::Socket::SSL and Net::SSLeay at runtime.
111 login
113 my $inbox_msgs = $imap->login($user, $passwd);
114 This method takes two required parameters, a username and password.
116 This pair is authenticated against the server. If authentication is
117 successful TRUE (1) will be returned
118 Nothing is returned on failure and the "errstr()" error handler is
120 set with the error message.
121 status
123 my $num_messages = $imap->status($folder);
124 my ($unseen, $recent, $num_messages) = $imap->status($folder);
125 Issue a "STATUS" command. The "STATUS" command counts messages
127 without altering the state of the named (optionally) mailbox. It
128 returns either the number of messages, or the number of unseen
129 messages, recent, and the total number of messages.
130 $folder is an optional argument. "status()" will use the current
132 mailbox or "INBOX" if the $folder argument is not provided.
133 This method does not use caching.
135 select
137 my $num_messages = $imap->select($folder);
138 Selects a folder named in the single required parameter. The number
140 of messages in that folder is returned on success. On failure,
141 nothing is returned and the "errstr()" error handler is set with
142 the error message.
143 examine
145 This is very nearly a synonym for "select()". The only real
146 difference is that the EXAMINE command is sent to the server
147 instead of SELECT. Net::IMAP::Simple is otherwise unaware of the
148 read-only-ness of the mailbox.
149 close
151 $imap->close;
152 Un-selects the current mailbox, leaving no mailbox selected.
154 messages
156 print "Messages in Junk Mail -- " . $imap->messages("INBOX.Junk Mail") . "\n";
157 This method is an alias for "$imap-"select>
159 flags
161 print "Avaliable server flags: " . join(", ", $imap->flags) . "\n";
162 This method accepts an optional folder name and returns the current
164 available server flags as a list, for the selected folder. If no
165 folder name is provided the last folder "$imap->select"'ed will be
166 used.
167 This method uses caching.
169 recent
171 print "Recent messages value: " . $imap->recent . "\n";
172 This method accepts an optional folder name and returns the
174 'RECENT' value provided durning a SELECT result set. If no folder
175 name is provided the last folder "$imap->select"'ed will be used.
176 This method uses caching.
178 See also: search
180 unseen
182 print "Unseen messages value: " . $imap->unseen . "\n";
183 This method accepts an optional folder name and returns the
185 'UNSEEN' value provided duringg a SELECT command result. If no
186 folder name is provided the last folder "$imap->select"'ed will be
187 used. If a folder name is provided, this will issue a SELECT
188 first.
189 This method uses caching.
191 NOTE: This is not the opposite of seen below. The UNSEEN value
193 varies from server to server, but according to the IMAP
194 specification, it should be the number of the first unseen message,
195 in the case the flag is provided. (If the flag is not provided,
196 users would have to use the SEARCH command to find it.)
197 See also: search
199 current_box
201 print "Current Mail Box folder: " . $imap->current_box . "\n";
202 This method returns the current working mail box folder name.
204 top
206 my $header = $imap->top( $message_number ); print for @{$header};
207 This method accepts a message number as its required parameter.
209 That message will be retrieved from the currently selected folder.
210 On success this method returns a list reference containing the
211 lines of the header. Nothing is returned on failure and the
212 "errstr()" error handler is set with the error message.
213 seen
215 defined( my $seen = $imap->seen( $message_number ) )
216 or warn "problem testing for \Seen: "
217 . $imap->errstr;
218 print "msg #$message_number has been \Seen!" if $seen;
220 A message number is the only required parameter for this method.
222 The message's "\Seen" flag will be examined and if the message has
223 been seen a true value is returned. A defined false value is
224 returned if the message does not have the "\Seen" flag set. The
225 undefined value is returned when an error has occurred while
226 checking the flag status.
227 NOTE: This is not the opposite of unseen above. This issues a
229 "FETCH" command and checks to see if the given message has been
230 "\Seen" before.
231 deleted
233 defined( my $deleted = $imap->deleted( $message_number ) )
234 or warn "problem testing for \Deleted: "
235 . $imap->errstr;
236 print "msg #$message_number has been \Deleted!" if $deleted;
238 A message number is the only required parameter for this method.
240 The message's "\Deleted" flag will be examined and if the message
241 has been deleted a true value is returned. A defined false value
242 is returned if the message does not have the "\Deleted" flag set.
243 The undefined value is returned when an error has occurred while
244 checking the flag status.
245 list
247 my $message_size = $imap->list($message_number);
248 my $mailbox_sizes = $imap->list;
249 This method returns size information for a message, as indicated in
251 the single optional parameter, or all messages in a mailbox. When
252 querying a single message a scalar value is returned. When listing
253 the entire mailbox a hash is returned. On failure, nothing is
254 returned and the "errstr()" error handler is set with the error
255 message.
256 get
258 my $message = $imap->get( $message_number ) or die $imap->errstr;
259 my @message_lines = $map->get( $message_number ) or die $imap->errstr;
260 This method fetches a message and returns its lines as an array or,
262 the actual message. On failure, either an empty list is returned
263 and the "errstr()" error handler is set with the error message.
264 Historically, "get()" returned the array of lines as a reference to
266 the array instead of returning the message or the array itself.
267 Please note that it still does this, although it may be deprecated
268 in the future.
269 The scalar result returned is actually a blessed arrayref with the
271 stringify member overloaded. If you're intending to use the
272 resulting message as a string more than once, it may make sense to
273 force the stringification first.
274 my $message = $imap->get(1);
276 $message = "$message"; # force stringification
277 It is not normally necessary to do this.
279 put
281 $imap->put( $mailbox_name, $message, @flags ) or warn $imap->errstr;
282 Save a message to the server under the folder named $mailbox_name.
284 You may optionally specify flags for the mail (e.g. "\Seen",
285 "\Answered"), but they must start with a slash.
286 If $msg is an arrayref, the lines will be printed correctly.
288 msg_flags
290 my @flags = $imap->msg_flags( $message_number );
291 my $flags = $imap->msg_flags( $message_number );
292 # aught to come out roughly the same
294 print "Flags on message #$message_number: @flags\n";
295 print "Flags on message #$message_number: $flags\n";
296 Detecting errors with this member functions is usually desirable.
298 In the scalar context, detecting an error is synonymous with
299 testing for defined.
300 if( defined( my $flags = $imap->msg_flags($num) ) ) {
302 # it has $flags!
303 } else {
305 warn "problem listing flags for message #$num: "
306 . $imap->errstr;
307 }
308 In list context, you must call waserr() to test for success.
310 my @flags = $imap->msg_flags($num);
312 warn "problem listing flags for msg #$num: "
313 . $imap->errstr if $imap->waserr;
314 getfh
316 my $file = $imap->getfh( $message_number ); print <$file>;
317 On success this method returns a file handle pointing to the
319 message identified by the required parameter. On failure, nothing
320 is returned and the "errstr()" error handler is set with the error
321 message.
322 quit
324 $imap->quit;
325 OR
327 $imap->quit(BOOL);
329 This method logs out of the IMAP server, expunges the selected
331 mailbox, and closes the connection. No error message will ever be
332 returned from this method.
333 Optionally if BOOL is TRUE (1) then a hard quit is performed which
335 closes the socket connection. This hard quit will still issue both
336 EXPUNGE and LOGOUT commands however the response is ignored and the
337 socket is closed after issuing the commands.
338 last
340 my $message_number = $imap->last;
341 This method returns the message number of the last message in the
343 selected mailbox, since the last time the mailbox was selected. On
344 failure, nothing is returned and the "errstr()" error handler is
345 set with the error message.
346 delete
348 print "Gone!" if $imap->delete( $message_number );
349 This method sets the "\Deleted" flag on the given message (or
351 messages). On success it returns true, false on failure and the
352 "errstr()" error handler is set with the error message. If the
353 flag was already there, no error is produced. I takes either a
354 message number or "sequence set" as the only argument. Note that
355 messages aren't actually deleted until they are expunged (see
356 expunge_mailbox).
357 undelete
359 print "Resurrected!" if $imap->undelete( $message_number );
360 This method removes the "\Deleted" flag on the given message. On
362 success it returns true, false on failure and the "errstr()" error
363 handler is set with the error message. If the flag wasn't there,
364 no error is produced.
365 see
367 print "You've seen message #$msgno" if $imap->see( $messageno );
368 This method sets the "\Seen" flag on the given message. On success
370 it returns true, false on failure and the "errstr()" error handler
371 is set with the error message. If the flag was already there, no
372 error is produced.
373 unsee
375 print "You've not seen message #$msgno" if $imap->unsee( $messageno );
376 This method removes the "\Seen" flag on the given message. On
378 success it returns true, false on failure and the "errstr()" error
379 handler is set with the error message. If the flag wasn't there,
380 no error is produced.
381 add_flags
383 delete and see above really just call this function for those
384 flags.
385 $imap->add_flags( $msgno, qw(\Seen \Deleted) )
387 or die $imap->errstr;
388 sub_flags
390 unsee above really just calls this function for that flag.
391 $imap->sub_flags( $msgno, '\Seen' ) or die $imap->errstr;
393 mailboxes
395 my @boxes = $imap->mailboxes;
396 my @folders = $imap->mailboxes("Mail/%");
397 my @lists = $imap->mailboxes("lists/perl/*", "/Mail/");
398 This method returns a list of mailboxes. When called with no
400 arguments it recurses from the IMAP root to get all mailboxes. The
401 first optional argument is a mailbox path and the second is the
402 path reference. RFC 3501 section 6.3.8 has more information.
403 On failure nothing is returned and the "errstr()" error handler is
405 set with the error message.
406 mailboxes_subscribed
408 my @boxes = $imap->mailboxes_subscribed;
409 my @folders = $imap->mailboxes_subscribed("Mail/%");
410 my @lists = $imap->mailboxes_subscribed("lists/perl/*", "/Mail/");
411 This method returns a list of mailboxes subscribed to. When called
413 with no arguments it recurses from the IMAP root to get all
414 mailboxes. The first optional argument is a mailbox path and the
415 second is the path reference. RFC 3501 has more information.
416 On failure nothing is returned and the "errstr()" error handler is
418 set with the error message.
419 create_mailbox
421 print "Created" if $imap->create_mailbox( "/Mail/lists/perl/advocacy" );
422 This method creates the mailbox named in the required argument.
424 Returns true on success, false on failure and the "errstr()" error
425 handler is set with the error message.
426 expunge_mailbox
428 my @expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );
429 die $imap->errstr if $imap->waserr;
430 my $expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" )
432 or die $imap->errstr;
433 This method removes all mail marked as deleted in the mailbox named
435 in the required argument. Returns either the number of messages
436 that were expunged, or the indexes of those messages -- which has a
437 questionable usefulness since it tends to return numbers that don't
438 relate to the message numbers marked with the "\Deleted" flags.
439 If 0 messages were expunged without error, the function will return
441 0E0 so it will still test true, but also evaluate to 0.
442 In list context, you must call waserr() to test for success.
444 delete_mailbox
446 print "Deleted" if $imap->delete_mailbox( "/Mail/lists/perl/advocacy" );
447 This method deletes the mailbox named in the required argument.
449 Returns true on success, false on failure and the "errstr()" error
450 handler is set with the error message.
451 rename_mailbox
453 print "Renamed" if $imap->rename_mailbox( $old => $new );
454 This method renames the mailbox in the first required argument to
456 the mailbox named in the second required argument. Returns true on
457 success, false on failure and the "errstr()" error handler is set
458 with the error message.
459 folder_subscribe
461 print "Subscribed" if $imap->folder_subscribe( "/Mail/lists/perl/advocacy" );
462 This method subscribes to the folder. Returns true on success,
464 false on failure and the "errstr()" error handler is set with the
465 error message.
466 folder_unsubscribe
468 print "Unsubscribed" if $imap->folder_unsubscribe( "/Mail/lists/perl/advocacy" );
469 This method un-subscribes to the folder. Returns true on success,
471 false on failure and the "errstr()" error handler is set with the
472 error message.
473 copy
475 print "copied" if $imap->copy( $message_number, $mailbox );
476 This method copies the message number (or "sequence set") in the
478 currently selected mailbox to the fold specified in the second
479 argument. Both arguments are required. On success this method
480 returns true. Returns false on failure and the "errstr()" error
481 handler is set with the error message.
482 noop
484 $imap->noop;
485 Performs a null operation. This may be needed to get updates on a
487 mailbox, or ensure that the server does not close the connection as
488 idle. RFC 3501 states that servers' idle timeouts must not be less
489 than 30 minutes.
490 errstr
492 print "Login ERROR: " . $imap->errstr . "\n" if !$imap->login($user, $pass);
493 Return the last error string captured for the last operation which
495 failed.
496 waserr
498 my @flags = $imap->msg_flags(14);
499 die $imap->errstr if $imap->waserr;
500 Because "msg_flags()" can optionally return a list, it's not really
502 possible to detect failure in list context. Therefore, you must
503 call "waserr()" if you wish to detect errors.
504 Few of the Net::IMAP::Simple methods use "waserr()". The ones that
506 do will mention it.
507
509 search
510 This function returns an array of message numbers (in list context)
511 or the number of matched messages (in scalar context). It takes a
512 single argument: the search.
513 IMAP searching can be a little confusing and this function makes no
515 attempt to parse your searches. If you wish to do searches by
516 hand, please see RFC 3501.
517 IMAP sorting (see RFC 5256) is supported via an optional second
519 argument. The RFC requires the charset be specified, which can be
520 provided via the optional third argument (defaults to UTF-8).
521 Here are a few examples:
523 my @ids = $imap->search("UNSEEN");
525 my @ids = $imap->search('SUBJECT "blarg is \"blarg\""');
526 my @ids = $imap->search('FROM "joe@aol.com"');
527 my @ids = $imap->search("DELETED");
528 # example from RFC 3501, search terms are ANDed together
530 my @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"');
531 # example from RFC 3501, search terms are ORed together
532 my @ids = $imap->search('OR BODY "blard" SUBJECT "blarg"');
533 # flagged and ( since x or !from y ):
535 my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
536 # no typo above, see the RFC
537 # example from RFC 5256, sorted by subject and reverse date
539 my @ids = $imap->search('BODY "zaphod"', 'SUBJECT REVERSE DATE');
540 Since this module is meant to be simple, Net::IMAP::Simple has a
542 few search helpers. If you need fancy booleans and things, you'll
543 have to learn search. If you need a quick search for unseen
544 messages, see below.
545 These all return an array of messages or count of messages exactly
547 as the search function does. Some of them take arguments, some do
548 not. They do try to grok your arguments slightly, the mechanics of
549 this (if any) will be mentioned below.
550 search_seen
552 Returns numbers of messages that have the \Seen flag.
553 search_recent
555 Returns numbers of messages that have the \Recent flag.
556 search_answered
558 Returns numbers of messages that have the \Answered flag.
559 search_deleted
561 Returns numbers of messages that have the \Deleted flag.
562 search_flagged
564 Returns numbers of messages that have the \Flagged flag.
565 search_draft
567 Returns numbers of messages that have the \Draft flag.
568 search_unseen
570 Returns numbers of messages that do not have the \Seen flag.
571 search_old
573 Returns numbers of messages that do not have the \Recent flag.
574 search_unanswered
576 Returns numbers of messages that do not have the \Answered
577 flag.
578 search_undeleted
580 Returns numbers of messages that do not have the \Deleted flag.
581 search_unflagged
583 Returns numbers of messages that do not have the \Flagged flag.
584 search_smaller
586 This function takes a single argument we'll call "<x>" and
587 returns numbers of messages that are smaller than "<x>" octets.
588 This function will try to force your argument to be a number
589 before passing it to the IMAP server.
590 search_larger
592 This function takes a single argument we'll call "<x>" and
593 returns numbers of messages that are larger than "<x>" octets.
594 This function will try to force your argument to be a number
595 before passing it to the IMAP server.
596 search_from
598 This function takes a single argument we'll call "<x>" and
599 returns numbers of messages that have "<x>" in the from header.
600 This function will attempt to force your string into the
601 RFC3501 quoted-string format.
602 search_to
604 This function takes a single argument we'll call "<x>" and
605 returns numbers of messages that have "<x>" in the to header.
606 This function will attempt to force your string into the
607 RFC3501 quoted-string format.
608 search_cc
610 This function takes a single argument we'll call "<x>" and
611 returns numbers of messages that have "<x>" in the cc header.
612 This function will attempt to force your string into the
613 RFC3501 quoted-string format.
614 search_bcc
616 This function takes a single argument we'll call "<x>" and
617 returns numbers of messages that have "<x>" in the bcc header.
618 This function will attempt to force your string into the
619 RFC3501 quoted-string format.
620 search_subject
622 This function takes a single argument we'll call "<x>" and
623 returns numbers of messages that have "<x>" in the subject
624 header. This function will attempt to force your string into
625 the RFC3501 quoted-string format.
626 search_body
628 This function takes a single argument we'll call "<x>" and
629 returns numbers of messages that have "<x>" in the message
630 body. This function will attempt to force your string into the
631 RFC3501 quoted-string format.
632 search_before
634 This function takes a single argument we'll call "<x>" and
635 returns numbers of messages that were received before "<x>".
636 If you have Date::Manip installed (optional), this function
637 will attempt to force the date into the format "%d-%m-%Y"
638 (date-month-year) as RFC3501 requires. If you do not have that
639 module, no attempt will be made to coerce your date into the
640 correct format.
641 search_since
643 This function takes a single argument we'll call "<x>" and
644 returns numbers of messages that were received after "<x>". If
645 you have Date::Manip installed (optional), this function will
646 attempt to force the date into the format "%d-%m-%Y" (date-
647 month-year) as RFC3501 requires. If you do not have that
648 module, no attempt will be made to coerce your date into the
649 correct format.
650 search_sent_before
652 This function takes a single argument we'll call "<x>" and
653 returns numbers of messages that have a header date before
654 "<x>". If you have Date::Manip installed (optional), this
655 function will attempt to force the date into the format
656 "%d-%m-%Y" (date-month-year) as RFC3501 requires. If you do
657 not have that module, no attempt will be made to coerce your
658 date into the correct format.
659 search_sent_since
661 This function takes a single argument we'll call "<x>" and
662 returns numbers of messages that have a header date after
663 "<x>". If you have Date::Manip installed (optional), this
664 function will attempt to force the date into the format
665 "%d-%m-%Y" (date-month-year) as RFC3501 requires. If you do
666 not have that module, no attempt will be made to coerce your
667 date into the correct format.
668
670 sequence set
671 Message numbers are never checked before being passed to the IMAP
672 server (this is a "simple" module after all), so in most places
673 where a message number is required, you can instead use so-called
674 sequence sets. Examples:
675 $imap->copy( "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
677 $imap->delete( "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
678
680 Creator
681 Joao Fonseca "<joao_g_fonseca@yahoo.com>"
682 2004 maintainer
684 Casey West "<casey@geeknst.com>"
685 2005 maintainer
687 Colin Faber "<cfaber@fpsn.net>"
688 2009 maintainer
690 Paul Miller "<jettero@cpan.org>"
691
693 Copyright (c) 2009 Paul Miller Copyright (c) 2005 Colin Faber Copyright
694 (c) 2004 Casey West Copyright (c) 1999 Joao Fonseca
695 All rights reserved. This program is free software; you can
697 redistribute it and/or modify it under the same terms as Perl itself.
698
700 There's tons, I'm trying to slog through them:
701 https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple
703 <https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>
704
706 perl, Net::IMAP::Server, IO::Socket::SSL, IO::Socket::INET6
707perl v5.12.1 2010-06-07 Simple(3)