ch16_01.htm

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

<p>When a client negotiates an SMTP session with a server, the server
tells the client that it's listening. Once
you're connected, you introduce yourself to the
server by issuing a HELO <a name="INDEX-2007" /></a>command. The HELO command accepts one
parameter&#x2014;your hostname&#x2014;and defaults to your remote
hostname if you don't specify one. If the command is
successful, the server sends a 250 response, as follows:
</p>

<blockquote><pre class="code">HELO
250 mail.somename.com Hello some-remote-host.com [127.0.0.1], pleased to meet 
you</pre></blockquote>

<p><a name="INDEX-2008" /></a>After
you've been greeted by the server, send the MAIL
command to tell the server who the message is from. The MAIL command
takes the string <tt class="literal">From:</tt>
<tt class="literal">user@hostname</tt> as an argument, and the server
responds with a 250 message to indicate success:
</p>

<blockquote><pre class="code">MAIL From: &lt;[e-mail]&gt;
250 [e-mail] ... Sender ok</pre></blockquote>

<p><a name="INDEX-2009" /></a>Then
send the RCPT command to tell the server who the recipient is:
</p>

<blockquote><pre class="code">RCPT To: &lt;[e-mail]&gt;
250 [e-mail] ... Recipient ok</pre></blockquote>

<p><a name="INDEX-2010" /></a>Now
you're ready to send the body of your message to the
server. The DATA command tells the server that all data until a . on
a line by itself should be treated as the body of the mail message:
</p>

<blockquote><pre class="code">DATA
354 Enter mail, end with "." on a line by itself
Subject: Hi, just thought you'd be interested ...

Hi, this is the text of my mail message that I'm going to 
send with Net::SMTP to show you how it works.
.
250 VAA09505 Message accepted for delivery</pre></blockquote>

<p>Once again, you get a 250 response, indicating that the message has
been accepted for delivery. At that point, you can exit the SMTP
<a name="INDEX-2011" /></a>session
with the QUIT command, which returns 221 on success:
</p>

<blockquote><pre class="code">QUIT
221 mail.somename.com closing connection
Connection closed by foreign host.</pre></blockquote>

<a name="perlnut2-CHP-16-SECT-1.2.1" /></a><div class="sect3">
<h3 class="sect3">16.1.2.1. Net::SMTP methods</h3>

<p>The following methods are defined by Net:SMTP.</p>

<a name="INDEX-2012" /></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">smtp</em> = Net::SMTP-&gt;new(<em class="replaceable">host</em>[, <em class="replaceable">options</em>])
</pre><p><a name="INDEX-2012" /></a>Constructor. Takes the hostname of the
remote mail server, <em class="replaceable"><tt>host</tt></em>, and possibly
some options, and creates a new SMTP object. Any options are passed
to <tt class="literal">new</tt> as a hash, in which the option is the key.
The possible options are:
</p><dl>
<dt><b><tt class="literal">Debug</tt></b></dt>
<dd>
Enables debug mode if set to <tt class="literal">1</tt>. Provides
information about your connection, requests, and responses.
<p></p>
</dd>


<dt><b><tt class="literal">Hello</tt></b></dt>
<dd>
Sends a HELO command to the SMTP server. Takes a string that
represents your domain; if not specified, <tt class="literal">Hello</tt>
guesses your domain.
<p></p>
</dd>


<dt><b><tt class="literal">Timeout</tt></b></dt>
<dd>
Time (in seconds) after which the client stops trying to establish a
connection with the SMTP server. Defaults to 120 seconds. If the
connection cannot be established, the constructor returns
<tt class="literal">undef</tt>.
<p></p>
</dd>

</dl></div>

<a name="INDEX-2013" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>banner</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">smtp</em>-&gt;data([<em class="replaceable">banner</em>])
</pre><p><a name="INDEX-2013" /></a>Returns the banner message with
which the server replied when the initial connection was made. For
example:
</p><blockquote><pre class="code">my $banner = $smtp-&gt;banner( );
print "$banner\n";</pre></blockquote></div>

<a name="INDEX-2014" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>data</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">smtp</em>-&gt;data([<em class="replaceable">bodydata</em>])
</pre><p><a name="INDEX-2014" /></a>Starts sending the body of the
current message to the server. If specified,
<em class="replaceable"><tt>bodydata</tt></em> can be a list or a reference to a
list; the contents of the list and the termination string
<tt class="literal">.\r\n</tt> are sent to the server. Returns true if
accepted.
</p><p>If <em class="replaceable"><tt>bodydata</tt></em> is not specified, then a true
result means that the server is ready to receive data, which must be
sent with the <tt class="literal">datasend</tt> and
<tt class="literal">dataend</tt> methods (inherited from Net::Cmd).
</p></div>

