<!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>