From 58096449c6044b7aade5cd41cfd71c6bec1d273d Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 15 Jun 2004 06:24:00 +0000 Subject: Manual is almost done. HTTP is missing. Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully. --- doc/smtp.html | 235 ++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 194 insertions(+), 41 deletions(-) (limited to 'doc/smtp.html') diff --git a/doc/smtp.html b/doc/smtp.html index 0862de0..b0ae634 100644 --- a/doc/smtp.html +++ b/doc/smtp.html @@ -35,15 +35,22 @@

SMTP

-

-The smtp.lua module provides functionality to send e-mail +

The smtp.lua module 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, +Another RFC of interest is RFC 2822, which governs the Internet Message Format. +Multipart messages (those that contain attatchments) are part +of the MIME standard, but described mainly +in RFC +2046 -

+

In the description below, good understanding of LTN012, Filters +sources and sinks and the MIME module is +assumed. In fact, the SMTP module was the main reason for their +creation.

MIME headers are represented as a Lua table in the form: @@ -78,29 +85,56 @@ Note: MIME headers are independent of order. Therefore, there is no problem in representing them in a Lua table.

- +

+The following constants can be set to control the default behaviour of +the SMTP module: +

-

-socket.smtp.mail{
+

+ + + +

+smtp.send{
  from = string,
  rcpt = string or string-table,
-  body = string,
-  headers = headers-table,
-  server = string
+  source = LTN12 source,
+  [server = string],
+  [port = string]
+  [domain = string],
+  [step = LTN12 pump step],
}

-Sends a message to a recipient list. +Sends a message to a recipient list. Since sending messages is not as +simple as downloading an URL from a FTP or HTTP server, this function +doesn't have a simple interface. However, see the +message source factory for +a very powerful way to define the message contents.

-Rcpt is a Lua table with one entry for each recipient, or a string +The sender is given by the e-mail address in the from field. +Rcpt is a Lua table with one entry for each recipient e-mail +address, 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. +The contents of the message are given by a LTN12 source. Several +arguments are optional: +

@@ -108,6 +142,13 @@ If successful, the function returns 1. Otherwise, the function returns nil followed by an error message.

+

+Note: SMTP servers are can be very picky with the format of e-mail +addresses. To be safe, use only addresses of the form +"<fulano@tecgraf.puc-rio.br>" in the from and +rcpt arguments to the send function. In headers, e-mail +addresses can take whatever form you like.

+

Big note: There is a good deal of misconception with the use of the destination address field headers, i.e., the 'To', 'Cc', @@ -117,11 +158,12 @@ exact opposite of what you expect.

-Only recipients specified in the recipient list will receive a copy of the +Only recipients specified in the rcpt 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. +message body along with the headers, and nothing more. The headers +are part of the message and should be produced by the LTN12 +source function. The rcpt list is not +part of the message and will not be sent to anyone.

@@ -143,9 +185,9 @@ Copy") contains addresses of recipients of the message whose addresses are not t

-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: +The LuaSocket send function does not care or interpret the +headers you send, but it gives you full control over what is sent and +to whom it is sent: