7.2. Proxy

This advanced and powerful script is can be executed before an SMTP command is sent to the internal state machine of the SMTP server (hence before the command is procesed by the SMTP server). It can be used to built custom SMTP commands or modify the current command line before processing.

7.2.1. Variables

These are the read-only arguments available for each command. Depending on when the proxy script is executed, the different objects may contain different information.

Variable	Type	Read-only	Description
$arguments	array	yes	Context/hook arguments
$connection	array	yes	Connection/session bound
$transaction	array	yes	Transaction bound
$context	any	no	Connection bound user-defined (default none)

7.2.1.1. Arguments

Array item	Type	Example	Description
command	string	“XCLIENT ADDR=1.1.1.1”	The SMTP command line issued

7.2.1.2. Connection

Array item	Type	Example	Description
id	string	“18c190a3-93f-47d7-bd…”	ID of the connection
remoteip	string	“192.168.1.11”	IP address of the connected client
remoteport	number	41666	TCP port of connected client
remoteptr	string	“mail.example.org”	Reverse DNS (FCrDNS) for remoteip (not always available)
remoteuid	number	106	UNIX socket remote user id (not always available)
localip	string	“10.0.0.1”	IP address of the server
localport	number	25	TCP port of the server
serverid	string	“inbound”	ID of the server
helo	array		HELO information (not always available)
tls	array		TLS information (if TLS was started)
auth	array		AUTH information (not always available)

7.2.1.2.1. HELO

Array item	Type	Example	Description
verb	string	“EHLO”	HELO or EHLO command
host	string	“mail.example.com”	HELO hostname

7.2.1.2.2. TLS

Array item	Type	Example	Description
protocol	string	“TLSv1.3”	The protocol
cipher	string	“ECDHE-RSA-AES256-SHA384”	The cipher
keysize	number	256	The keysize
sni	string	“example.com”	The SNI hostname (not always available)
peercert	array		The peer certificate (if provided by the client)

7.2.1.2.2.1. Peercert

Array item	Type	Example	Description
x509	X509Resource		An X509Resource to be used with the X509 class
error	number	18	The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3))

7.2.1.2.3. AUTH

Array item	Type	Example	Description
mechanism	string	“PLAIN”	SASL mechanism (always in uppercase)
username	string	“mailuser”	SASL username (not always available)

7.2.1.3. Transaction

Array item	Type	Example	Description
id	string	“18c190a3-93f-47d7-bd…”	ID of the transaction
sender	string	“test@example.org”	Sender address (envelope), lowercase
senderaddress	array	[“localpart” => “examp…]	Sender address (envelope)
senderparams	array	[“SIZE” => “2048”, … ]	Sender parameters to the envelope address (keys will always be in uppercase)
recipients	array	[recipient, …]	List of all accepted recipients (envelope), in order of scanning

7.2.1.3.1. Recipient

Array item	Type	Example	Description
recipient	string	“test@example.com”	Recipient address (envelope), lowercase
address	array	[“localpart” => “examp…]	Recipient address (envelope)
params	array	[“NOTIFY” => “NEVER”, .. ]	Recipient parameters to the envelope address (keys will always be in uppercase)
transportid	string	“inbound”	Transport ID for recipient

7.2.1.3.2. Address

Array item	Type	Example	Description
localpart	string	“test”	Local part of address
domain	string	“example.org”	Domain part of address

7.2.2. Functions

proxy.Pass([options])

Pass the command to the SMTP server’s state machine.

Parameters

options (array) – an options array

Returns

doesn’t return, script is terminated

The following options are available in the options array.

• command (string) Change the SMTP command.

• next (boolean) Request to get the next command as well. The default is false.

proxy.Reply([reason[, options]])

Send a reply to the client (The default is code 250). The command is not passed to the SMTP server’s state machine.

Parameters

• reason (string or array) – the message to reply

• options (array) – an options array

Returns

doesn’t return, script is terminated

The following options are available in the options array.

• disconnect (boolean) Disconnect the client. The default is false.

• reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.

• next (boolean) Request to get the next command as well. The default is false.

7.2.3. On script error

On script error Reply() is called with a generic 421 response.

7.2.4. On implicit termination

If not explicitly terminated then Pass() is called.