NAME

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

SYNOPSIS

    use strict;
    use warnings;
    use Net::IMAP::Simple;
    use Email::Simple;

    # Create the object
    my $imap = Net::IMAP::Simple->new('imap.example.com') ||
       die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";

    # Log on
    if(!$imap->login('user','pass')){
        print STDERR "Login failed: " . $imap->errstr . "\n";
        exit(64);
    }

    # Print the subject's of all the messages in the INBOX
    my $nm = $imap->select('INBOX');

    for(my $i = 1; $i <= $nm; $i++){
        if($imap->seen($i)){
            print "*";
        } else {
            print " ";
        }

        my $es = Email::Simple->new(join '', @{ $imap->top($i) } );

        printf("[%03d] %s\n", $i, $es->header('Subject'));
    }

    $imap->quit;

DESCRIPTION

This module is a simple way to access IMAP accounts.

OBJECT CREATION METHOD

    my $imap = Net::IMAP::Simple->new( $server [ :port ]);

    # OR

    my $imap = Net::IMAP::Simple->new( $server [, option_name => option_value ] );

new

This class method constructs a new Net::IMAP::Simple object. It takes one required parameter which is the server to connect to, and additional optional parameters.

The server parameter may specify just the server, or both the server and port number. To specify an alternate port, seperate it from the server with a colon (:), example.com:5143.

On success an object is returned. On failure, nothing is returned and an error message is set to $Net::IMAP::Simple.

Options are provided as a hash to new():

port => int

Assign the port number (default: 143)

timeout => int (default: 90)

Connection timeout in seconds.

retry => int (default: 1)

Attempt to retry the connection attmpt (x) times before giving up

retry_delay => int (default: 5)

Wait (x) seconds before retrying a connection attempt

use_v6 => BOOL

If set to true, attempt to use IPv6 sockets rather than IPv4 sockets.

This option requires the IO::Socket::INET6 module

use_ssl => BOOL

If set to true, attempt to use IO::Socket::SSL sockets rather than vanilla sockets.

This option requires the IO::Socket::SSL module

bindaddr => str

Assign a local address to bind

use_select_cache => BOOL

Enable select() caching internally

select_cache_ttl => int

The number of seconds to allow a select cache result live before running $imap-select()> again.

debug => BOOL | \*HANDLE

Enable debugging output. If \*HANDLE is a valid file handle, debugging will be written to it. Otherwise debugging will be written to STDOUT

METHODS

starttls

    $imap->starttls;

If you start an IMAP session and wish to upgrade to SSL later, you can use this function to start TLS. This function will try to require IO::Socket::SSL and Net::SSLeay at runtime.

login

  my $inbox_msgs = $imap->login($user, $passwd);

This method takes two required parameters, a username and password. This pair is authenticated against the server. If authentication is successful TRUE (1) will be returned

Nothing is returned on failure and the errstr() error handler is set with the error message.

status

    my $num_messages                     = $imap->status($folder);
    my ($unseen, $recent, $num_messages) = $imap->status($folder);

Issue a STATUS command. The STATUS command counts messages without altering the state of the named (optionally) mailbox. It returns either the number of messages, or the number of unseen messages, recent, and the total number of messages.

$folder is an optional argument. status() will use the current mailbox or INBOX if the $folder argument is not provided.

This method does not use caching.

select

    my $num_messages = $imap->select($folder);

Selects a folder named in the single required parameter. The number of messages in that folder is returned on success. On failure, nothing is returned and the errstr() error handler is set with the error message.

examine

This is very nearly a synonym for select(). The only real difference is that the EXAMINE command is sent to the server instead of SELECT. Net::IMAP::Simple is otherwise unaware of the read-only-ness of the mailbox.

messages

    print "Messages in Junk Mail -- " . $imap->messages("INBOX.Junk Mail") .  "\n";

This method is an alias for $imap-select>

flags

    print "Avaliable server flags: " . join(", ", $imap->flags) . "\n";

This method accepts an optional folder name and returns the current available server flags as a list, for the selected folder. If no folder name is provided the last folder $imap->select'ed will be used.

This method uses caching.

recent

    print "Recent messages value: " . $imap->recent . "\n";

This method accepts an optional folder name and returns the 'RECENT' value provided durning a SELECT result set. If no folder name is provided the last folder $imap->select'ed will be used.

This method uses caching.

See also: search

current_box

   print "Current Mail Box folder: " . $imap->current_box . "\n";

This method returns the current working mail box folder name.

