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

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

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.

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

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

  • 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_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_default_ca (boolean) Load additional TLS certificates (ca_root_nss). The default is false.

  • tls_client_cert (string) Use the following pki:X 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.

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

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

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

  • jobid (string) Job ID of the message.

  • 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 of and 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.

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.

  • 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 the current transportid.

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

Note

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

predelivery.Bounce()

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.

Returns

doesn’t return, script is terminated

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

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

Returns

doesn’t return, script is terminated

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

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.