modulereview
nite_man
<h3>Name</h3>
<p>Net::IMAP::Simple</p>
<h3>Author</h3>
<p>Joao Fonseca</a>
<h3>Version</h3>
<p>0.93</p>
<h3>Description</h3>
<p>
Perl extension for simple IMAP account handling. This module leaves a possibility
to create, delete or rename IMAP mailboxes, read, copy, delete mail messages.
</p>
<h3>Methods</h3>
<dl>
<dt><i>new(host, opt_par1 => val1, opt_par2 => var2, ...)</i></dt>
<dd>
Method <code>new</code> create a new object <code> Net::IMAP::Simple </code>
Parameter <code>host</code> defines a IMAP host name, another parameters are optional and pass to <code>
IO::Socket::INET</code> directly. Usually, it uses parameter <code>Timeout</code> but you can see other parameters in <code>IO::Socket::INET</code> <a
href='http://search.cpan.org/author/JHI/perl-5.8.0/ext/IO/lib/IO/Socket/INET.pm#CONSTRUCTOR'>
documentation</a><br>
The method <code>new</code> returns an object which connected
to the IMAP server in successful case or it returns
<code>undef</code> and stores an error code into variable <code>$!</code>:
<pre>
my $imap = Net::IMAP::Simple->new($my_host, Timeout => 30) or die "Can't connect to $my_host: $!";
</pre>
</dd>
<dt><i>login(user_name, user_passw)</i></dt>
<dd>
This method tries to login on IMAP server using a pair <code> user_name</code> and <code>user_passw</code>. This method returns
a number of messages in the default user's mail box (usually this is INBOX)
or <code>undef</code> (at that, you can use a hash for
defining of <code>user_name</code> and <code>user_passw</code>):
<pre>
defined (my $num_msgs = $imap->login($my_name => $my_passw)) or die "Can't login!";
</pre>
</dd>
<dt><i>mailboxes()</i></dt>
<dd>
This method returns a list of all user's mailboxes:
<pre>
my $mailbox_list = $imap->mailboxes;
</pre>
</dd>
<dt><i>select(mailbox_name)</i></dt>
<dd>
This method selects a mailbox according to <code>mailbox_name</code>
and return a number of messages which consist in this mailbox
(if mailbox is empty the method <code>select</code> returns 0)
or <code>undef</code> if mailbox doesn't exist:
<pre>
defined(my $num_msgs = $imap->select($mailbox)) or die "Mailbox $mailbox is invalid!";
</pre>
</dd>
<dt><i>get(message_number)</i></dt>
<dd>
Method <code>get</code> returns a reference on array which
consists lines of message with number <code>message_number</code>:
<pre>
print "Message No 10:\n";
map { print $_ ."\n" } @{ $imap->get(10) };
</pre>
</dd>
<dt><i>getfh(message_number)</i></dt>
<dd>
This method returns the lines of defined message alike previous
method but stores result into temporary file. This means
that the message transfers early on user's computer and
then you can read it from file:
<pre>
my $fh = $imap->getfh(10);
print "Message No 10:\n";
print <$fh>;
close $fh;
</pre>
</dd>
<dt><i>delete(message_number)</i></dt>
<dd>
This method marks a defined message as delete but, in fact,
this message will be delete when method <code>quite</code> will
be called. <code>Net::IMAP::Simple</code> doesn't leave to
possibility of undelete of message which were marked as delete:
<pre>
$imap->delete(10);
</pre>
</dd>
<dt><i>top(message_number)</i></dt>
<dd>
Method <code>top</code> returns a header of defined message as
an array reference:
<pre>
my $header = $imap->top(10);
my $head_obj = Mail::Header->new($header);
my $subj = $head_obj->get('Subject');
my $from = $head_obj->get('From');
</pre>
</dd>
<dt><i>list()</i></dt>
<dd>
If this method is called without a parameter, it returns
size for all messages in the mailbox as hash reference where
key is message ID and value is message size:
<pre>
my $all_sizes = $imap->list;
map { print "Message No $_: $$all_sizes{$_} bytes!\n" } keys %$all_sizes;
or
my $msg_size = $imap->list(10);
print "Message No 10: $msg_size bytes!\n";
</pre>
</dd>
<dt><i>seen(message_number)</i></dt>
<dd>
This method returns 'true' if defined message was read and
'false' if not. You can use method <code>seen</code> for
determination of list of new messages in your mailbox:
<pre>
for(1 .. $num_msgs) { push @new_msgs, $_ unless $imap->seen($_);
print "You have ".scalar @new_msgs." in your mailbox!\n";
</pre>
</dd>
<dt><i>quit()</i></dt>
<dd>
Method <code>quit</code> deletes all marked messages and close
a connection with IMAP server:
<pre>
$imap->quit;
</pre>
</dd>
</dl>
<h3>Others methods</h3>
<p>
You can manipulate a mailbox by using following methods:
<ul>
<li><code>$res = $imap->create_mailbox(mailbox_name);</code></li>
<li><code>$res = $imap->delete_mailbox(mailbox_name);</code></li>
<li><code>$res = $imap->rename_mailbox(old_mailbox_name, new_mailbox_name);</code></li>
</ul>
which create, delete and rename defined mailbox accordingly. Those methods
return 'true' in success case or 'false'.<br>
For copy message from one mailbox to another you can use method <code>copy</code>:
<code>
$res = $imap->copy(message_number, mailbox_name);
</code>
This method returns 'true' in success case or 'false'.
</p>
<h3>Resume</h3>
<p>
This module will be useful in case of creation a mail checker or simple
mail interface to IMAP server. In more complex case preferably use more
power modules
<ul><li>
<a
href='http://search.cpan.org/author/KJOHNSON/NetxAP-0.02/Net/IMAP.pm'>Net::IMAP</a>
leaves larger set of methods for intercept and interpretation of server
responses, management of mailboxes and messages etc.
</li>
<li>
<a
href='http://search.cpan.org/author/DJKERNEN/Mail-IMAPClient-2.2.7/IMAPClient.pod'>Mail::IMAPClient</a>
leaves most full interface to the IMAP server but you should be ready to
interpret some responses of server by yourself using
<a href='http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2060.html'>RFC 2060</a>.
</li>
</p>
A simple Perl interface to the IMAP server.
This review describes methods of module Net::IMAP::Simple.