top

    my $header = $imap->top( $message_number ); print for @{$header};

This method accepts a message number as its required parameter. That message will be retrieved from the currently selected folder. On success this method returns a list reference containing the lines of the header. Nothing is returned on failure and the errstr() error handler is set with the error message.

seen

    defined( my $seen = $imap->seen( $message_number ) )
        or warn "problem testing for \Seen: "
              . $imap->errstr;

    print "msg #$message_number has been \Seen!" if $seen;

A message number is the only required parameter for this method. The message's \Seen flag will be examined and if the message has been seen a true value is returned. A defined false value is returned if the message does not have the \Seen flag set. The undefined value is returned when an error has occurred while checking the flag status.

NOTE: This is not the opposite of unseen above. This issues a FETCH command and checks to see if the given message has been \Seen before.

deleted

    defined( my $deleted = $imap->deleted( $message_number ) )
        or warn "problem testing for \Deleted: "
              . $imap->errstr;

    print "msg #$message_number has been \Deleted!" if $deleted;

A message number is the only required parameter for this method. The message's \Deleted flag will be examined and if the message has been deleted a true value is returned. A defined false value is returned if the message does not have the \Deleted flag set. The undefined value is returned when an error has occurred while checking the flag status.

list

    my $message_size  = $imap->list($message_number);
    my $mailbox_sizes = $imap->list;

This method returns size information for a message, as indicated in the single optional parameter, or all messages in a mailbox. When querying a single message a scalar value is returned. When listing the entire mailbox a hash is returned. On failure, nothing is returned and the errstr() error handler is set with the error message.

get

  my $message = $imap->get( $message_number ) or die $imap->errstr;
  my @message_lines = $map->get( $message_number ) or die $imap->errstr;

This method fetches a message and returns its lines as an array or, the actual message. On failure, either an empty list is returned and the errstr() error handler is set with the error message.

Historically, get() returned the array of lines as a reference to the array instead of returning the message or the array itself. Please note that it still does this, although it may be deprecated in the future.

The scalar result returned is actually a blessed arrayref with the stringify member overloaded. If you're intending to use the resulting message as a string more than once, it may make sense to force the stringification first.

    my $message = $imap->get(1);
       $message = "$message"; # force stringification

It is not normally necessary to do this.

put

  $imap->put( $mailbox_name, $message, @flags ) or warn $imap->errstr;

Save a message to the server under the folder named $mailbox_name. You may optionally specify flags for the mail (e.g. \Seen, \Answered), but they must start with a slash.

If $msg is an arrayref, the lines will be printed correctly.

msg_flags

    my @flags = $imap->msg_flags( $message_number );
    my $flags = $imap->msg_flags( $message_number );

    # aught to come out roughly the same
    print "Flags on message #$message_number: @flags\n";
    print "Flags on message #$message_number: $flags\n";

Detecting errors with this member functions is usually desirable. In the scalar context, detecting an error is synonymous with testing for defined.

    if( defined( my $flags = $imap->msg_flags($num) ) ) {
        # it has $flags!

    } else {
        warn "problem listing flags for message #$num: " 
           . $imap->errstr;
    }

In list context, you must call waserr() to test for success.

    my @flags = $imap->msg_flags($num);
    warn "problem listing flags for msg #$num: "
       . $imap->errstr if $imap->waserr;

getfh

  my $file = $imap->getfh( $message_number ); print <$file>;

On success this method returns a file handle pointing to the message identified by the required parameter. On failure, nothing is returned and the errstr() error handler is set with the error message.

quit

  $imap->quit;

  OR

  $imap->quit(BOOL);

This method logs out of the IMAP server, expunges the selected mailbox, and closes the connection. No error message will ever be returned from this method.

Optionally if BOOL is TRUE (1) then a hard quit is performed which closes the socket connection. This hard quit will still issue both EXPUNGE and LOGOUT commands however the response is ignored and the socket is closed after issuing the commands.

last

  my $message_number = $imap->last;

This method returns the message number of the last message in the selected mailbox, since the last time the mailbox was selected. On failure, nothing is returned and the errstr() error handler is set with the error message.

delete

  print "Gone!" if $imap->delete( $message_number );

This method sets the \Deleted flag on the given message (or messages). On success it returns true, false on failure and the errstr() error handler is set with the error message. If the flag was already there, no error is produced. I takes either a message number or "sequence set" as the only argument. Note that messages aren't actually deleted until they are expunged (see expunge_mailbox).

