LuaSocket: Network support for the Lua language

SMTP

The module smtp.lua provides functionality to send e-mail messages. The implementation conforms to the Simple Mail Transfer Protocol, RFC 2821. The other RFC of interest in this implementation is RFC 2822, which governs the Internet Message Format.

MIME headers are represented as a Lua table in the form:

headers = {   field-1-name = field-1-value,   field-2-name = field-2-value,   field-3-name = field-3-value,

  ...

  field-n-name = field-n-value }

Field names are case insensitive (as specified by the standard) and all functions work with lowercase field names. Field values are left unmodified.

Note: MIME headers are independent of order. Therefore, there is no problem in representing them in a Lua table.

socket.smtp.mail{
  from = string,
  rcpt = string or string-table,
  body = string,
  headers = headers-table,
  server = string
}

Sends a message to a recipient list.

Rcpt 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 from. The message is composed by the optional MIME Headers headers and text body. The message is sent using the server server.

If successful, the function returns 1. Otherwise, the function returns nil followed by an error message.

Big note: There is a good deal of misconception with the use of the destination address field headers, i.e., the 'To', 'Cc', and, more importantly, the 'Bcc' headers. Do not add a 'Bcc' header to your messages because it will probably do the exact opposite of what you expect.

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 not part of the message.

RFC 2822 has two important and short 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:

To: contains the address(es) of the primary recipient(s) of the message;
Cc: (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;
Bcc: (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.

The LuaSocket mail 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:

If someone is to receive the message, the e-mail address has to be in the recipient list. This is the only parameter that controls who gets a copy of the message;
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 Bcc field of popular e-mail clients;
It is up to you to add the To header with the list of primary recipients so that other recipients can see it;
It is also up to you to add the Cc header with the list of additional recipients so that everyone else sees it;
Adding a header Bcc is nonsense, unless it is empty. Otherwise, everyone receiving the message will see it and that is exactly what you don't want to happen!

I hope this clarifies the issue. Otherwise, please refer to RFC 2821 and RFC 2822.

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