aboutsummaryrefslogtreecommitdiff
path: root/docs/smtp.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/smtp.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to '')
-rw-r--r--docs/smtp.html (renamed from doc/smtp.html)382
1 files changed, 192 insertions, 190 deletions
diff --git a/doc/smtp.html b/docs/smtp.html
index bbbff80..787d0b1 100644
--- a/doc/smtp.html
+++ b/docs/smtp.html
@@ -1,11 +1,11 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: SMTP support"> 6<meta name="description" content="LuaSocket: SMTP support">
7<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, 7<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
8Library, Support"> 8Library, Support">
9<title>LuaSocket: SMTP support</title> 9<title>LuaSocket: SMTP support</title>
10<link rel="stylesheet" href="reference.css" type="text/css"> 10<link rel="stylesheet" href="reference.css" type="text/css">
11</head> 11</head>
@@ -14,22 +14,22 @@ Library, Support">
14 14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16 16
17<div class=header> 17<div class="header">
18<hr> 18<hr>
19<center> 19<center>
20<table summary="LuaSocket logo"> 20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org"> 21<tr><td align="center"><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 22<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
23</a></td></tr> 23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language 24<tr><td align="center" valign="top">Network support for the Lua language
25</td></tr> 25</td></tr>
26</table> 26</table>
27<p class=bar> 27<p class="bar">
28<a href="index.html">home</a> &middot; 28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot; 29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot; 30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot; 31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a> 32<a href="reference.html">reference</a>
33</p> 33</p>
34</center> 34</center>
35<hr> 35<hr>
@@ -37,14 +37,14 @@ Library, Support">
37 37
38<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 38<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39 39
40<h2 id=smtp>SMTP</h2> 40<h2 id="smtp">SMTP</h2>
41 41
42<p> The <tt>smtp</tt> namespace provides functionality to send e-mail 42<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
43messages. The high-level API consists of two functions: one to 43messages. The high-level API consists of two functions: one to
44define an e-mail message, and another to actually send the message. 44define an e-mail message, and another to actually send the message.
45Although almost all users will find that these functions provide more than 45Although almost all users will find that these functions provide more than
46enough functionality, the underlying implementation allows for even more 46enough functionality, the underlying implementation allows for even more
47control (if you bother to read the code). 47control (if you bother to read the code).
48</p> 48</p>
49 49
50<p>The implementation conforms to the Simple Mail Transfer Protocol, 50<p>The implementation conforms to the Simple Mail Transfer Protocol,
@@ -54,19 +54,19 @@ href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>,
54which governs the Internet Message Format. 54which governs the Internet Message Format.
55Multipart messages (those that contain attachments) are part 55Multipart messages (those that contain attachments) are part
56of the MIME standard, but described mainly 56of the MIME standard, but described mainly
57in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> 57in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p>
58 58
59<p> In the description below, good understanding of <a 59<p> In the description below, good understanding of <a
60href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters 60href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
61sources and sinks</a> and the <a href=mime.html>MIME</a> module is 61sources and sinks</a> and the <a href="mime.html">MIME</a> module is
62assumed. In fact, the SMTP module was the main reason for their 62assumed. In fact, the SMTP module was the main reason for their
63creation. </p> 63creation. </p>
64 64
65<p> 65<p>
66To obtain the <tt>smtp</tt> namespace, run: 66To obtain the <tt>smtp</tt> namespace, run:
67</p> 67</p>
68 68
69<pre class=example> 69<pre class="example">
70-- loads the SMTP module and everything it requires 70-- loads the SMTP module and everything it requires
71local smtp = require("socket.smtp") 71local smtp = require("socket.smtp")
72</pre> 72</pre>
@@ -92,31 +92,149 @@ headers = {<br>
92<p> 92<p>
93Field names are case insensitive (as specified by the standard) and all 93Field names are case insensitive (as specified by the standard) and all
94functions work with lowercase field names (but see 94functions work with lowercase field names (but see
95<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). 95<a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
96Field values are left unmodified. 96Field values are left unmodified.
97</p> 97</p>
98 98
99<p class=note> 99<p class="note">
100Note: MIME headers are independent of order. Therefore, there is no problem 100Note: MIME headers are independent of order. Therefore, there is no problem
101in representing them in a Lua table. 101in representing them in a Lua table.
102</p> 102</p>
103 103
104<p> 104<p>
105The following constants can be set to control the default behavior of 105The following constants can be set to control the default behavior of
106the SMTP module: 106the SMTP module:
107</p> 107</p>
108 108
109<ul> 109<ul>
110<li> <tt>DOMAIN</tt>: domain used to greet the server; 110<li> <tt>DOMAIN</tt>: domain used to greet the server;</li>
111<li> <tt>PORT</tt>: default port used for the connection; 111<li> <tt>PORT</tt>: default port used for the connection;</li>
112<li> <tt>SERVER</tt>: default server used for the connection; 112<li> <tt>SERVER</tt>: default server used for the connection;</li>
113<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations; 113<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li>
114<li> <tt>ZONE</tt>: default time zone. 114<li> <tt>ZONE</tt>: default time zone.</li>
115</ul> 115</ul>
116 116
117<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118
119<p class="name" id="message">
120smtp.<b>message(</b>mesgt<b>)</b>
121</p>
122
123<p class="description">
124Returns a <em>simple</em>
125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
126</p>
127
128<p class="parameters">
129The only parameter of the function is a table describing the message.
130<tt>Mesgt</tt> has the following form (notice the recursive structure):
131</p>
132
133<blockquote>
134<table summary="Mesgt table structure">
135<tr><td><tt>
136mesgt = {<br>
137&nbsp;&nbsp;headers = <i>header-table</i>,<br>
138&nbsp;&nbsp;body = <i>LTN12 source</i> or <i>string</i> or
139<i>multipart-mesgt</i><br>
140}<br>
141&nbsp;<br>
142multipart-mesgt = {<br>
143&nbsp;&nbsp;[preamble = <i>string</i>,]<br>
144&nbsp;&nbsp;[1] = <i>mesgt</i>,<br>
145&nbsp;&nbsp;[2] = <i>mesgt</i>,<br>
146&nbsp;&nbsp;...<br>
147&nbsp;&nbsp;[<i>n</i>] = <i>mesgt</i>,<br>
148&nbsp;&nbsp;[epilogue = <i>string</i>,]<br>
149}<br>
150</tt></td></tr>
151</table>
152</blockquote>
153
154<p class="parameters">
155For a simple message, all that is needed is a set of <tt>headers</tt>
156and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
157or as a <em>simple</em>
158<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
159source. For multipart messages, the body is a table that
160recursively defines each part as an independent message, plus an optional
161<tt>preamble</tt> and <tt>epilogue</tt>.
162</p>
163
164<p class="return">
165The function returns a <em>simple</em>
166<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
167source that produces the
168message contents as defined by <tt>mesgt</tt>, chunk by chunk.
169Hopefully, the following
170example will make things clear. When in doubt, refer to the appropriate RFC
171as listed in the introduction. </p>
172
173<pre class="example">
174-- load the smtp support and its friends
175local smtp = require("socket.smtp")
176local mime = require("mime")
177local ltn12 = require("ltn12")
178
179-- creates a source to send a message with two parts. The first part is
180-- plain text, the second part is a PNG image, encoded as base64.
181source = smtp.message{
182 headers = {
183 -- Remember that headers are *ignored* by smtp.send.
184 from = "Sicrano de Oliveira &lt;sicrano@example.com&gt;",
185 to = "Fulano da Silva &lt;fulano@example.com&gt;",
186 subject = "Here is a message with attachments"
187 },
188 body = {
189 preamble = "If your client doesn't understand attachments, \r\n" ..
190 "it will still display the preamble and the epilogue.\r\n" ..
191 "Preamble will probably appear even in a MIME enabled client.",
192 -- first part: no headers means plain text, us-ascii.
193 -- The mime.eol low-level filter normalizes end-of-line markers.
194 [1] = {
195 body = mime.eol(0, [[
196 Lines in a message body should always end with CRLF.
197 The smtp module will *NOT* perform translation. However, the
198 send function *DOES* perform SMTP stuffing, whereas the message
199 function does *NOT*.
200 ]])
201 },
202 -- second part: headers describe content to be a png image,
203 -- sent under the base64 transfer content encoding.
204 -- notice that nothing happens until the message is actually sent.
205 -- small chunks are loaded into memory right before transmission and
206 -- translation happens on the fly.
207 [2] = {
208 headers = {
209 ["content-type"] = 'image/png; name="image.png"',
210 ["content-disposition"] = 'attachment; filename="image.png"',
211 ["content-description"] = 'a beautiful image',
212 ["content-transfer-encoding"] = "BASE64"
213 },
214 body = ltn12.source.chain(
215 ltn12.source.file(io.open("image.png", "rb")),
216 ltn12.filter.chain(
217 mime.encode("base64"),
218 mime.wrap()
219 )
220 )
221 },
222 epilogue = "This might also show up, but after the attachments"
223 }
224}
225
226-- finally send it
227r, e = smtp.send{
228 from = "&lt;sicrano@example.com&gt;",
229 rcpt = "&lt;fulano@example.com&gt;",
230 source = source,
231}
232</pre>
233
234
117<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 235<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118 236
119<p class=name id=send> 237<p class="name" id="send">
120smtp.<b>send{</b><br> 238smtp.<b>send{</b><br>
121&nbsp;&nbsp;from = <i>string</i>,<br> 239&nbsp;&nbsp;from = <i>string</i>,<br>
122&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br> 240&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
@@ -131,53 +249,53 @@ smtp.<b>send{</b><br>
131<b>}</b> 249<b>}</b>
132</p> 250</p>
133 251
134<p class=description> 252<p class="description">
135Sends a message to a recipient list. Since sending messages is not as 253Sends a message to a recipient list. Since sending messages is not as
136simple as downloading an URL from a FTP or HTTP server, this function 254simple as downloading an URL from a FTP or HTTP server, this function
137doesn't have a simple interface. However, see the 255doesn't have a simple interface. However, see the
138<a href=#message><tt>message</tt></a> source factory for 256<a href="#message"><tt>message</tt></a> source factory for
139a very powerful way to define the message contents. 257a very powerful way to define the message contents.
140</p> 258</p>
141 259
142 260
143<p class=parameters> 261<p class="parameters">
144The sender is given by the e-mail address in the <tt>from</tt> field. 262The 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 263<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
146address, or a string 264address, or a string
147in case there is just one recipient. 265in case there is just one recipient.
148The contents of the message are given by a <em>simple</em> 266The contents of the message are given by a <em>simple</em>
149<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 267<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
150<tt>source</tt>. Several arguments are optional: 268<tt>source</tt>. Several arguments are optional:
151</p> 269</p>
152<ul> 270<ul>
153<li> <tt>user</tt>, <tt>password</tt>: User and password for 271<li> <tt>user</tt>, <tt>password</tt>: User and password for
154authentication. The function will attempt LOGIN and PLAIN authentication 272authentication. The function will attempt LOGIN and PLAIN authentication
155methods if supported by the server (both are unsafe); 273methods if supported by the server (both are unsafe);</li>
156<li> <tt>server</tt>: Server to connect to. Defaults to "localhost"; 274<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li>
157<li> <tt>port</tt>: Port to connect to. Defaults to 25; 275<li> <tt>port</tt>: Port to connect to. Defaults to 25;</li>
158<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the 276<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
159local machine host name; 277local machine host name;</li>
160<li> <tt>step</tt>: 278<li> <tt>step</tt>:
161<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 279<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
162pump step function used to pass data from the 280pump step function used to pass data from the
163source to the server. Defaults to the LTN12 <tt>pump.step</tt> function; 281source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
164<li><tt>create</tt>: An optional function to be used instead of 282<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. 283<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
166</ul> 284</ul>
167 285
168<p class=return> 286<p class="return">
169If successful, the function returns 1. Otherwise, the function returns 287If successful, the function returns 1. Otherwise, the function returns
170<b><tt>nil</tt></b> followed by an error message. 288<b><tt>nil</tt></b> followed by an error message.
171</p> 289</p>
172 290
173<p class=note> 291<p class="note">
174Note: SMTP servers can be very picky with the format of e-mail 292Note: SMTP servers can be very picky with the format of e-mail
175addresses. To be safe, use only addresses of the form 293addresses. To be safe, use only addresses of the form
176"<tt>&lt;fulano@example.com&gt;</tt>" in the <tt>from</tt> and 294"<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 295<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
178addresses can take whatever form you like. </p> 296addresses can take whatever form you like. </p>
179 297
180<p class=note> 298<p class="note">
181Big note: There is a good deal of misconception with the use of the 299Big note: There is a good deal of misconception with the use of the
182destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', 300destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
183and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a 301and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
@@ -185,68 +303,69 @@ and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
185exact opposite of what you expect. 303exact opposite of what you expect.
186</p> 304</p>
187 305
188<p class=note> 306<p class="note">
189Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the 307Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
190message. Each recipient of an SMTP mail message receives a copy of the 308message. Each recipient of an SMTP mail message receives a copy of the
191message body along with the headers, and nothing more. The headers 309message body along with the headers, and nothing more. The headers
192<em>are</em> part of the message and should be produced by the 310<em>are</em> part of the message and should be produced by the
193<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 311<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
194<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> 312<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
195part of the message and will not be sent to anyone. 313part of the message and will not be sent to anyone.
196</p> 314</p>
197 315
198<p class=note> 316<p class="note">
199<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> 317<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>
200has two <em>important and short</em> sections, "3.6.3. Destination address 318has two <em>important and short</em> sections, "3.6.3. Destination address
201fields" and "5. Security considerations", explaining the proper 319fields" and "5. Security considerations", explaining the proper
202use of these headers. Here is a summary of what it says: 320use of these headers. Here is a summary of what it says:
203</p> 321</p>
204 322
205<ul> 323<ul>
206<li> <tt>To</tt>: contains the address(es) of the primary recipient(s) 324<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
207of the message; 325of the message;</li>
208<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of 326<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
209making a copy on a typewriter using carbon paper) contains the 327making a copy on a typewriter using carbon paper) contains the
210addresses of others who are to receive the message, though the 328addresses of others who are to receive the message, though the
211content of the message may not be directed at them; 329content of the message may not be directed at them;</li>
212<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon 330<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
213Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message. 331Copy") contains addresses of recipients of the message whose addresses are not
214</ul> 332to be revealed to other recipients of the message.</li>
333</ul>
215 334
216<p class=note> 335<p class="note">
217The LuaSocket <tt>send</tt> function does not care or interpret the 336The LuaSocket <tt>send</tt> function does not care or interpret the
218headers you send, but it gives you full control over what is sent and 337headers you send, but it gives you full control over what is sent and
219to whom it is sent: 338to whom it is sent:
220</p> 339</p>
221<ul> 340<ul>
222<li> If someone is to receive the message, the e-mail address <em>has</em> 341<li> If someone is to receive the message, the e-mail address <em>has</em>
223to be in the recipient list. This is the only parameter that controls who 342to be in the recipient list. This is the only parameter that controls who
224gets a copy of the message; 343gets a copy of the message;</li>
225<li> If there are multiple recipients, none of them will automatically 344<li> If there are multiple recipients, none of them will automatically
226know that someone else got that message. That is, the default behavior is 345know that someone else got that message. That is, the default behavior is
227similar to the <tt>Bcc</tt> field of popular e-mail clients; 346similar to the <tt>Bcc</tt> field of popular e-mail clients;</li>
228<li> It is up to you to add the <tt>To</tt> header with the list of primary 347<li> It is up to you to add the <tt>To</tt> header with the list of primary
229recipients so that other recipients can see it; 348recipients so that other recipients can see it;</li>
230<li> It is also up to you to add the <tt>Cc</tt> header with the 349<li> It is also up to you to add the <tt>Cc</tt> header with the
231list of additional recipients so that everyone else sees it; 350list of additional recipients so that everyone else sees it;</li>
232<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is 351<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
233empty. Otherwise, everyone receiving the message will see it and that is 352empty. Otherwise, everyone receiving the message will see it and that is
234exactly what you <em>don't</em> want to happen! 353exactly what you <em>don't</em> want to happen!</li>
235</ul> 354</ul>
236 355
237<p class=note> 356<p class="note">
238I hope this clarifies the issue. Otherwise, please refer to 357I hope this clarifies the issue. Otherwise, please refer to
239<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> 358<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>
240and 359and
241<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. 360<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>.
242</p> 361</p>
243 362
244<pre class=example> 363<pre class="example">
245-- load the smtp support 364-- load the smtp support
246local smtp = require("socket.smtp") 365local smtp = require("socket.smtp")
247 366
248-- Connects to server "localhost" and sends a message to users 367-- Connects to server "localhost" and sends a message to users
249-- "fulano@example.com", "beltrano@example.com", 368-- "fulano@example.com", "beltrano@example.com",
250-- and "sicrano@example.com". 369-- and "sicrano@example.com".
251-- Note that "fulano" is the primary recipient, "beltrano" receives a 370-- Note that "fulano" is the primary recipient, "beltrano" receives a
252-- carbon copy and neither of them knows that "sicrano" received a blind 371-- carbon copy and neither of them knows that "sicrano" received a blind
@@ -270,134 +389,17 @@ mesgt = {
270 389
271r, e = smtp.send{ 390r, e = smtp.send{
272 from = from, 391 from = from,
273 rcpt = rcpt, 392 rcpt = rcpt,
274 source = smtp.message(mesgt) 393 source = smtp.message(mesgt)
275} 394}
276</pre> 395</pre>
277 396
278<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
279
280<p class=name id=message>
281smtp.<b>message(</b>mesgt<b>)</b>
282</p>
283
284<p class=description>
285Returns 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>
290The 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>
297mesgt = {<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>
303multipart-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>
316For a simple message, all that is needed is a set of <tt>headers</tt>
317and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
318or as a <em>simple</em>
319<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
320source. For multipart messages, the body is a table that
321recursively 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>
326The function returns a <em>simple</em>
327<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
328source that produces the
329message contents as defined by <tt>mesgt</tt>, chunk by chunk.
330Hopefully, the following
331example will make things clear. When in doubt, refer to the appropriate RFC
332as listed in the introduction. </p>
333
334<pre class=example>
335-- load the smtp support and its friends
336local smtp = require("socket.smtp")
337local mime = require("mime")
338local 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.
342source = 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
388r, 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 397<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
396 398
397<div class=footer> 399<div class="footer">
398<hr> 400<hr>
399<center> 401<center>
400<p class=bar> 402<p class="bar">
401<a href="index.html">home</a> &middot; 403<a href="index.html">home</a> &middot;
402<a href="index.html#down">download</a> &middot; 404<a href="index.html#down">download</a> &middot;
403<a href="installation.html">installation</a> &middot; 405<a href="installation.html">installation</a> &middot;
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-01 13:17:37 +0000