8.1. Pre-delivery

The pre-delivery script is executed just before an email is being put into the active queue (for delivery as soon as the active queue policies allow).

8.1.1. Variables

These are the pre-defined variables available.

Variable	Type	Read-only	Description
$arguments	array	yes	Context/hook arguments
$message	array	yes	The queued message
$context	any	no	Delivery attempt-bound variable. It is only passed between pre and post-delivery.

8.1.1.1. Arguments

Array item	Type	Example	Description
retry	number	3	The current retry
queue	array	[“plugin” => [“return”…]	The queue plugin data (not always available)

8.1.1.1.1. Queue

Array item	Type	Example	Description
plugin	array	[“return” => “plugin data”]	Custom queue plugin return value (not always available)

8.1.1.1.1.1. Plugin

Array item	Type	Example	Description
return	any	“plugin return value”	Any type passed from custom queue plugin

8.1.1.2. Message

Array item	Type	Example	Description
id	array	[“transaction” => “18…”	ID of the message
ts	number	1575558785.1234	Unix time of transaction
serverid	string	“inbound”	ID of the server
sender	string	“test@example.org”	Sender address (envelope), lowercase
senderaddress	array	[“localpart” => “test”…]	Sender address (envelope)
recipient	string	“test@example.org”	Recipient address (envelope), lowercase
recipientaddress	array	[“localpart” => “test”…]	Recipient address (envelope)
transportid	string	“inbound”	ID of the transport profile to be used
tenantid	string	“customidentifier1”	Tenant ID of the message
jobid	string	“jobidentifier1”	Job ID of the message
priority	number	1	The queue priority
size	number	412311	Message size in bytes
file	array	[“original” => …,]	The message file
dsn	array	[“envid” => …,]	The message DSN options

8.1.1.2.1. Id

Array item	Type	Example	Description
transaction	string	“18c190a3-93f-47d7-bd…”	ID of the transaction
queue	number	1	Queue ID of the message

8.1.1.2.2. Address

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

8.1.1.2.3. File

Array item	Type	Example	Description
original	FileResource		An FileResource to be used with the File class
modified	FileResource		An FileResource to be used with the File class

8.1.1.2.4. DSN

Array item	Type	Example	Description
envid	string	“abcdef@example.com”	The DSN ENVID
ret	string	“HDRS”	The DSN RET (HDRS or FULL)
notify	array	“SUCCESS,FAILURE”	The DSN NOTIFY options (NEVER, SUCCESS, FAILURE or DELAY)
orcpt	string	“recipient@example.org”	The DSN ORCPT recipient address

8.1.2. Functions

predelivery.Try([options])

Accept the email into the active queue (for delivery as soon as the active queue policies allow). This is the default action.

Parameters

options (array) – an options array

Returns

doesn’t return, script is terminated

The following options are available in the options array. Some are used to override the properties otherwise chosen based on the email’s metadata and transport settings.

• transportid (string) Change the transport ID. The default is the current transportid.

• server (string or array) The destination IP-address or hostname as a string, or an associative array with host (string) and mx (boolean). Overrides the transport setting.

• port (number) TCP port to connect to. Overrides the transport setting.

• sender (string or array) Change the sender email address, either as a string or an associative array with a localpart, domain and params. Overrides the queued email’s metadata.

• recipient (string or array) Change the recipient email address, either as a string or an associative array with a localpart, domain and params. Overrides the queued email’s metadata.

• helo (string) The SMTP HELO/EHLO hostname. It can also be specified per source IP. Overrides the transport setting.

• sourceip (array) Source (local) IP(s) to use. The array may contain either strings (of ID’s) or associative arrays with id, address (literal), helo and proxyprotocol. The proxyprotocol setting uses the same format as proxyprotocol in the root options array. Overrides the transport setting.

• sourceip_random (boolean) The order in which to choose non suspended sourceips. The default is true.

• nonlocal_source (boolean) Allow binding of non-local addresses (BINDANY). The default is false.

• saslusername (string) If specified issue a AUTH LOGIN before MAIL FROM. Overrides the transport setting.

• saslpassword (string) If specified issue a AUTH LOGIN before MAIL FROM. Overrides the transport setting.

• saslmechanism (string) If specified issue the SASL mechanism and the saslpassword (used for eg. XOAUTH2).

• tls (string) Use any of the following TLS modes; disabled, optional, optional_verify, dane, dane_fallback_require, dane_fallback_require_verify, dane_require, require or require_verify. Overrides the transport setting.

• tls_implicit (boolean) Use implicit TLS (do not use STARTTLS). The default is false.

• tls_sni (string or boolean) Request a certificate using the SNI extension. If true the connected hostname will be used. The default is not to use SNI (false).

• tls_protocols (string) Use one or many of the following TLS protocols; SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3. Protocols may be separated by , and excluded by !. The default is !SSLv2,!SSLv3.

• tls_ciphers (string) List of ciphers to support. The default is decided by OpenSSL for each tls_protocol.

• tls_ciphersuites (string) List of TLS ciphersuites to support (TLSv1.3). The default is decided by OpenSSL for each tls_protocol.

• tls_verify_host (boolean) Verify certificate hostname (CN). The default is false.

• tls_verify_name (array) Hostnames to verify against the certificate’s CN and SAN (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).

• tls_client_cert (array or string) If given as an associative array it should include a x509 (X509Resource), privatekey (*PrivateKeyResource) and optionally a chain (array) of X509Resources. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.

• xclient (array) Associative array of XCLIENT attributes to send.

• chunking (boolean) Enable CHUNKING support. Overrides the transport setting.

• pipelining (boolean) Enable PIPELINING support. Overrides the transport setting.

• protocol (string) The protocol to use; smtp or lmtp. Overrides the transport setting.

• mx_include (array) Filter the MX lookup result, only including ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).

• mx_exclude (array) Filter the MX lookup result, removing ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).

