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

    # Duh
    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(6);
    }

    # 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;

This module is a simple way to access IMAP accounts.

new

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

This class method constructs a new CWNet::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 (CW:), CWexample.com:5143. On success an object is returned. On failure, nothing is returned and an error message is set to CW$Net::IMAP::Simple. OPTIONS:

 port           => Assign the port number (default: 143)

 timeout        => Connection timeout in seconds.

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

 retry_delay    => Wait (x) seconds before retrying a
                -> connection attempt

 use_v6         => If set to true, attempt to use IPv6
                -> sockets rather than IPv4 sockets.
                -> This option requires the
                -> IO::Socket::INET6 module

 bindaddr       => Assign a local address to bind

 use_select_cache => Enable select() caching internally

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

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.

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.

messages

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

This method is an alias for CW$imap->select

flags

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

This method accepts an optional folder name and returns the current avaliable server flags as a list, for the selected folder. If no folder name is provided the last folder CW$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 CW$imap->select'ed will be used. This method uses caching.

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

  print "Seen it!" if $imap->seen( $message_number );

A message number is the only required parameter for this method. The message's CW\Seen flag will be examined and if the message has been seen a true value is returned. All other failures return a false value and the errstr() error handler is set with the error message.

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 );
  print for @{$message};

This method fetches a message and returns its lines in a list reference. On failure, nothing is returned and the errstr() error handler is set with the error message.

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 preformed 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 retuns 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 deletes a message from the selected mailbox. On success it returns true. False on failure and the errstr() error handler is set with the error message.

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 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

  print "Expunged" if $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );

This method removes all mail marked as deleted in 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.

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 unsubscribes 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 in the currently seleted 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.

Colin Faber, <cfaber@fpsn.net>.

Casey West, <casey@geeknst.com>.

Joao Fonseca, <joao_g_fonseca@yahoo.com>.

Net::IMAP, perl, Changes

Copyright (c) 2005 Colin Faber. Copyright (c) 2004 Casey West. Copyright (c) 1999 Joao Fonseca.

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.