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.