undelete

  print "Resurrected!" if $imap->undelete( $message_number );

This method removes the \Deleted flag on the given message. On success it returns true, false on failure and the errstr() error handler is set with the error message. If the flag wasn't there, no error is produced.

see

  print "You've seen message #$msgno" if $imap->see( $messageno );

This method sets the \Seen flag on the given message. On success it returns true, false on failure and the errstr() error handler is set with the error message. If the flag was already there, no error is produced.

unsee

  print "You've not seen message #$msgno" if $imap->unsee( $messageno );

This method removes the \Seen flag on the given message. On success it returns true, false on failure and the errstr() error handler is set with the error message. If the flag wasn't there, no error is produced.

add_flags

delete and see above really just call this function for those flags.

   $imap->add_flags( $msgno, qw(\Seen \Deleted) )
        or die $imap->errstr;

sub_flags

unsee above really just calls this function for that flag.

   $imap->sub_flags( $msgno, '\Seen' ) or die $imap->errstr;

mailboxes

  my @boxes   = $imap->mailboxes;
  my @folders = $imap->mailboxes("Mail/%");
  my @lists   = $imap->mailboxes("lists/perl/*", "/Mail/");

This method returns a list of mailboxes. When called with no arguments it recurses from the IMAP root to get all mailboxes. The first optional argument is a mailbox path and the second is the path reference. RFC 3501 section 6.3.8 has more information.

On failure nothing is returned and the errstr() error handler is set with the error message.

mailboxes_subscribed

  my @boxes   = $imap->mailboxes_subscribed;
  my @folders = $imap->mailboxes_subscribed("Mail/%");
  my @lists   = $imap->mailboxes_subscribed("lists/perl/*", "/Mail/");

This method returns a list of mailboxes subscribed to. When called with no arguments it recurses from the IMAP root to get all mailboxes. The first optional argument is a mailbox path and the second is the path reference. RFC 3501 has more information.

On failure nothing is returned and the errstr() error handler is set with the error message.

create_mailbox

  print "Created" if $imap->create_mailbox( "/Mail/lists/perl/advocacy" );

This method creates the mailbox named in the required argument. Returns true on success, false on failure and the errstr() error handler is set with the error message.

expunge_mailbox

  my @expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );
  die $imap->errstr if $imap->waserr;

  my $expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" )
      or die $imap->errstr;

This method removes all mail marked as deleted in the mailbox named in the required argument. Returns either the number of messages that were expunged, or the indexes of those messages -- which has a questionable usefulness since it tends to return numbers that don't relate to the message numbers marked with the \Deleted flags.

If 0 messages were expunged without error, the function will return 0E0 so it will still test true, but also evaluate to 0.

In list context, you must call waserr() to test for success.

delete_mailbox

  print "Deleted" if $imap->delete_mailbox( "/Mail/lists/perl/advocacy" );

This method deletes the mailbox named in the required argument. Returns true on success, false on failure and the errstr() error handler is set with the error message.

rename_mailbox

  print "Renamed" if $imap->rename_mailbox( $old => $new );

This method renames the mailbox in the first required argument to the mailbox named in the second required argument. Returns true on success, false on failure and the errstr() error handler is set with the error message.

folder_subscribe

  print "Subscribed" if $imap->folder_subscribe( "/Mail/lists/perl/advocacy" );

This method subscribes to the folder. Returns true on success, false on failure and the errstr() error handler is set with the error message.

folder_unsubscribe

  print "Unsubscribed" if $imap->folder_unsubscribe( "/Mail/lists/perl/advocacy" );

This method un-subscribes to the folder. Returns true on success, false on failure and the errstr() error handler is set with the error message.

copy

  print "copied" if $imap->copy( $message_number, $mailbox );

This method copies the message number (or "sequence set") in the currently selected mailbox to the fold specified in the second argument. Both arguments are required. On success this method returns true. Returns false on failure and the errstr() error handler is set with the error message.

errstr

 print "Login ERROR: " . $imap->errstr . "\n" if !$imap->login($user, $pass);

Return the last error string captured for the last operation which failed.

waserr

 my @flags = $imap->msg_flags(14);
 die $imap->errstr if $imap->waserr;

Because msg_flags() can optionally return a list, it's not really possible to detect failure in list context. Therefore, you must call waserr() if you wish to detect errors.

Few of the Net::IMAP::Simple methods use waserr(). The ones that do will mention it.

SEARCHING

search