• mx_exclude_bypass (array) Before applying mx_exclude, allow the once matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).

• ip_exclude (array) Filter the IP addresses or networks, removing addresses listed.

• ip_exclude_temporary (boolean) Specify if empty results due to filtered IP or MX addresses should result in a temporary or permanent error. The default is false (permanent error).

• tenantid (string) Set tenantid of the message.

• jobid (string) Set jobid of the message.

• priority (number) The queue priority (0 - normal, 1 - high). The default is 0.

• during (number) Set the message duration in seconds relative to the current time. The default is either choosen by the transport or automatically assigned.

• timeout (array) Associative array of state and the timeout in seconds. The default is set according to RFC2821.

• connect_timeout (number) The connect timeout in seconds. The default is 30 seconds.

• pooling (boolean) Enable connection pooling. The default is false.

• proxyprotocol (array) Associative array of server (IP) and port as well as local sourceip to use when using an outbound PROXY PROTOCOL server.

• dsn (array) Associative array of envid (string), ret (string), notify (string), orcpt (string) and success (string) which may be set to “delivered” to send delivered notification instead of “relayed” (default) whenever applicable.

• additional_headers (array) Add additional headers to be sent (in the format of header-name: header-value, no encoding or folding is done). This can be useful to add per retry headers.

• plugin (array) Associative array of id (string), arguments (any type) to enable custom delivery plugins.

predelivery.Queue([options])

Queue the message to be retried later.

Parameters

options (array) – options array

Returns

doesn’t return, script is terminated

The following options are available in the options array.

• hold (boolean) Put the message in the hold (inactive) queue. The default is false.

• priority (number) The queue priority (0 - normal, 1 - high). The default is 0.

• delay (number) the delay in seconds. The default is according to the current transports retry delay.

• reason (string) Optional message to be logged with the message.

• increment_retry (boolean) If the retry count should be increased. The default is true.

• reset_retry (boolean) If the retry count should be reset to zero. The default is false.

• transportid (string) Set the transport ID. The default is the current transportid.

• quotas (array) An array of quotas to be associated with the message, for use with queue_quota().

• tenantid (string) Set tenantid of the message.

• jobid (string) Set jobid of the message.

Note

It’s possible to forcefully queue the message exceeding its max retry.

predelivery.Bounce([options])

Skip the delivery attempt and execute the post-delivery context with $arguments["action"] set to BOUNCE. By default this will delete the message from the queue, and generate a DSN (bounce) to the sender.

Parameters

options (array) – options array

Returns

doesn’t return, script is terminated

The following options are available in the options array.

• dsn (array) The DSN settings.

The following options are available in the dsn array.

• transportid (string) Set the transport ID. The default is either choosen by the transport or automatically assigned.

• recipient (string or array) Set the recipient of the DSN, either as a string or an associative array with a localpart and domain.

• metadata (array) Add additional metadata (KVP) to the DSN.

• from (string or array) Set the From-header address of the DSN, either as a string or an associative array with a localpart and domain.

• from_name (string) Set the From-header display name of the DSN.

• dkim (array) Set the DKIM options of the DSN (selector, domain, key including the options available in MIME.signDKIM()).

• tenantid (string) Set tenantid of the message.

• jobid (string) Set jobid of the message.

• priority (number) The queue priority (0 - normal, 1 - high). The default is 0.

• subject (string) A custom subject.

• subject_prepend (string) A custom string to append to the subject line (in addition to the original subject).

• headers (array) Array of additional headers to append to the DSN.

• readable_mimepart (string) A full MIME part to be included as the human readable part of the DSN.

• ret (string) Include either FULL (message), HDRS (headers only) or false (do not include the original message) in bounces. The default is HDRS.

• modified_original (boolean) Included original message headers as modified by end-of-DATA script. The default is false (as received).

• fields (array) Override the original reportingmta (string), receivedfrommta (string), remotemta (string), status (array of three numbers), diagnosticcode (string), diagnostictype (string) and finalrecipient (address) fields.

• additional_fields (array) Array of additional fields to append to the DSN.

• additional_recipient_fields (array) Array of additional fields to append to the per recipient fields in the DSN.

if ($message["recipientaddress"]["localpart"] == "no-reply")
{
   Bounce(["dsn" => [
       "from_name" => "The Postmaster" // change postmaster address
   ]]);
}

Note

If the message has a null return path (empty sender) or the transport has DSN disabled, it will run the post-delivery with DELETE instead.

predelivery.Delete([options])

Skip the delivery attempt and execute the post-delivery context with $arguments["action"] set to DELETE, and optional populate $arguments["dsn"]["diagnosticcode"] with a reason. By default this will delete the message from the queue, without generating a DSN (bounce) to the sender.

Parameters

options (array) – an options array

Returns

doesn’t return, script is terminated

The following options are available in the options array.

• reason (string) The reason for deletion. The default is a system generated message.

predelivery.SetMetaData(metadata)

This function updates the queued message’s metadata the hqf file. It is consequentially remembered for the next retry. The metadata must be an array with both string keys and values.

Parameters

metadata (array) – metadata to set

Return type

none

Note

To work-around the data type limitation of the metadata; data can be encoded using json_encode(). Key names starting with a “_” (underscore) is reserved for Halon’s internal use.

predelivery.GetMetaData()

Get the metadata set by SetMetaData(). If no data was set, an empty array is returned.

Returns

the data set by SetMetaData()

Return type

array

8.1.3. On script error

On script error Queue(["delay" => 300, "increment_retry" => false]) is called.

8.1.4. On implicit termination

If not explicitly terminated then Try() is called.