Table of Contents

SMTP Server Lua Scripting

The SMTP Server Lua Script is called SMTPSVR.LUA and can be edited from the Settings → Scripts page in the VPOP3 settings. 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:

SMTP Server Global Variables

The following variables are defined for the SMTP Server Lua script. They are accessible to all callback functions in the script, and can often be modified by the script to modify the VPOP3 behaviour.

If the variable is marked as (IN) then it should be treated as read-only by the script. If it is marked as (IN/OUT) then the script can modify it if desired.

V5 and later

V6 and later

V6.5 and later

In VPOP3 Enterprise Only

V7.10 and later

SMTP Server "Start()"

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:

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.
The <current capabilities> value is the current capabilities string which will be returned to the SMTP client

This function should return the new capabilities string (see the relevant RFCs for the syntax)

DoHELO()

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.
The <bRefuse> value is if VPOP3 is going to refuse this SMTP connection already
The <bEHLO> value is TRUE if this function is being called after a EHLO command, or FALSE if it's being called after a HELO command

This function should return <bRefuse>, “<response string>“

DoHELP()

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)

DoVRFY()

DoVRFY(<recipient list>, “<current response>)

This function is called by VPOP3 when it receives a VRFY command

The 'Recipient list' contains the expanded list of recipients which the command's parameter expands to. The 'current response' contains the response which VPOP3 would return if the script doesn't exist.

This function should return the text to return to the client (return the value of the <current response> parameter to return VPOP3's normal response)

DoEXPN()

DoEXPN(<recipient list>, ”<current response>)

This function is called by VPOP3 when it receives a EXPN command

The 'Recipient list' contains the expanded list of recipients which the command's parameter expands to. The 'current response' contains the response which VPOP3 would return if the script doesn't exist.

This function should return the text to return to the client (return the value of the <current response> parameter to return VPOP3's normal response)

DoMAILFROM()

DoMAILFROM(“<data>”, “<mailfrom>”, <parameters>, “<SPF Result>”, “<Auth Sender>”)

This function is called by VPOP3 when it receives a valid MAIL FROM command

The <data> is the raw data after the MAIL FROM: command
The <mailfrom> is the address after the MAIL FROM: command
The <parameters> is a table of parameters to the MAIL FROM: command (if any) with the table entry key being the parameter name and the table entry value being the parameter value
The <SPF Result> is the result (pass, fail, softfail, etc) of the SPF check (if any) on the connection (in v5 and later).

This function should return <new parameters>, <SMTP Result string>

Starting in version 5, the script can add a new 'parameter' with name 'MAILFROM' and a new value for the return path to be used by VPOP3.

DoRCPTTO()

DoRCPTTO(“<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: command
The <recipient> is the address after the RCPT TO: command
The <parameters> is a table of parameters to the RCPT TO: command (if any) with the table entry key being the parameter name and the table entry value being the parameter value
The <recipient list> is a table containing the list of recipient email addresses for this message so far (not including this one)

This function should return <new parameters>, <SMTP Result string>

DoDATAStart()

DoDATAStart(<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()

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 version 7.0 and later, the returned 'results string' is ignored)

In this function the VPOP3 ProcessMessage helper functions can be used.

CheckRecipients()

CheckRecipients(<Recipient List>, <To Recipients>, <Cc Recipients>, <Bcc Recipients>, “<Sender IP Address>”, “<Authenticated Sender>”, “<Sender Address>”, “Subject”, <locally sent>, <message size>

This function is called after the entire message has been received (so the message headers can be parsed by VPOP3) and allows a script to check that the recipients, and recipient types (eg Bcc) are allowed for this message

This function should return either nothing, or a 4xx/5xx error response to return to the email client if the message is to be rejected

End()

End()

This function is called by VPOP3 when the SMTP service session ends