mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-19 19:58:20 +01:00
229 lines
6.9 KiB
HTML
229 lines
6.9 KiB
HTML
|
<!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> ·
|
||
|
|
<a href="home.html#download">download</a> ·
|
||
|
|
<a href="introduction.html">introduction</a> ·
|
||
|
|
<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>
|
||
|
|
field-1-name = <i>field-1-value</i>,<br>
|
||
|
|
field-2-name = <i>field-2-value</i>,<br>
|
||
|
|
field-3-name = <i>field-3-value</i>,
|
||
|
|
</tt></td></tr>
|
||
|
|
<tr><td align=center><tt>
|
||
|
|
...
|
||
|
|
</tt></td></tr>
|
||
|
|
<tr><td><tt>
|
||
|
|
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>
|
||
|
|
from = <i>string</i>,<br>
|
||
|
|
rcpt = <i>string</i> or <i>string-table</i>,<br>
|
||
|
|
body = <i>string</i>,<br>
|
||
|
|
headers = <i>headers-table</i>,<br>
|
||
|
|
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> ·
|
||
|
|
<a href="home.html#down">download</a> ·
|
||
|
|
<a href="introduction.html">introduction</a> ·
|
||
|
|
<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>
|