This function returns an array of message numbers (in list context) or the number of matched messages (in scalar context). It takes a single argument: the search.

IMAP searching can be a little confusing and this function makes no attempt to parse your searches. If you wish to do searches by hand, please see RFC 3501.

Here are a few examples:

    my @ids = $imap->search("UNSEEN");
    my @ids = $imap->search('SUBJECT "blarg is \"blarg\""');
    my @ids = $imap->search('FROM "joe@aol.com"');
    my @ids = $imap->search("DELETED");

    # example from RFC 3501, search terms are ANDed together
    my @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"');

    # flagged and ( since x or !from y ):
    my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
      # no typo above, see the RFC

Since this module is meant to be simple, Net::IMAP::Simple has a few search helpers. If you need fancy booleans and things, you'll have to learn search. If you need a quick search for unseen messages, see below.

These all return an array of messages or count of messages exactly as the search function does. Some of them take arguments, some do not. They do try to grok your arguments slightly, the mechanics of this (if any) will be mentioned below.

search_seen: Returns numbers of messages that have the \Seen flag.
search_recent: Returns numbers of messages that have the \Recent flag.
search_answered: Returns numbers of messages that have the \Answered flag.
search_deleted: Returns numbers of messages that have the \Deleted flag.
search_flagged: Returns numbers of messages that have the \Flagged flag.
search_draft: Returns numbers of messages that have the \Draft flag.
search_unseen: Returns numbers of messages that do not have the \Seen flag.
search_old: Returns numbers of messages that do not have the \Recent flag.
search_unanswered: Returns numbers of messages that do not have the \Answered flag.
search_undeleted: Returns numbers of messages that do not have the \Deleted flag.
search_unflagged: Returns numbers of messages that do not have the \Flagged flag.
search_smaller: This function takes a single argument we'll call <x> and returns numbers of messages that are smaller than <x> octets. This function will try to force your argument to be a number before passing it to the IMAP server.
search_larger: This function takes a single argument we'll call <x> and returns numbers of messages that are larger than <x> octets. This function will try to force your argument to be a number before passing it to the IMAP server.
search_from: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the from header. This function will attempt to force your string into the RFC3501 quoted-string format.
search_to: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the to header. This function will attempt to force your string into the RFC3501 quoted-string format.
search_cc: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the cc header. This function will attempt to force your string into the RFC3501 quoted-string format.
search_bcc: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the bcc header. This function will attempt to force your string into the RFC3501 quoted-string format.
search_subject: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the subject header. This function will attempt to force your string into the RFC3501 quoted-string format.
search_body: This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the message body. This function will attempt to force your string into the RFC3501 quoted-string format.
search_before: This function takes a single argument we'll call <x> and returns numbers of messages that were received before <x>. If you have Date::Manip installed (optional), this function will attempt to force the date into the format %d-%m-%Y (date-month-year) as RFC3501 requires. If you do not have that module, no attempt will be made to coerce your date into the correct format.
search_since: This function takes a single argument we'll call <x> and returns numbers of messages that were received after <x>. If you have Date::Manip installed (optional), this function will attempt to force the date into the format %d-%m-%Y (date-month-year) as RFC3501 requires. If you do not have that module, no attempt will be made to coerce your date into the correct format.
search_sent_before: This function takes a single argument we'll call <x> and returns numbers of messages that have a header date before <x>. If you have Date::Manip installed (optional), this function will attempt to force the date into the format %d-%m-%Y (date-month-year) as RFC3501 requires. If you do not have that module, no attempt will be made to coerce your date into the correct format.
search_sent_since: This function takes a single argument we'll call <x> and returns numbers of messages that have a header date after <x>. If you have Date::Manip installed (optional), this function will attempt to force the date into the format %d-%m-%Y (date-month-year) as RFC3501 requires. If you do not have that module, no attempt will be made to coerce your date into the correct format.

OTHER NOTES

sequence set

Message numbers are never checked before being passed to the IMAP server (this is a "simple" module after all), so in most places where a message number is required, you can instead use so-called sequence sets. Examples:

    $imap->copy(   "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
    $imap->delete( "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;

AUTHOR

Creator: Joao Fonseca <joao_g_fonseca@yahoo.com>
2004 maintainer: Casey West <casey@geeknst.com>
2005 maintainer: Colin Faber <cfaber@fpsn.net>
2009 maintainer: Paul Miller <jettero@cpan.org>

COPYRIGHT

BUGS

There's tons, I'm trying to slog through them:

https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)