ch16_01.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<tt class="literal">verify</tt>, so it frequently doesn't
work.<a name="INDEX-2027" /></a><a name="INDEX-2028" /></a><a name="INDEX-2029" /></a><a name="INDEX-2030" /></a><a name="INDEX-2031" /></a> 
</p></div>
</div>
</div>
<a name="perlnut2-CHP-16-SECT-1.3" /></a><div class="sect2">
<h3 class="sect2">16.1.3. Retrieving Email with Net::POP3</h3>

<p><a name="INDEX-2032" /></a><a name="INDEX-2033" /></a><a name="INDEX-2034" /></a><a name="INDEX-2035" /></a><a name="INDEX-2036" /></a>You can use SMTP to send mail, but not
to retrieve it. For retrieving messages, use the Post Office Protocol
Version 3 (POP3), described in RFC 1081. One way to do this is to use
the Net::POP3 module. POP3 provides commands for interacting with the
POP server, typically bound to port 110. Net::POP3 automates the
transfer of email from a remote server to the local machine.
</p>

<p>The POP server retrieves messages from a specified spooling directory
on the remote system. The messages are stored in a file named for the
username<a name="INDEX-2037" /></a><a name="INDEX-2038" /></a><a name="INDEX-2039" /></a>; anonymous logins are not permitted.
Authentication is based on username and password and is done by
sending the USER and PASS commands to the POP server. For example,
identification of user <tt class="literal">foo</tt> with password
<tt class="literal">bar</tt> looks like this:
</p>

<blockquote><pre class="code">USER foo
PASS bar</pre></blockquote>

<p><a name="INDEX-2040" /></a><a name="INDEX-2041" /></a><a name="INDEX-2042" /></a>Net::POP3 has <tt class="literal">user</tt>
and <tt class="literal">pass</tt> methods but may also authenticate users
with <tt class="literal">login</tt>, which takes both username and password
arguments. If authentication fails, the user cannot retrieve, delete,
or alter any messages from the mail server. <tt class="literal">login</tt>
returns the number of messages on the POP server for the user, or
<tt class="literal">undef</tt> if authentication fails.
</p>

<p>Authenticated users can retrieve information about their mailboxes
and can get specific messages by message number.
</p>

<p>A POP session to retrieve a mail message is negotiated with the
server through the following steps:
</p>

<ol><li>
<p>Connect to the POP server (the default port is 110).</p>
</li><li>
<p>Send USER command.</p>
</li><li>
<p>Send PASS command.</p>
</li><li>
<p>If authenticated, receive number of messages.</p>
</li><li>
<p>Send RETR &lt;<em class="emphasis">message number</em>&gt; command to
retrieve a specific message.
</p>
</li><li>
<p>Send QUIT command to end session.</p>
</li></ol>
<p>The following methods are defined by Net:POP3.</p>



<a name="INDEX-2043" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>new</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em> = Net::POP3-&gt;new([<em class="replaceable">host</em>,] [<em class="replaceable">options</em>])
</pre><p><a name="INDEX-2043" /></a>Constructor. Creates a new Net::POP3
object. <em class="replaceable"><tt>host</tt></em> is the name of the remote
host to which a POP3 connection will be made. If
<em class="replaceable"><tt>host</tt></em> is not specified, then the POP3_Host
specified in Net::Config is used.
</p><p><em class="replaceable"><tt>options</tt></em> are passed as key/value pairs, in
which the option is the key. The possible options are:
</p><dl>
<dt><b><tt class="literal">ResvPort</tt></b></dt>
<dd>
Optional. If given, then the socket for the Net::POP3 object will be
bound to the given local port using <tt class="literal">bind</tt> when the
socket is created.
<p></p>
</dd>


<dt><b><tt class="literal">Debug</tt></b></dt>
<dd>
Enables debugging information<p></p>
</dd>


<dt><b><tt class="literal">Timeout</tt></b></dt>
<dd>
Maximum time, in seconds, to wait for a response from the POP3
server. Default is 120 seconds.
<p></p>
</dd>

</dl></div>

<a name="INDEX-2044" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>apop</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;apop(<em class="replaceable">user</em>, <em class="replaceable">pass</em>)
</pre><p><a name="INDEX-2044" /></a>Authenticates
<em class="replaceable"><tt>user</tt></em> with password
<em class="replaceable"><tt>pass</tt></em> with the server. The password is not
sent in clear text. Requires the MD5 package; otherwise, returns
<tt class="literal">undef</tt>.
</p></div>

<a name="INDEX-2045" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;delete(<em class="replaceable">msgnum</em>)
</pre><p><a name="INDEX-2045" /></a>Marks message
<em class="replaceable"><tt>msgnum</tt></em> for deletion from the remote
mailbox. All messages marked for deletion are removed when the
connection to the server is closed.
</p></div>

<a name="INDEX-2046" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;get(<em class="replaceable">msgnum</em>)
</pre><p><a name="INDEX-2046" /></a>Gets message
<em class="replaceable"><tt>msgnum</tt></em> from remote mailbox. Returns a
reference to an array containing lines of text read from the server.
</p></div>

<a name="INDEX-2047" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>last</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;last(  )
</pre><p><a name="INDEX-2047" /></a>Returns the highest message number.
</p></div>

