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)