Differences

This shows you the differences between two versions of the page.

--- reference:lua_smtp_relay_control [2010/05/04 15:09] – paul
+++ reference:lua_smtp_relay_control [2025/08/14 10:24] (current) – paul
@@ Line 1: / Line 1: @@
 ======Lua SMTP Relay Control======
-Every time VPOP3 is going to send messages via SMTP Relay, it runs a script called **relayout.lua** in the VPOP3 directory. For every message which is to be sent (according to any SMTP Domain filter rules) VPOP3 calls a function in that script called **CheckFile**.
+Every time VPOP3 is going to send messages via SMTP Relay, it runs a script called **relayout.lua** in the VPOP3 directory.
+====Global Variables====
+This script may have global variables, depending on your version of VPOP3.
+In VPOP3 3.0.0L and later, there are two read-only global variables set at the start of the script:
+  * senderid - this is the numeric message sender configuration id (starting at 0)
+  * sendername - this is the name you gave to the message sender configuration in VPOP3
+In VPOP3 5 and later, there is a read/write global variable
+  * UseBATV - this is a boolean value saying whether to [[http://en.wikipedia.org/wiki/Bounce_Address_Tag_Validation|BATV]] encode the return path address
+In VPOP3 6.7 and later, there are more read/write global variables and a read-only variable
+  * MaxMessagesPerConnection - The maximum number of messages to send in this connection
+  * MaxRecipientsPerConnection - The maximum number of recipients to specify in this connection
+  * MaxRecipientsPerMessage - The maximum number of recipients to send each message to
+  * ConnectedServer (read only) - The server name which VPOP3 has connected to (set just before the ServerConnected function call)
+In VPOP3 8.8 and later, there is a read/write global variables
+  * VerifyCertificate - this is a boolean value saying whether to verify the SSL certificate when connecting in SSL/TLS or STARTTLS mode. If the certificate verification fails (certificate/hostname mismatch or not verifying to a root) then the connection will terminate
+=====Initialisation=====
+When VPOP3 starts the send process, it calls the function **Start** which takes no parameters, and has no return value. This can be used for initialisation, or for changing read/write global variables
+In VPOP3 v6.7 and later, after VPOP3 has connected to an SMTP relay server, it calls the function **ServerConnected** which takes no parameters and has no return value. The **ConnectedServer** global variable is set just before this function call.
+=====Return Code Handling=====
+Starting in version 5.0.0, VPOP3 will call the function **ReturnCodeHandler** every time it receives a return code from the ISP's server.
+The function signature is:
+**ReturnCodeHandler(LastCommand, FullResponse, LastLine)**
+  * LastCommand - the last SMTP command sent by VPOP3
+  * FullResponse - the latest full response from the ISP. Note that if the ISP gives a multi-line response, this value contains the full response, not just one line of it
+  * LastLine - the last line of the response from the ISP
+The function optionally returns a string which contains the new full response. This must start with a numeric SMTP return code.
+This function is intended to be used if the ISP returns inappropriate return codes. For instance, some ISPs return '4xx' return codes for 'bad recipient', which makes VPOP3 retry sending the message when they should really return a '5xx' return code to tell VPOP3 not to retry the message, and just generate a delivery failure report.
+=====Messages to be sent=====
+For every message which is to be sent (according to any SMTP Domain filter rules) VPOP3 calls a function in that script called **CheckFile**.
 The function signature is:
@@ Line 39: / Line 77: @@
 end;
 </code>
-In VPOP3 3.0.0L and later, there are two global variables set at the start of the script:
-  * senderid - this is the numeric message sender configuration id (starting at 0)
-  * sendername - this is the name you gave to the message sender configuration in VPOP3
 As an example, if you want messages over 50000 bytes to go through mail sender '0' and all other messages to go through mail sender '1' you could have:
@@ Line 49: / Line 83: @@
 function CheckFile(filename, actions, size, createtime, mailfrom, recipients, headerdata, headerlines)
- time = os.date("*t");
  if size > 50000 then
   if senderid ~= 0 then
@@ Line 63: / Line 96: @@
 end;
 </code>
+=====Return Path Modification=====
+In VPOP3 v8.8 and later, a function is called as each message is sent, allowing the Lua script to rewrite the Return Path (MAIL FROM) address. This can be useful for implementing things such as SRS or other sender rewriting
+The function signature is:
+**ModifyReturnPath(Computed-Mail-From, Mail-From, Original-Mail-From, Auth-Sender, Recipients, Creation-Time, Headers, Size, Sender-IP-Address, Subject, All-Recipients)**
+  * Computed-Mail-From - the Return Path after being processed by VPOP3 (eg using 'Return Path Settings' in the Mail Sender). This is the Return Path that will be used if the Lua script doesn't give an alternative
+  * Mail-From - the Return Path prior to the Return Path Settings acting on it. This can take account of Mappings to change it
+  * Original-Mail-From - the original Return Path when the message was sent
+  * Auth-Sender - the authenticated VPOP3 user who sent the message
+  * Recipients - a table of recipients to whom this message will be sent at this time
+  * Creation-Time - the time the outgoing message was created in VPOP3. In ISO-8601 format
+  * Headers - a table of the message headers
+  * Size - the message size
+  * Sender-IP-Address - the IP address of the message sender (or blank if created by VPOP3)
+  * Subject - the message subject
+  * All-Recipients - a table of all the recipients the message was sent to. This may contain more recipients than the 'Recipients' table, because the message may already have been sent to some recipients, or Domain Filtering may have removed some recipients from this send attempt
+The function can return a single string value which is the new Return Path to use (if it doesn't return anything, then the 'Computed-Mail-From' value will be used).

PSCS Wiki

User Tools

Site Tools

Differences

Page Tools