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

jobid

string

“customidentifier1”

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 or address (literal) and helo. 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).

  • jobid (string) Job ID of the message.

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

  • 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().

  • jobid (string) Set ID 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()).

  • jobid (string) Job ID 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.

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.