Lua SMTP MX Control

Every time VPOP3 is going to send messages using direct MX sending, it runs a script called mxout.lua which can be created/edited in Settings → Scripts (or in the VPOP3 directory in VPOP3 v6.6 or earlier).

For every message which is to be sent VPOP3 calls a function in that script called CheckFile.

The function signature is: CheckFile(Filename, Actions, Size, CreationTime, Retries, LastTryTime, ReturnPath, Recipients, HeaderData, HeaderLines)

• Filename - the filename on disk
• Actions - An object containing the values: ForceLastTry, 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
• Retries - The number of times VPOP3 has tried to send the message so far
• LastTryTime - The time the message was last attempted - 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 four values:

• ForceLastTry - if this is true, then this attempt of the message will be the last time. If false, then the retry scheme will progress as normal. 'SkipSend' must be false for this to take effect.
• 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.

If you need to tweak how VPOP3 connects to remote servers you can write a ServerDetails function. VPOP3 calls this function before sending each message.

(This function was added in VPOP3 v6.5)

The function signature is: ServerDetails(Parameters, HeaderLines, Actions)

The Parameters object contains details of the message being sent:

• authsender - the authenticated sender (if any) that sent the message to VPOP3
• originator - the email address that sent the message to VPOP3
• server - the mail server being connected to
• domain - the domain the message is being sent to
• length - the size of the message being sent
• connnid - the VPOP3 Connection/Sender ID
• connection - the VPOP3 Connection/Sender name

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 contains 9 or more values:

• tryESMTP - boolean to say whether VPOP3 should try to use ESMTP when connecting. If false, VPOP3 will just try SMTP. The default is true, where VPOP3 will attempt ESMTP and try to fallback to SMTP if the remote server doesn't support ESMTP
• tryTLS - boolean to say whether VPOP3 should use TLS if the remote server claims to support it
• HELOname - the text name to use when VPOP3 sends the HELO or EHLO command
• useBATV - whether VPOP3 should use BATV translation when sending the message
• timeouts - a list of timeouts for the session
• returnAddressModifier - should the return address be modified by VPOP3
• defaultReturnAddress - the return address to use if VPOP3 modifies it
• nullReturnAddress - the return address to use if VPOP3 should send a null return address
• allowDSN - boolean to indicate whether VPOP3 should use DSN if the remote server claims to support it

Starting with VPOP3 v6.17 it also contains:

• forceTLS - 1/0 to indicate that STARTTLS connection is forced. Connection fails if STARTTLS is not supported or fails
• verifyCert - 1/0 to indicate that the TLS certificate should be verified after connection. The connection will fail if verification fails
• checkCertName - wildcard string to check against the TLS certificate CN. The connection will fail if the CN doesn't match (case insensitive)
• checkCertThumbprint - string to check against the TLS certificate SHA-1 thumbprint. The connection will fail if the thumbprint doesn't match (case insensitive)

Example - don't use SSL when connecting to 'mail.broken.com'

function ServerDetails(params, headers, actions)
  if params["server"] == "mail.broken.com" then
    actions["tryTLS"] = 0
  end
  return actions
end

(VPOP3 8.0 and later)

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