This is an old revision of the document!
The SMTP Server Lua Script is called SMTPSVR.LUA and should be placed in the VPOP3 folder. This script is called whenever an instance of the VPOP3 SMTP server is launched - ie whenever someone opens a connection to port 25 on the VPOP3 server to send it a message, whether from a local user or an incoming SMTP message.
Each SMTP server instance has its own instance of the SMTPSVR.LUA script. No threading conflicts will occur.
During the lifetime of the SMTP server instance, there are several global variables which are available to the Lua script. These may change as the script is called on different callbacks, and may be changed by the Lua script itself in order to change the VPOP3 behaviour.
VPOP3 will call the following Lua functions in the script at the following times:
Start()
This function is called by VPOP3 when the SMTP Server session starts, before the welcome message is sent to the SMTP client
Can return “” to give the default welcome message, or another string (including the SMTP result code).
VPOP3 will terminate the connection if a 5xx or 4xx result code is given
In VPOP3 Enterprise, there are also the following global variables defined. These can be changed by the Start() function if desired:
* RBLServers - table containing a list of RBL servers to query
* RBLWhitelist - table containing a list of white-listed servers (wildcards are supported)
* RBLCheckAllServers - if TRUE then all RBL servers will be checked, if FALSE, then VPOP3 will stop testing as soon as one returns a match result.
=====SMTP Server - RBLResults()=====
RBLResults()
(Only supported in VPOP3 Enterprise)
This function is called by VPOP3 after the RBL (Realtime Black List) processing has taken place
For this function the standard SMTP Server Global Variables will give the result of the RBL processing.
Also there is a table called RBLResultInfo which contains the raw result information in the form of a table of entries indexed on the name of the RBL
database, with the entry data being the IP address resulting from the RBL query in the form of a single number (so a resulting value of '127.0.0.1' which be stored as 0x0100007f or 16777343)
(Note a bug in VPOP3 2.1.0 and earlier means that this will not work. It was fixed in 2.1.0a and later)
This function should return a text string which can be used to block connections.
This text string is used as the 'welcome' response from the VPOP3 SMTP server.
If the return string is “”, then the default VPOP3 welcome text will be used, or the return value from the Start() function if any. Otherwise the text returned from this function will be used. The text string returned should contain the SMTP result code - VPOP3 will terminate the connection if a 5xx or 4xx result code is given.
=====GetMaxMessageSize()=====
GetMaxMessageSize(“<hostname>”, <current max size in bytes>)
This function is called by VPOP3 when the SMTP service session starts, and also when VPOP3 receives a EHLO or HELO command
At session start the <hostname> value is the SMTP client IP address. At the EHLO/HELO time it's the parameter to the EHLO or HELO command.
This function should return the new maximum message size in bytes (0 = no limit)
=====GetEHLOCapabilities=====
GetEHLOCapabilities(“<hostname>”, “<current capabilities>”)
This function is called by VPOP3 when it receives a EHLO command
The <hostname> value is the value of the parameter to the EHLO command.DoHELO(“<hostname>”, bRefuse, bEHLO)
This function is called by VPOP3 when it receives a HELO or EHLO command
The <hostname> value is the value of the parameter to the EHLO or HELO command.DoHELP(”<help text>”)
This function is called by VPOP3 when it receives a HELP command
The <help text> value is the text which VPOP3 will return to the SMTP client
This function should return the new help text to return to the client (see the RFCs for the syntax)
=====DoQUIT()=====
DoQUIT()
This function is called by VPOP3 when it receives a QUIT command
This function should return the text to return to the client (or “” to use the default VPOP3 text)
=====DoNOOP()=====
DoNOOP()
This function is called by VPOP3 when it receives a NOOP command
This function should return the text to return to the client (or “” to use the default VPOP3 text)
=====DoRSET()=====
DoRSET()
This function is called by VPOP3 when it receives a RSET command
This function should return the text to return to the client (or “” to use the default VPOP3 text)
=====DoMAILFROM()=====
DoMAILFROM(“<data>”, “<mailfrom>”, <parameters>)
This function is called by VPOP3 when it receives a valid MAIL FROM command
The <data> is the raw data after the MAIL FROM: commandDoRCPTTO(“<data>”, “<recipient>”, <parameters>, <recipient list>)
This function is called by VPOP3 when it receives a valid RCPT TO command
The <data> is the raw data after the RCPT TO: commandDoDATAStart(<recipient list>)
This function is called by VPOP3 when it receives a valid DATA command
The <recipient list> is a table containing the list of recipient email addresses for this message
This function should return <SMTP Result string>, <Header lines to ADD to the start of the message header>
=====DoUnrecognised()=====
DoUnrecognised(<line>)
This function is called by VPOP3 when it receives a command it doesn't recognise
The <line> is a raw command line that VPOP3 received
This function should return <SMTP Result string>**
ProcessMessage(“<mailfrom>”, “<subject>”, <recipient list>, <current actions>, <message MIME structure>, <message size>, <attachments>)
This function is called by VPOP3 when a message has been received by the SMTP service.
In <actions>, 'Delete' is implied for all SMTP messages (it's not possible to not delete a mesage). If Delete and Ignore are both TRUE then the message is rejected with a 5xx SMTP error code. If Ignore is TRUE, but Delete is FALSE, then the message is accepted, but not processed (ie 'blackholed')
This function should return <new actions table>, <results string>
In this function the VPOP3 ProcessMessage helper functions can be used.
End()
This function is called by VPOP3 when the SMTP service session ends