Every time VPOP3 adds a message to the Outgoing mail queue, it runs a script called outmessage.lua.

Scripts are stored as files in the VPOP3 directory in VPOP3 v6.6 and earlier, or managed through the Settings → Scripts page in VPOP3 v6.7 and later.

See the Lua Scripting page for general details about VPOP3's scripting, and information on how we can help.

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

The function signature is: NewMessage(AuthenticatedSender, ReturnPath, CreationDate, Subject, SenderIPAddress, FileLength, Priority, Headers, Message, HoldSeconds, DeleteAfterSeconds)

• AuthenticatedSender - The VPOP3 username of the user who authenticated to send the message (if authentication wasn't used, this is blank).
• ReturnPath - The email address of the sender (strictly speaking, the SMTP return path/MAIL FROM address, which is where bounce messages will be sent).
• CreationDate - The time the message was created - as YYYYMMDDHHMMSS.
• Subject - The subject of the message.
• SenderIPAddress - The IP address of the message sender (if generated from within VPOP3/forwarded/etc, this will be blank).
• FileLength - The size of the message file - this will be slightly longer than the message itself because of control data, but can be used as an estimate.
• Priority - The current priority of the message. VPOP3 will send messages with a smaller priority number first.
• Headers - A list of the message header lines in raw form.
• Message - The message content in raw form (single string, includes raw headers).
• HoldSeconds - The current number of seconds the message will be held before being sent (0 = no time).
• DeleteAfterSeconds - The current number of seconds before the message will be deleted from the queue (0 = never).
• HoldTimeFromSender - The ISO-8601 time to hold to as defined at message send time (eg by 'FUTURERELEASE') (added in v8.6)
• DeleteTimeFromSender - The ISO-8601 time to delete the message at as defined at message send time (added in v8.6)

The function returns a table of new settings. This can contain the following fields. If the field doesn't exist, then the value is not changed.

• Priority - The new priority of the message. VPOP3 will send messages with a smaller priority number first.
• HoldReason - A reason to be logged in the database for why the message is held.
• Hold - If this is set to 'true', '1', 't', 'hold' then the message is held, otherwise it is not held.
• HoldUntil - If this is set to a string like YYYYMMDDHHMMSS then the message is held until that time, otherwise it is held for the specified number of seconds.
• DeleteAfter - If this is set to 'none', then it is never deleted. If this is set to a string like YYYYMMDDHHMMSS then the message will be deleted after that time, otherwise it will be deleted after the specified number of seconds.
• ReturnPath - (added in v8.6) - A new value for the ReturnPath (MAILFROM) of the message being sent

Example from a customer to change the ReturnPath depending on the 'From' address in the header

-- change ReturnPath with address-only according to address in From-Field
-- Copyright 2024 AT Software und Rechnertechnik GmbH Muenchen
-- last change 09.03.2024 AT/ath
function NewMessage(AuthenticatedSender, ReturnPath, CreationDate, Subject, SenderIPAddress, FileLength, Priority, Headers)
	actions = {}
	SenderAddressTo = "..."
	SenderSubject = "..."
	MessageHeadersChanged = false
	for k,v in pairs(Headers) do
		if string.upper(v[1]) == "SUBJECT" then
            SenderSubject = v[2]
            if not SenderSubject then SenderSubject = "..." end
		end
		if string.upper(v[1]) == "TO" then
		    SenderAddressTo = v[2]
            if not SenderAddressTo then SenderAddressTo = "..." end
		end
		if string.upper(v[1]) == "FROM" then
		    -- SenderAddressFrom = "Alexander <alexander@my-secondcompany.com>"
			SenderAddressFrom = v[2]
            if string.find(SenderAddressFrom, "@my%-secondcompany%.com") then
                JustTheAddress = string.match(SenderAddressFrom, " <%g*@my%-secondcompany%.com>")
                JustTheAddress = string.sub(JustTheAddress, 3, string.len(JustTheAddress)-1) -- remove trailing and ending brackets
                -- OldReturnPath = "alexander@firstcompany.com"
                OldReturnPath = ReturnPath
                -- actions["returnpath"] = "alexander@my-secondcompany.com"
                actions["returnpath"] = JustTheAddress
                MessageHeadersChanged = true
                print("Changed ReturnPath in message from '" .. SenderAddressFrom .. "' from '" .. OldReturnPath .. "' to '" .. JustTheAddress .. "' for message to '" .. SenderAddressTo .. "' with Subject '" .. SenderSubject .. "'")
			end
		end
    end
    if not MessageHeadersChanged then
        print("Nothing changed in message from '" .. SenderAddressFrom .. "' for message to '" .. SenderAddressTo .. "' with Subject '" .. SenderSubject .. "'")
    end
	return actions
end