=head1 NAME

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

=head1 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;

=head1 DESCRIPTION

This module is a simple way to access IMAP accounts.

=head1 OBJECT CREATION METHOD

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

    # OR

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

=head2 new

This class method constructs a new C<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
(C<:>), C<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():

=over 4

=item port => int

Assign the port number (default: 143)

=item timeout => int (default: 90)

Connection timeout in seconds.

=item retry => int (default: 1)

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

=item retry_delay => int (default: 5)

Wait (x) seconds before retrying a connection attempt

=item use_v6 => BOOL

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

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

=item bindaddr => str

Assign a local address to bind

=item use_select_cache => BOOL

Enable select() caching internally

=item select_cache_ttl => int

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

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

=back

=head1 METHODS

=over 4

=item 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 C<require> L<IO::Socket::SSL>
and L<Net::SSLeay> at runtime.

=item 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.

=item 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.

=item messages

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

This method is an alias for $imap->select

=item 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 $imap->select'ed will be used.

This method uses caching.

=item 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.

=item unseen

    print "Unseen messages value: " . $imap->unseen . "\n";

This method accepts an optional folder name and returns the 'UNSEEN' 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.

=item current_box

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

This method returns the current working mail box folder name.

=item 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.

=item seen

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

A message number is the only required parameter for this method. The message's
C<\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.

=item 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.

=item 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.

=item 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.

=item 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";

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=item errstr

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

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

=back

=head1 AUTHOR

=over 4

=item Creator

Joao Fonseca C<< <joao_g_fonseca@yahoo.com> >>

=item 2004 maintainer

Casey West C<< <casey@geeknst.com> >>

=item 2005 maintainer

Colin Faber C<< <cfaber@fpsn.net> >>

=item 2009 maintainer

Paul Miller C<< <jettero@cpan.org> >>

=back

=head1 COPYRIGHT

Copyright (c) 2009 Paul Miller
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.

=head1 SEE ALSO

L<perl>, L<Net::IMAP>

