Simple(3) User Contributed Perl Documentation Simple(3)NAMENet::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.
close
$imap->close;
Un-selects the current mailbox, leaving no mailbox selected.
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
unseen
print "Unseen messages value: " . $imap->unseen . "\n";
This method accepts an optional folder name and returns the
'UNSEEN' value provided duringg a SELECT command result. If no
folder name is provided the last folder "$imap->select"'ed will be
used. If a folder name is provided, this will issue a SELECT
first.
This method uses caching.
NOTE: This is not the opposite of seen below. 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.)
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.
noop
$imap->noop;
Performs a null operation. This may be needed to get updates on a
mailbox, or ensure that the server does not close the connection as
idle. RFC 3501 states that servers' idle timeouts must not be less
than 30 minutes.
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.
IMAP sorting (see RFC 5256) is supported via an optional second
argument. The RFC requires the charset be specified, which can be
provided via the optional third argument (defaults to UTF-8).
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"');
# example from RFC 3501, search terms are ORed together
my @ids = $imap->search('OR BODY "blard" SUBJECT "blarg"');
# flagged and ( since x or !from y ):
my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
# no typo above, see the RFC
# example from RFC 5256, sorted by subject and reverse date
my @ids = $imap->search('BODY "zaphod"', 'SUBJECT REVERSE DATE');
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
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
<https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>
SEE ALSO
perl, Net::IMAP::Server, IO::Socket::SSL, IO::Socket::INET6
perl v5.14.1 2010-06-07 Simple(3)
