Mercurial > luasocket

comparison doc/smtp.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
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 <meta name="description" content="LuaSocket: SMTP support">
7 <meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
8 Library, Support">
9 <title>LuaSocket: SMTP support</title>
10 <link rel="stylesheet" href="reference.css" type="text/css">
11 </head>
12
13 <body>
14
15 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17 <div class=header>
18 <hr>
19 <center>
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">
23 </a></td></tr>
24 <tr><td align=center valign=top>Network support for the Lua language
25 </td></tr>
26 </table>
27 <p class=bar>
28 <a href="home.html">home</a> &middot;
29 <a href="home.html#download">download</a> &middot;
30 <a href="installation.html">installation</a> &middot;
31 <a href="introduction.html">introduction</a> &middot;
32 <a href="reference.html">reference</a>
33 </p>
34 </center>
35 <hr>
36 </div>
37
38 <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40 <h2 id=smtp>SMTP</h2>
41
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).
48 </p>
49
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
58 2046</a>
59
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
64 creation. </p>
65
66 <p>
67 To obtain the <tt>smtp</tt> namespace, run:
68 </p>
69
70 <pre class=example>
71 -- loads the SMTP module and everything it requires
72 local smtp = require("socket.smtp")
73 </pre>
74
75 <p>
76 MIME headers are represented as a Lua table in the form:
77 </p>
78
79 <blockquote>
80 <table summary="MIME headers in Lua table">
81 <tr><td><tt>
82 headers = {<br>
83 &nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
84 &nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
85 &nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
86 &nbsp;&nbsp;...<br>
87 &nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
88 }
89 </tt></td></tr>
90 </table>
91 </blockquote>
92
93 <p>
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.
97 </p>
98
99 <p class=note>
100 Note: MIME headers are independent of order. Therefore, there is no problem
101 in representing them in a Lua table.
102 </p>
103
104 <p>
105 The following constants can be set to control the default behavior of
106 the SMTP module:
107 </p>
108
109 <ul>
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.
115 </ul>
116
117 <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118
119 <p class=name id=send>
120 smtp.<b>send{</b><br>
121 &nbsp;&nbsp;from = <i>string</i>,<br>
122 &nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
123 &nbsp;&nbsp;source = <i>LTN12 source</i>,<br>
124 &nbsp;&nbsp;[user = <i>string</i>,]<br>
125 &nbsp;&nbsp;[password = <i>string</i>,]<br>
126 &nbsp;&nbsp;[server = <i>string</i>,]<br>
127 &nbsp;&nbsp;[port = <i>number</i>,]<br>
128 &nbsp;&nbsp;[domain = <i>string</i>,]<br>
129 &nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
130 &nbsp;&nbsp;[create = <i>function</i>]<br>
131 <b>}</b>
132 </p>
133
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.
140 </p>
141
142
143 <p class=parameters>
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
146 address, or a string
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:
151 </p>
152 <ul>
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;
160 <li> <tt>step</tt>:
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.
166 </ul>
167
168 <p class=return>
169 If successful, the function returns 1. Otherwise, the function returns
170 <b><tt>nil</tt></b> followed by an error message.
171 </p>
172
173 <p class=note>
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>&lt;fulano@example.com&gt;</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>
179
180 <p class=note>
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.
186 </p>
187
188 <p class=note>
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.
196 </p>
197
198 <p class=note>
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:
203 </p>
204
205 <ul>
206 <li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
207 of the message;
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.
214 </ul>
215
216 <p class=note>
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
219 to whom it is sent:
220 </p>
221 <ul>
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!
235 </ul>
236
237 <p class=note>
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>
240 and
241 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
242 </p>
243
244 <pre class=example>
245 -- load the smtp support
246 local smtp = require("socket.smtp")
247
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 = "&lt;luasocket@example.com&gt;"
255
256 rcpt = {
257 "&lt;fulano@example.com&gt;",
258 "&lt;beltrano@example.com&gt;",
259 "&lt;sicrano@example.com&gt;"
260 }
261
262 mesgt = {
263 headers = {
264 to = "Fulano da Silva &lt;fulano@example.com&gt;",
265 cc = '"Beltrano F. Nunes" &lt;beltrano@example.com&gt;',
266 subject = "My first message"
267 },
268 body = "I hope this works. If it does, I can send you another 1000 copies."
269 }
270
271 r, e = smtp.send{
272 from = from,
273 rcpt = rcpt,
274 source = smtp.message(mesgt)
275 }
276 </pre>
277
278 <!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
279
280 <p class=name id=message>
281 smtp.<b>message(</b>mesgt<b>)</b>
282 </p>
283
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).
287 </p>
288
289 <p class=parameters>
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):
292 </p>
293
294 <blockquote>
295 <table summary="Mesgt table structure">
296 <tr><td><tt>
297 mesgt = {<br>
298 &nbsp;&nbsp;headers = <i>header-table</i>,<br>
299 &nbsp;&nbsp;body = <i>LTN12 source</i> or <i>string</i> or
300 <i>multipart-mesgt</i><br>
301 }<br>
302 &nbsp;<br>
303 multipart-mesgt = {<br>
304 &nbsp;&nbsp;[preamble = <i>string</i>,]<br>
305 &nbsp;&nbsp;[1] = <i>mesgt</i>,<br>
306 &nbsp;&nbsp;[2] = <i>mesgt</i>,<br>
307 &nbsp;&nbsp;...<br>
308 &nbsp;&nbsp;[<i>n</i>] = <i>mesgt</i>,<br>
309 &nbsp;&nbsp;[epilogue = <i>string</i>,]<br>
310 }<br>
311 </tt></td></tr>
312 </table>
313 </blockquote>
314
315 <p class=parameters>
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>.
323 </p>
324
325 <p class=return>
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>
333
334 <pre class=example>
335 -- load the smtp support and its friends
336 local smtp = require("socket.smtp")
337 local mime = require("mime")
338 local ltn12 = require("ltn12")
339
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{
343 headers = {
344 -- Remember that headers are *ignored* by smtp.send.
345 from = "Sicrano de Oliveira &lt;sicrano@example.com&gt;",
346 to = "Fulano da Silva &lt;fulano@example.com&gt;",
347 subject = "Here is a message with attachments"
348 },
349 body = {
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.
355 [1] = {
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
360 function does *NOT*.
361 ]])
362 },
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.
368 [2] = {
369 headers = {
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"
374 },
375 body = ltn12.source.chain(
376 ltn12.source.file(io.open("image.png", "rb")),
377 ltn12.filter.chain(
378 mime.encode("base64"),
379 mime.wrap()
380 )
381 )
382 },
383 epilogue = "This might also show up, but after the attachments"
384 }
385 }
386
387 -- finally send it
388 r, e = smtp.send{
389 from = "&lt;sicrano@example.com&gt;",
390 rcpt = "&lt;fulano@example.com&gt;",
391 source = source,
392 }
393 </pre>
394
395 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
396
397 <div class=footer>
398 <hr>
399 <center>
400 <p class=bar>
401 <a href="home.html">home</a> &middot;
402 <a href="home.html#down">download</a> &middot;
403 <a href="installation.html">installation</a> &middot;
404 <a href="introduction.html">introduction</a> &middot;
405 <a href="reference.html">reference</a>
406 </p>
407 <p>
408 <small>
409 Last modified by Diego Nehab on <br>
410 Thu Apr 20 00:25:51 EDT 2006
411 </small>
412 </p>
413 </center>
414 </div>
415
416 </body>
417 </html>