<a name="INDEX-2015" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>dataend</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">smtp</em>-&gt;dataend(  )
</pre><p><a name="INDEX-2015" /></a>Net::Cmd method issued after
<tt class="literal">datasend</tt> to end the sending of data. Sends
<tt class="literal">.\r\n</tt> to the server telling it that
there's no more data coming and that it should send
the message.
</p><p>Here's an example that uses
<tt class="literal">datasend</tt> and <tt class="literal">dataend</tt>:
</p><blockquote><pre class="code">@list_data = (1..10);
$smtp-&gt;data( );
$smtp-&gt;datasend(@list_data);
$smtp-&gt;dataend( );</pre></blockquote></div>

<a name="INDEX-2016" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>datasend</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">smtp</em>-&gt;datasend("<em class="replaceable">data</em>")
</pre><p><a name="INDEX-2016" /></a>Net::Cmd method that sends the
body of the message to the remote server if the body
wasn't specified with the <tt class="literal">data</tt>
method.
</p></div>

<a name="INDEX-2017" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>domain</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">smtp</em>-&gt;domain(  )
</pre><p><a name="INDEX-2017" /></a>Returns the domain of the remote
SMTP server, or <tt class="literal">undef</tt>.
</p></div>

<a name="INDEX-2018" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>expand</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">smtp</em>-&gt;expand(<em class="replaceable">address</em>)
</pre><p><a name="INDEX-2018" /></a>Requests the server to expand
<em class="replaceable"><tt>address</tt></em>. Returns an array containing the
text from the server.
</p></div>

<a name="INDEX-2019" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>hello</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">smtp</em>-&gt;hello(<em class="replaceable">domain</em>)
</pre><p><a name="INDEX-2019" /></a>Identifies your domain to the mail
server. Executes automatically when you create a Net::SMTP object, so
you shouldn't have to do it manually.
</p></div>

<a name="INDEX-2020" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>help</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">help_text</em> = $<em class="replaceable">smtp</em>-&gt;help([<em class="replaceable">subject</em>])
</pre><p><a name="INDEX-2020" /></a>Returns help text from the server,
or <tt class="literal">undef</tt> on failure. If
<em class="replaceable"><tt>subject</tt></em> is specified, returns help for
that topic.
</p></div>

<a name="INDEX-2021" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>mail</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" true align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">smtp</em>-&gt;mail(<em class="replaceable">address</em>[, <em class="replaceable">options</em>])
$<em class="replaceable">smtp</em>-&gt;send(<em class="replaceable">address</em>)
send_or_mail(<em class="replaceable"><tt>address</tt></em>)
send_and_mail(<em class="replaceable"><tt>address</tt></em>)
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-2021" /></a>Takes the
sender's address and sends the appropriate command
(MAIL, SEND, SOML, or SAML) to the server to initiate the
message-sending process.
</p><p><tt class="literal">mail</tt> can take some ESMTP options, passed as
key/value pairs. See the Net::SMTP documentation for the details.
</p></div>

<a name="INDEX-2022" /></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">smtp</em>-&gt;quit
</pre><p><a name="INDEX-2022" /></a>This method sends the QUIT command to
the remote SMTP server and closes the socket connection.
</p></div>

<a name="INDEX-2023" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>recipient</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">smtp</em>-&gt;recipient(<em class="replaceable">addr</em>[, <em class="replaceable">addr</em>[, ...]])
</pre><p><a name="INDEX-2023" /></a>Tells the server to send the
current message to all specified recipients. As defined in the RFC,
each address is sent as a separate command to the server. If the
sending of any address fails, the process aborts and returns false;
you can then call <tt class="literal">reset</tt> to reset the server.
</p></div>

<a name="INDEX-2024" /></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>
$<em class="replaceable">smtp</em>-&gt;reset(  )
</pre><p><a name="INDEX-2024" /></a>Resets the server's
status. Useful for canceling a message after it has been initiated
but before any data has been sent.
</p></div>

<a name="INDEX-2025" /></a><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>to</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">smtp</em>-&gt;to(<em class="replaceable">address</em>[, <em class="replaceable">address</em>[, ...]])
</pre><p><a name="INDEX-2025" /></a>Interchangeable with
<tt class="literal">recipient</tt>.
</p></div>

<a name="INDEX-2026" /></a><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><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>verify</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">smtp</em>-&gt;verify(<em class="replaceable">address</em>)
</pre><p><a name="INDEX-2026" /></a>Verifies that the specified mail
address is valid. However, many servers ignore