aboutsummaryrefslogtreecommitdiff
path: root/doc/smtp.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/smtp.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/smtp.html')
-rw-r--r--doc/smtp.html228
1 files changed, 228 insertions, 0 deletions
diff --git a/doc/smtp.html b/doc/smtp.html
new file mode 100644
index 0000000..3a30a07
--- /dev/null
+++ b/doc/smtp.html
@@ -0,0 +1,228 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4
5<head>
6<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=smtp>SMTP</h2>
37
38<p>
39The module <tt>smtp.lua</tt> provides functionality to send e-mail
40messages. The implementation conforms to the Simple Mail Transfer Protocol,
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
42The other RFC of interest in this implementation is
43<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
44which governs the Internet Message Format.
45
46</p>
47
48<p>
49MIME headers are represented as a Lua table in the form:
50</p>
51
52<blockquote>
53<table summary="MIME headers in Lua table">
54<tr><td><tt>
55headers = {<br>
56&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
57&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
58&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
59</tt></td></tr>
60<tr><td align=center><tt>
61&nbsp;&nbsp;...
62</tt></td></tr>
63<tr><td><tt>
64&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
65}
66</tt></td></tr>
67</table>
68</blockquote>
69
70<p>
71Field names are case insensitive (as specified by the standard) and all
72functions work with lowercase field names.
73Field values are left unmodified.
74</p>
75
76<p class=note>
77Note: MIME headers are independent of order. Therefore, there is no problem
78in representing them in a Lua table.
79</p>
80
81<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
82
83<p class=name id=mail>
84socket.smtp.<b>mail{</b><br>
85&nbsp;&nbsp;from = <i>string</i>,<br>
86&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
87&nbsp;&nbsp;body = <i>string</i>,<br>
88&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
89&nbsp;&nbsp;server = <i>string</i><br>
90<b>}</b>
91</p>
92
93<p class=description>
94Sends a message to a recipient list.
95</p>
96
97<p class=parameters>
98<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
99in case there is just one recipient.
100The sender is given by the e-mail address <tt>from</tt>.
101The message is composed by the optional MIME Headers <tt>headers</tt>
102and text <tt>body</tt>. The message is sent using the server
103<tt>server</tt>.
104</p>
105
106<p class=return>
107If successful, the function returns 1. Otherwise, the function returns
108<tt>nil</tt> followed by an error message.
109</p>
110
111<p class=note>
112Big note: There is a good deal of misconception with the use of the
113destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
114and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
115'<tt>Bcc</tt>' header to your messages because it will probably do the
116exact opposite of what you expect.
117</p>
118
119<p class=note>
120Only recipients specified in the recipient list will receive a copy of the
121message. Each recipient of an SMTP mail message receives a copy of the
122message body along with the headers, and nothing more. The headers are
123considered as part of the message. The list of recipients is <em>not</em>
124part of the message.
125</p>
126
127<p class=note>
128<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
129has two <em>important and short</em> sections, "3.6.3. Destination address
130fields" and "5. Security considerations", explaining the proper
131use of these headers. Here is a summary of what it says:
132</p>
133
134<ul>
135<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
136of the message;
137<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
138making a copy on a typewriter using carbon paper) contains the
139addresses of others who are to receive the message, though the
140content of the message may not be directed at them;
141<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
142Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
143</ul>
144
145<p class=note>
146The LuaSocket <tt>mail</tt> function does not interpret the headers you
147pass to, but it gives you full control over what is sent and to whom
148it is sent:
149</p>
150<ul>
151<li> If someone is to receive the message, the e-mail address <em>has</em>
152to be in the recipient list. This is the only parameter that controls who
153gets a copy of the message;
154<li> If there are multiple recipients, none of them will automatically
155know that someone else got that message. That is, the default behavior is
156similar to the <tt>Bcc</tt> field of popular e-mail clients;
157<li> It is up to you to add the <tt>To</tt> header with the list of primary
158recipients so that other recipients can see it;
159<li> It is also up to you to add the <tt>Cc</tt> header with the
160list of additional recipients so that everyone else sees it;
161<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
162empty. Otherwise, everyone receiving the message will see it and that is
163exactly what you <em>don't</em> want to happen!
164</ul>
165
166<p class=note>
167I hope this clarifies the issue. Otherwise, please refer to
168<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
169and
170<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
171</p>
172
173<pre class=example>
174-- Connects to server "localhost" and sends a message to users
175-- "fulano@tecgraf.puc-rio.br", "beltrano@tecgraf.puc-rio.br",
176-- and "sicrano@tecgraf.puc-rio.br".
177-- Note that "fulano" is the primary recipient, "beltrano" receives a
178-- carbon copy and neither of them knows that "sicrano" received a blind
179-- carbon copy of the message.
180headers = {
181 to = "fulano@tecgraf.puc-rio.br",
182 cc = "beltrano@tecgraf.puc-rio.br",
183 subject = "LuaSocket test message"
184}
185
186from = "luasocket@tecgraf.puc-rio.br"
187
188rcpt = {
189 "fulano@tecgraf.puc-rio.br",
190 "beltrano@tecgraf.puc-rio.br",
191 "sicrano@tecgraf.puc-rio.br"
192}
193
194body = "This is a test message. Please ignore."
195
196server = "localhost"
197
198r, e = socket.smtp.mail{
199 from = from,
200 rcpt = rcpt,
201 headers = headers,
202 body = body,
203 server = server
204}
205</pre>
206
207<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209<div class=footer>
210<hr>
211<center>
212<p class=bar>
213<a href="home.html">home</a> &middot;
214<a href="home.html#down">download</a> &middot;
215<a href="introduction.html">introduction</a> &middot;
216<a href="reference.html">reference</a>
217</p>
218<p>
219<small>
220Last modified by Diego Nehab on <br>
221Sat Aug 9 01:00:41 PDT 2003
222</small>
223</p>
224</center>
225</div>
226
227</body>
228</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-15 10:07:32 +0000