<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
    "http://www.w3.org/TR/html4/strict.dtd">
<html>

<head>
<title>LuaSocket: Network support for the Lua language</title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>

<body>

<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<div class=header>
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org">
<img border=0 alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language
</td></tr>
</table>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a> 
</p>
</center>
<hr>
</div>

<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h2 id=smtp>SMTP</h2> 

<p>
The  module  <tt>smtp.lua</tt>  provides functionality  to  send  e-mail
messages. The implementation conforms to the Simple Mail Transfer Protocol,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
The other RFC of interest in this implementation is 
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
which governs the Internet Message Format.

</p>

<p>
MIME headers are represented as a Lua table in the form:
</p>

<blockquote>
<table summary="MIME headers in Lua table">
<tr><td><tt>
headers = {<br>
&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
</tt></td></tr>
<tr><td align=center><tt>
&nbsp;&nbsp;...
</tt></td></tr>
<tr><td><tt>
&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
}
</tt></td></tr>
</table>
</blockquote>

<p>
Field names are case insensitive (as  specified by the standard) and all
functions  work with  lowercase field names.  
Field values are left unmodified.
</p>

<p class=note>
Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table. 
</p>

<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=mail> 
socket.smtp.<b>mail{</b><br>
&nbsp;&nbsp;from = <i>string</i>,<br>
&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
&nbsp;&nbsp;body = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
&nbsp;&nbsp;server = <i>string</i><br>
<b>}</b>
</p>

<p class=description>
Sends a message to a recipient list.
</p>

<p class=parameters>
<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
in case there is just one recipient. 
The sender is given by the e-mail address <tt>from</tt>. 
The message is composed by the optional MIME Headers <tt>headers</tt> 
and text <tt>body</tt>. The message is  sent using  the server  
<tt>server</tt>. 
</p>

<p class=return> 
If  successful, the function returns 1. Otherwise, the function returns
<tt>nil</tt> followed by an error message.
</p>

<p class=note>
Big note: There is a good deal of misconception with the use of the
destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
'<tt>Bcc</tt>' header to your messages because it will probably do the
exact opposite of what you expect.
</p>

<p class=note>
Only recipients specified in the recipient list will receive a copy of the
message.  Each recipient of an SMTP mail message receives a copy of the
message body along with the headers, and nothing more.  The headers are
considered as part of the message. The list of recipients is <em>not</em>
part of the message.  
</p>

<p class=note>
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
has two <em>important and short</em> sections, "3.6.3. Destination address
fields" and "5. Security considerations",  explaining the proper
use of these headers. Here is a summary of what it says: 
</p>

<ul>
<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
of the message;
<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
making a copy on a typewriter using carbon paper) contains the
addresses of others who are to receive the message, though the
content of the message may not be directed at them;
<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
</ul> 

<p class=note>
The LuaSocket <tt>mail</tt> function does not interpret the headers you 
pass to, but it gives you full control over what is sent and to whom 
it is sent:
</p>
<ul>
<li> If someone is to receive the message, the e-mail address <em>has</em>
to be in the recipient list. This is the only parameter that controls who
gets a copy of the message;
<li> If there are multiple recipients, none of them will automatically 
know that someone else got that message. That is, the default behavior is
similar to the <tt>Bcc</tt> field of popular e-mail clients; 
<li> It is up to you to add the <tt>To</tt> header with the list of primary
recipients so that other recipients can see it;
<li> It is also up to you to add the <tt>Cc</tt> header with the 
list of additional recipients so that everyone else sees it;
<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is 
empty. Otherwise, everyone receiving the message will see it and that is
exactly what you <em>don't</em> want to happen!
</ul>

<p class=note>
I hope this clarifies the issue. Otherwise, please refer to 
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
and
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
</p>

<pre class=example>
-- Connects to server "localhost" and sends a message to users
-- "fulano@tecgraf.puc-rio.br",  "beltrano@tecgraf.puc-rio.br", 
-- and "sicrano@tecgraf.puc-rio.br".
-- Note that "fulano" is the primary recipient, "beltrano" receives a
-- carbon copy and neither of them knows that "sicrano" received a blind
-- carbon copy of the message.
headers = {
  to = "fulano@tecgraf.puc-rio.br",
  cc = "beltrano@tecgraf.puc-rio.br",
  subject = "LuaSocket test message"
}

from = "luasocket@tecgraf.puc-rio.br"

rcpt = {
  "fulano@tecgraf.puc-rio.br",
  "beltrano@tecgraf.puc-rio.br",
  "sicrano@tecgraf.puc-rio.br"
}

body = "This is a test message. Please ignore."

server = "localhost"

r, e = socket.smtp.mail{
  from = from,
  rcpt = rcpt, 
  headers = headers, 
  body = body, 
  server = server
}
</pre>

<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>

</body>
</html>