# Proxy This advanced and powerful script can be executed before an SMTP command is sent to the internal state machine of the SMTP server (hence before the command is processed by the SMTP server). It can be used to build custom SMTP commands or modify the current command line before processing. ## 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](#v-a8) | array | yes | Context/hook arguments | | [$connection](#v-c8) | array | yes | Connection/session bound | | [$transaction](#v-t8) | array | yes | Transaction bound | | $context | any | no | Connection bound user-defined (default none) | ### Arguments | Array item | Type | Example | Description | |--------------|--------|--------------------------|------------------------------| | command | string | `"XCLIENT ADDR=1.1.1.1"` | The SMTP command line issued | ### Connection | Array item | Type | Example | Description | |-----------------------------------------------------|--------|-----------------------------|----------------------------------------------------------| | id | string | `"18c190a3-93f-47d7-bd..."` | ID of the connection | | priority | number | `1` | The connection priority | | 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](#he8) | array | | HELO information (not always available) | | [tls](#tls8) | array | | TLS information (if TLS was started) | | [auth](#au8) | array | | AUTH information (not always available) | #### HELO | Array item | Type | Example | Description | |--------------|--------|----------------------|----------------------| | verb | string | `"EHLO"` | HELO or EHLO command | | host | string | `"mail.example.com"` | HELO hostname | #### 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](#p8) | array | | The peer certificate (if provided by the client) | ##### Peercert | Array item | Type | Example | Description | |--------------|--------------|-----------|------------------------------------------------------------------------------------------------------| | x509 | X509Resource | | An X509Resource to be used with the [`X509`](functions.html.md#X509) class | | chain | array | | An array of X509Resource (the chain) | | error | number | `18` | The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3)) | #### AUTH | Array item | Type | Example | Description | |--------------|--------|--------------|--------------------------------------| | mechanism | string | `"PLAIN"` | SASL mechanism (always in uppercase) | | username | string | `"mailuser"` | SASL username (not always available) | ### 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](#a8) | 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" => "test@example.com", ...], ...]` | List of all accepted [recipients](#v-t-r8) (envelope), in order of scanning | #### Recipient | Array item | Type | Example | Description | |--------------------------------------------------------|--------|------------------------------|---------------------------------------------------------------------------------| | recipient | string | `"test@example.com"` | Recipient address (envelope), lowercase | | [address](#a8) | 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 | #### Address | Array item | Type | Example | Description | |--------------|--------|-----------------|------------------------| | localpart | string | `"test"` | Local part of address | | domain | string | `"example.org"` | Domain part of address | ## Functions ### 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`. > * **priority** (number) Change the connection priority (0 normal, 1 high). ### 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 associative array may contain the properties *code* (number) and *enhanced* (array of three numbers). To remove the *enhanced* code set it to `[0,0,0]`. The default is pre-defined. > * **next** (boolean) Request to get the next command as well. The default is `false`. > * **priority** (number) Change the connection priority (0 normal, 1 high). ### Next([options]) Request to get the next line from the client to the proxy hook, without sending any data back to the client. * **Parameters:** **options** (*array*) – an options array * **Returns:** doesn’t return, script is terminated The following options are available in the options array. > * **priority** (number) Change the connection priority (0 normal, 1 high). ## On script error On script error [`Reply()`](#proxy.Reply) is called with a generic 421 response. ## On implicit termination If not explicitly terminated then [`Pass()`](#proxy.Pass) is called.