======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.

====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 an 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)
=====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:
**CheckFile(Filename, Actions, Size, CreationTime, ReturnPath, Recipients, HeaderData, HeaderLines)**

  * Filename - the filename on disk
  * Actions - An object containing the values: **SkipSend**, **Reason**, **Priority** - see below
  * Size - The size of the message on disk
  * CreationTime - The time the message was put in the outgoing queue - as YYYYMMDDHHMMSS
  * ReturnPath - The message sender/return path value
  * Recipients - A table containing a list of recipients
  * HeaderData - The header information as an associative table - eg HeaderData['Subject'] = <message subject>
  * HeaderLines - A list of the message header lines in raw form

The function returns an Actions object saying what to do with the message. If nothing else, the function should return the Actions parameter.

The Actions object contain three values:
  * SkipSend - if this is true then the message won't be sent this time. If 'false', then the message will be sent as normal.
  * Priority - this indicates what order the messages should be sent in. 50 is the default. Priority 100 go first, priority 1 go last.
  * Reason - this is logged as the reason if the SkipSend value is true.

A simple function which will stop messages over 10,000,000 bytes being sent between 7am and 7pm, and make messages over 5,000,000 bytes be sent last is below

<code>
function CheckFile(filename, actions, size, createtime, mailfrom, recipients, headerdata, headerlines)

 time = os.date("*t");
 if size > 10000000 and (time.hour > 7 and time.hour < 19) then
  actions["SkipSend"] = 1;
 end;

 if size > 5000000 then
  actions["Priority"] = 1;
 end;

 return actions;
end;
</code>

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:

<code>
function CheckFile(filename, actions, size, createtime, mailfrom, recipients, headerdata, headerlines)

 if size > 50000 then
  if senderid ~= 0 then
   actions["SkipSend"] = 1;
  end;
 else
  if senderid ~= 1 then
   actions["SkipSend"] = 1;
  end;
 end;

 return actions;
end;
</code>