1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2
"http://www.w3.org/TR/html4/strict.dtd">
6
<meta name="description" content="LuaSocket: SMTP support">
7
<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
9
<title>LuaSocket: SMTP support</title>
10
<link rel="stylesheet" href="reference.css" type="text/css">
15
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
20
<table summary="LuaSocket logo">
21
<tr><td align=center><a href="http://www.lua.org">
22
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
24
<tr><td align=center valign=top>Network support for the Lua language
28
<a href="home.html">home</a> ·
29
<a href="home.html#download">download</a> ·
30
<a href="installation.html">installation</a> ·
31
<a href="introduction.html">introduction</a> ·
32
<a href="reference.html">reference</a>
38
<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
42
<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
43
messages. The high-level API consists of two functions: one to
44
define an e-mail message, and another to actually send the message.
45
Although almost all users will find that these functions provide more than
46
enough functionality, the underlying implementation allows for even more
47
control (if you bother to read the code).
50
<p>The implementation conforms to the Simple Mail Transfer Protocol,
51
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
52
Another RFC of interest is <a
53
href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
54
which governs the Internet Message Format.
55
Multipart messages (those that contain attachments) are part
56
of the MIME standard, but described mainly
57
in <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">RFC
60
<p> In the description below, good understanding of <a
61
href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
62
sources and sinks</a> and the <a href=mime.html>MIME</a> module is
63
assumed. In fact, the SMTP module was the main reason for their
67
To obtain the <tt>smtp</tt> namespace, run:
71
-- loads the SMTP module and everything it requires
72
local smtp = require("socket.smtp")
76
MIME headers are represented as a Lua table in the form:
80
<table summary="MIME headers in Lua table">
83
field-1-name = <i>field-1-value</i>,<br>
84
field-2-name = <i>field-2-value</i>,<br>
85
field-3-name = <i>field-3-value</i>,<br>
87
field-n-name = <i>field-n-value</i><br>
94
Field names are case insensitive (as specified by the standard) and all
95
functions work with lowercase field names.
96
Field values are left unmodified.
100
Note: MIME headers are independent of order. Therefore, there is no problem
101
in representing them in a Lua table.
105
The following constants can be set to control the default behavior of
110
<li> <tt>DOMAIN</tt>: domain used to greet the server;
111
<li> <tt>PORT</tt>: default port used for the connection;
112
<li> <tt>SERVER</tt>: default server used for the connection;
113
<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;
114
<li> <tt>ZONE</tt>: default time zone.
117
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
119
<p class=name id=send>
120
smtp.<b>send{</b><br>
121
from = <i>string</i>,<br>
122
rcpt = <i>string</i> or <i>string-table</i>,<br>
123
source = <i>LTN12 source</i>,<br>
124
[user = <i>string</i>,]<br>
125
[password = <i>string</i>,]<br>
126
[server = <i>string</i>,]<br>
127
[port = <i>number</i>,]<br>
128
[domain = <i>string</i>,]<br>
129
[step = <i>LTN12 pump step</i>,]<br>
130
[create = <i>function</i>]<br>
134
<p class=description>
135
Sends a message to a recipient list. Since sending messages is not as
136
simple as downloading an URL from a FTP or HTTP server, this function
137
doesn't have a simple interface. However, see the
138
<a href=#message><tt>message</tt></a> source factory for
139
a very powerful way to define the message contents.
144
The sender is given by the e-mail address in the <tt>from</tt> field.
145
<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
147
in case there is just one recipient.
148
The contents of the message are given by a <em>simple</em>
149
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
150
<tt>source</tt>. Several arguments are optional:
153
<li> <tt>user</tt>, <tt>password</tt>: User and password for
154
authentication. The function will attempt LOGIN and PLAIN authentication
155
methods if supported by the server (both are unsafe);
156
<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";
157
<li> <tt>port</tt>: Port to connect to. Defaults to 25;
158
<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
159
local machine host name;
161
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
162
pump step function used to pass data from the
163
source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;
164
<li><tt>create</tt>: An optional function to be used instead of
165
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
169
If successful, the function returns 1. Otherwise, the function returns
170
<b><tt>nil</tt></b> followed by an error message.
174
Note: SMTP servers can be very picky with the format of e-mail
175
addresses. To be safe, use only addresses of the form
176
"<tt><fulano@example.com></tt>" in the <tt>from</tt> and
177
<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
178
addresses can take whatever form you like. </p>
181
Big note: There is a good deal of misconception with the use of the
182
destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
183
and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
184
'<tt>Bcc</tt>' header to your messages because it will probably do the
185
exact opposite of what you expect.
189
Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
190
message. Each recipient of an SMTP mail message receives a copy of the
191
message body along with the headers, and nothing more. The headers
192
<em>are</em> part of the message and should be produced by the
193
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
194
<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
195
part of the message and will not be sent to anyone.
199
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
200
has two <em>important and short</em> sections, "3.6.3. Destination address
201
fields" and "5. Security considerations", explaining the proper
202
use of these headers. Here is a summary of what it says:
206
<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
208
<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
209
making a copy on a typewriter using carbon paper) contains the
210
addresses of others who are to receive the message, though the
211
content of the message may not be directed at them;
212
<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
213
Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
217
The LuaSocket <tt>send</tt> function does not care or interpret the
218
headers you send, but it gives you full control over what is sent and
222
<li> If someone is to receive the message, the e-mail address <em>has</em>
223
to be in the recipient list. This is the only parameter that controls who
224
gets a copy of the message;
225
<li> If there are multiple recipients, none of them will automatically
226
know that someone else got that message. That is, the default behavior is
227
similar to the <tt>Bcc</tt> field of popular e-mail clients;
228
<li> It is up to you to add the <tt>To</tt> header with the list of primary
229
recipients so that other recipients can see it;
230
<li> It is also up to you to add the <tt>Cc</tt> header with the
231
list of additional recipients so that everyone else sees it;
232
<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
233
empty. Otherwise, everyone receiving the message will see it and that is
234
exactly what you <em>don't</em> want to happen!
238
I hope this clarifies the issue. Otherwise, please refer to
239
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
241
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
245
-- load the smtp support
246
local smtp = require("socket.smtp")
248
-- Connects to server "localhost" and sends a message to users
249
-- "fulano@example.com", "beltrano@example.com",
250
-- and "sicrano@example.com".
251
-- Note that "fulano" is the primary recipient, "beltrano" receives a
252
-- carbon copy and neither of them knows that "sicrano" received a blind
253
-- carbon copy of the message.
254
from = "<luasocket@example.com>"
257
"<fulano@example.com>",
258
"<beltrano@example.com>",
259
"<sicrano@example.com>"
264
to = "Fulano da Silva <fulano@example.com>",
265
cc = '"Beltrano F. Nunes" <beltrano@example.com>',
266
subject = "My first message"
268
body = "I hope this works. If it does, I can send you another 1000 copies."
274
source = smtp.message(mesgt)
278
<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
280
<p class=name id=message>
281
smtp.<b>message(</b>mesgt<b>)</b>
284
<p class=description>
285
Returns a <em>simple</em>
286
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
290
The only parameter of the function is a table describing the message.
291
<tt>Mesgt</tt> has the following form (notice the recursive structure):
295
<table summary="Mesgt table structure">
298
headers = <i>header-table</i>,<br>
299
body = <i>LTN12 source</i> or <i>string</i> or
300
<i>multipart-mesgt</i><br>
303
multipart-mesgt = {<br>
304
[preamble = <i>string</i>,]<br>
305
[1] = <i>mesgt</i>,<br>
306
[2] = <i>mesgt</i>,<br>
308
[<i>n</i>] = <i>mesgt</i>,<br>
309
[epilogue = <i>string</i>,]<br>
316
For a simple message, all that is needed is a set of <tt>headers</tt>
317
and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
318
or as a <em>simple</em>
319
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
320
source. For multipart messages, the body is a table that
321
recursively defines each part as an independent message, plus an optional
322
<tt>preamble</tt> and <tt>epilogue</tt>.
326
The function returns a <em>simple</em>
327
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
328
source that produces the
329
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
330
Hopefully, the following
331
example will make things clear. When in doubt, refer to the appropriate RFC
332
as listed in the introduction. </p>
335
-- load the smtp support and its friends
336
local smtp = require("socket.smtp")
337
local mime = require("mime")
338
local ltn12 = require("ltn12")
340
-- creates a source to send a message with two parts. The first part is
341
-- plain text, the second part is a PNG image, encoded as base64.
342
source = smtp.message{
344
-- Remember that headers are *ignored* by smtp.send.
345
from = "Sicrano de Oliveira <sicrano@example.com>",
346
to = "Fulano da Silva <fulano@example.com>",
347
subject = "Here is a message with attachments"
350
preamble = "If your client doesn't understand attachments, \r\n" ..
351
"it will still display the preamble and the epilogue.\r\n" ..
352
"Preamble will probably appear even in a MIME enabled client.",
353
-- first part: no headers means plain text, us-ascii.
354
-- The mime.eol low-level filter normalizes end-of-line markers.
356
body = mime.eol(0, [[
357
Lines in a message body should always end with CRLF.
358
The smtp module will *NOT* perform translation. However, the
359
send function *DOES* perform SMTP stuffing, whereas the message
363
-- second part: headers describe content to be a png image,
364
-- sent under the base64 transfer content encoding.
365
-- notice that nothing happens until the message is actually sent.
366
-- small chunks are loaded into memory right before transmission and
367
-- translation happens on the fly.
370
["content-type"] = 'image/png; name="image.png"',
371
["content-disposition"] = 'attachment; filename="image.png"',
372
["content-description"] = 'a beautiful image',
373
["content-transfer-encoding"] = "BASE64"
375
body = ltn12.source.chain(
376
ltn12.source.file(io.open("image.png", "rb")),
378
mime.encode("base64"),
383
epilogue = "This might also show up, but after the attachments"
389
from = "<sicrano@example.com>",
390
rcpt = "<fulano@example.com>",
395
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
401
<a href="home.html">home</a> ·
402
<a href="home.html#down">download</a> ·
403
<a href="installation.html">installation</a> ·
404
<a href="introduction.html">introduction</a> ·
405
<a href="reference.html">reference</a>
409
Last modified by Diego Nehab on <br>
410
Thu Apr 20 00:25:51 EDT 2006
added
removed
src/libs/luasocket/doc/smtp.html
