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 toSTDOUT
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. - 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 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.
- 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.
- unseen
-
print "Unseen messages value: " . $imap->unseen . "\n";
This method accepts an optional folder name and returns the 'UNSEEN' value provided darning a SELECT result set. If no folder name is provided the last folder
$imap->select
'ed will be used.This method uses caching.
NOTE: The UNSEEN value varies from server to server, but according to the IMAP specification, it should be the number of the first unseen message, in the case the flag is provided. (If the flag is not provided, users would have to use the SEARCH command to find it -- not implemented.)
- 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
\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 theerrstr()
error handler is set with the error message. - deleted
-
print "Deleted!" if $imap->deleted( $message_number );
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. 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. - 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";
- 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 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. On success it returns true, false on failure and theerrstr()
error handler is set with the error message. If the flag was already there, no error is produced. - 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 theerrstr()
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 theerrstr()
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 theerrstr()
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
-
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 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 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.
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
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.
BUGS
There's tons, I'm trying to slog through them:
https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple
SEE ALSO
perl, Net::IMAP, Net::IMAP::Server, IO::Socket::SSL, IO::Socket::INET6