8.1. Pre-delivery

The pre-delivery script is executed just before a delivery attempt of a message that is being picked up from the queue.

8.1.1. Variables

These are the read-only pre-defined variables available. Some of them can be changed using the functions below.

8.1.1.1. Original message

These variables are related to the queued message.

8.1.1.1.1. Connection

Variable Type Example Description
$senderip string “192.168.1.11” IP address of the sender
$serverid string “mailserver:1” ID of the server the message was recevied on
$senderhelo string “mail.example.com” HELO hostname of sender
$saslusername string “mailuser” SASL username

8.1.1.1.2. Transaction

Variable Type Example Description
$messageid string “18c190a3-93f-47d7-bd...” ID of the message
$sender string “test@example.org” Email address of sender (envelope), lowercase
$senderlocalpart string “test” Local part of sender’s address (envelope)
$senderdomain string “example.org” Domain part of sender’s address (envelope)
$recipient string “test@example.com” Email address of recipient (envelope), lowercase
$recipientlocalpart string “test” Local part of recipient’s address (envelope)
$recipientdomain string “example.com” Domain part of recipient’s address (envelope)
$receivedtime number 1445937340 The unix time (in UTC) when the message was received
$actionid number 1 Same as $actionid in DATA context

8.1.1.2. Queue

Variable Type Example Description
$transportid string “mailtransport:1” ID of the transport profile assigned
$queueid number 12345 Queue ID of the message
$retry number 3 The current retry count
$retries number 30 The maximum number of retries for that message

8.1.1.3. Arguments

Variable Type Example Description
$sourceip string “10.0.0.1” The delivery source IP (initially defined by the transport profile)
$destination string “172.16.1.25” The destination host (initially defined by the transport profile)
$destinationport number 25 The destination port (initially defined by the transport profile)

These are the writable pre-defined variables available.

Variable Type Description
$context any Delivery attempt-bound variable. It is only passed between pre and post-delivery.

8.1.2. Functions

predelivery.Try()

Try to deliver the message now. This is the default action.

Returns:doesn’t return, script is terminated
predelivery.Bounce()

Delete the message from the queue, and generate a DSN (bounce) to the sender.

Returns:doesn’t return, script is terminated
predelivery.Delete()

Delete the message from the queue, without generating a DSN (bounce) to the sender.

Returns:doesn’t return, script is terminated
predelivery.Reschedule(delay[, options])

Reschedule the message for delay seconds.

Parameters:
  • delay (number) – delay in seconds
  • options (array) – options array
Returns:

doesn’t return, script is terminated

The following options are available in the options array.

  • 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 $transportid.
predelivery.CurrentConnections(namespace, entry, max)

Can be used to limit concurrency. It returns false of the current number of connections with the same entry name in that namespace exceeds max, and true otherwise. The function will also occupy one “slot” after being executed, over the duration of its delivery attempt.

Parameters:
  • namespace (string) – the namespace
  • entry (string) – the entry
  • max (number) – the maximum concurrency
Return type:

boolean

if (CurrentConnections("to-domain", $recipientdomain, 3) == false) {
        Reschedule(rand(1, 30), [
                "reason" => "Too many concurrent connections for this domain",
                "increment_retry" => false
        ]);
}
predelivery.SetDestination(host[, port])

Set the host and port for the current delivery attempt. It is not remembered for the next retry.

Parameters:
  • host (string) – hostname or IP address
  • port (number) – the TCP destination port
Return type:

none

Updates:

$destination and $destinationport

predelivery.SetProtocol(protocol)

Set the protocol for the current delivery attempt. It is not remembered for the next retry.

Parameters:protocol (string) – smtp or lmtp
Return type:none
predelivery.SetTLS(options)

Set the TLS options for the current delivery attempt. It is not remembered for the next retry.

Parameters:options (array) – options array
Return type:none

The following options are available in the options array.

  • tls (string) Use any of the following TLS modes; disabled, optional, optional_verify, dane, dane_require, require or require_verify.
  • 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 SSL/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.
  • tls_capture_peer_cert (boolean) If set to true, the peer certificate will be available in the postdelivery.GetTLS() results. The default is false.
predelivery.SetSASL(username, password)