<a name="INDEX-2048" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>list</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;list([<em class="replaceable">msgnum</em>])
</pre><p><a name="INDEX-2048" /></a>If called with an argument, returns the
size of message <em class="replaceable"><tt>msgnum</tt></em>. If called without
an argument, returns a hash reference, in which the keys are the
message numbers of all undeleted messages, and each corresponding
value is the size of the message.
</p></div>

<a name="INDEX-2049" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>login</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;login([<em class="replaceable">user</em>[, <em class="replaceable">pass</em>]])
</pre><p><a name="INDEX-2049" /></a>Sends both USER and PASS commands. If
the password, <em class="replaceable"><tt>pass</tt></em>, is not given, then
Net::Netrc is used to look up the password based on the host and the
username, <em class="replaceable"><tt>user</tt></em>. If
<em class="replaceable"><tt>user</tt></em> is not specified, the current
username is used. Returns the count of messages in the mailbox, or
<tt class="literal">undef</tt> if the server can't
authenticate the user.
</p></div>

<a name="INDEX-2050" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>pass</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;pass(<em class="replaceable">pass</em>)
</pre><p><a name="INDEX-2050" /></a>Sends the PASS command with the
password. Returns the number of messages in the mailbox.
</p></div>

<a name="INDEX-2051" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>popstat</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;popstat(  )
</pre><p><a name="INDEX-2051" /></a>Returns a list with two elements:
the number of undeleted elements and the size of the mailbox.
</p></div>

<a name="INDEX-2052" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>quit</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;quit(  )
</pre><p><a name="INDEX-2052" /></a>Quits, closing the connection to the
remote POP3 server and deleting all messages marked for deletion.
</p><p>Note that if a Net::POP3 object goes out of scope before
<tt class="literal">quit</tt> has been called, <tt class="literal">reset</tt> is
called before the connection is closed, and any messages marked for
deletion are not deleted.
</p></div>

<a name="INDEX-2053" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>reset</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$pop-&gt;reset(  )
</pre><p><a name="INDEX-2053" /></a>Resets status of the remote POP3
server. Clears the delete status on all messages that were marked for
deletion.
</p></div>

<a name="INDEX-2054" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>top</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;top(<em class="replaceable">msgnum</em>[, <em class="replaceable">numlines</em>])
</pre><p><a name="INDEX-2054" /></a>Gets the header and the first
<em class="replaceable"><tt>numlines</tt></em> lines of body for message
<em class="replaceable"><tt>msgnum</tt></em>. Returns a reference to an array
containing lines of text read from the server.
</p></div>

<a name="INDEX-2055" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>uidl</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;uidl([<em class="replaceable">msgnum</em>])
</pre><p><a name="INDEX-2055" /></a>Returns a unique identifier for
<em class="replaceable"><tt>msgnum</tt></em> if specified. If
<em class="replaceable"><tt>msgnum</tt></em> is not specified, returns a
reference to a hash in which the keys are the message numbers, and
the values are the unique identifiers.
</p></div>

<a name="INDEX-2056" /></a><a name="INDEX-2057" /></a><a name="INDEX-2058" /></a><a name="INDEX-2059" /></a><a name="INDEX-2060" /></a><a name="INDEX-2061" /></a><a name="INDEX-2062" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>user</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><pre>
$<em class="replaceable">pop</em>-&gt;user(<em class="replaceable">user</em>)
</pre><p><a name="INDEX-2056" /></a>Sends the USER command, identifying the
user.<a name="INDEX-2057" /></a><a name="INDEX-2058" /></a><a name="INDEX-2059" /></a><a name="INDEX-2060" /></a><a name="INDEX-2061" /></a><a name="INDEX-2062" /></a>
</p></div></div>
</div>

<hr width="684" align="left" />
<div class="navbar"><table width="684" border="0"><tr><td align="left" valign="top" width="228"><a href="ch15_02.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0" /></a></td><td align="center" valign="top" width="228"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0" /></a></td><td align="right" valign="top" width="228"><a href="ch16_02.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0" /></a></td></tr><tr><td align="left" valign="top" width="228">15.2. The IO::Socket Module</td><td align="center" valign="top" width="228"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0" /></a></td><td align="right" valign="top" width="228">16.2. The Mail Modules</td></tr></table></div>
<hr width="684" align="left" />

<img src="../gifs/navbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links" />
<p><p><font size="-1"><a href="copyrght.htm">Copyright &copy; 2002</a> O'Reilly &amp; Associates. All rights reserved.</font></p>

<map name="library-map">
<area shape="rect" coords="1,0,85,94" href="../index.htm"><area shape="rect" coords="86,1,178,103" href="../lwp/index.htm"><area shape="rect" coords="180,0,265,103" href="../lperl/index.htm"><area shape="rect" coords="267,0,353,105" href="../perlnut/index.htm"><area shape="rect" coords="354,1,446,115" href="../prog/index.htm"><area shape="rect" coords="448,0,526,132" href="../tk/index.htm"><area shape="rect" coords="528,1,615,119" href="../cookbook/index.htm"><area shape="rect" coords="617,0,690,135" href="../pxml/index.htm">
      </map>

</body></html>