Set the SASL AUTH username and password for the current delivery attempt. It is not remembered for the next retry.

Parameters:
  • username (string) – username
  • password (string) – password
Return type:

none

predelivery.SetXCLIENT(attributes)

Send the following XCLIENT xclient attributes. It is not remembered for the next retry.

Parameters:attributes (array) – associative array of XCLIENT attributes to send
Return type:none
predelivery.SetHELO(hostname)

Set the HELO hostname for the current delivery attempt. It is not remembered for the next retry.

Parameters:hostname (string) – a hostname
Return type:none
predelivery.SetSourceIP(id[, options])

This function changes the source IP of the current delivery attempt. It is not remembered for the next retry.

Parameters:
  • id (string or array) – the IP address ID to use
  • options (array) – options array
Return type:

none

Updates:

$sourceip to the actual IP address of id

The following options are available in the options array.

  • nonlocal_source (boolean) If the system setting ‘system_nonlocal_source’ is enabled, id may be an IP. The default is false.

Note

If id is given as an array, only one item for each IP family may be given.

predelivery.SetSender(sender)

Set the sender MAIL FROM for the current delivery attempt. It is not remembered for the next retry.

Parameters:sender (string or array) – an email address, either as a string or a tuple with localpart and domain
Return type:none
Updates:$sender, $senderlocalpart and $senderdomain
predelivery.SetSenderParams(params)

Set the sender MAIL FROM params for the current delivery attempt. It is not remembered for the next retry.

Parameters:params (array) – key-value array of params
Return type:none
predelivery.SetRecipient(recipient)

Set the recipient RCPT TO for the current delivery attempt. It is not remembered for the next retry.

Parameters:recipient (string or array) – an email address, either as a string or a tuple with localpart and domain
Return type:none
Updates:$recipient, $recipientlocalpart and $recipientdomain
predelivery.SetRecipientParams(params)

Set the recipient RCPT TO params for the current delivery attempt. It is not remembered for the next retry.

Parameters:params (array) – key-value array of params
Return type:none
predelivery.SetDSN(options)

Set the DSN options for the current delivery attempt if a DSN were to be created. It is not remembered for the next retry.

Parameters:options (array) – options array
Return type:none

The following options are available in the options array.

  • transportid (string) Set the transport ID. The default is either choosen by the transport or automatically assigned.
  • recipient (string) Set the recipient. The default is $recipientlocalpart at $recipientdomain.
  • metadata (array) Add additional metadata (KVP) to the DSN.
  • from (string) Set the From-header address of the DSN.
  • 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()).
predelivery.SetMetaData(metadata)

This function updates the queued message’s metadata in the database. 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
predelivery.GetMailQueueMetric([options])

Return metric information about the mail queue, it can be used to enforce quotas.

Parameters:options (array) – options array
Return type:number

The following options are available in the options array.

  • metric (string) Metric to be returned; count or bytes. The default is count.
  • filter (array) Any of the available filters, see below. The default is no filters.

The following filters are available in the filters array.

Type Example
remoteip $connection[“remoteip”]
saslusername $connection[“auth”][“username”]
sender $transaction[“sender”]
senderdomain $transaction[“senderaddress”][“domain”]
recipient $transaction[“recipients”][0][“recipient”]
recipientdomain $transaction[“recipients”][0][“address”][“domain”]
transportid $transaction[“recipients”][0][“transportid”]
retry 1
metadata.x any metadata
$queuesize = GetMailQueueMetric(
        [
                "metric" => "bytes",
                "filter" => [
                        "senderdomain" => ["example.com" , "example.net"],
                        "transportid" => "mailtransport:2"
                ]
        ]
) / 1024 / 1024;
if ($queuesize > 500) {
        Defer("Current queue for mailtransport:2 exceeds 500 MiB");
}

Note

If multiple filters of the same type are given using array notation, any of them may match.

predelivery.GetMailFile([options])

Return a File class to the current mail file.

Parameters:options (array) – an options array
Returns:A File class to the current mail file.
Return type:File

The following options are available in the options array.

  • changes (boolean) Include changes done to the original message. The default is false.

8.1.3. On script error

On script error Reschedule(300) is called with increment_retry set to false.

8.1.4. On implicit termination

If not explicitly terminated then Try() is called.