7.5. Pre-delivery

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

7.5.1. Pre-defined variables

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

Variable Type Example Description
$receivedtime number 1445937340 The unix time (in UTC) when the message was received
$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)
$senderip string “192.168.1.11” IP address of the sender
$senderhelo string “mail.example.com” HELO message of sender
$saslusername string “mailuser” SASL username
$sender string “test@example.org” E-mail address of sender
$senderdomain string “example.org” Domain part of sender’s address
$recipient string “test@example.com” E-mail address of recipient
$recipientdomain string “example.com” Domain part of recipient’s address
$retry number 3 The current retry count
$retries number 30 The maximum number of retries for that message
$messageid string “18c190a3-93f-47d7-bd...” ID of the message
$actionid number 1 Same as $actionid in DATA context
$queueid number 12345 Queue ID of the message
$serverid string “mailserver:1” ID of the mailserver profile
$transportid string “mailtransport:1” ID of the transport profile that is used

7.5.2. Functions

predelivery.Try()

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

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.
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
if (CurrentConnections("to-domain", $recipientdomain, 3) == false)
                Reschedule(rand(1, 30), [
                            "reason" => "Too many concurrent connections for this domain",
                            "increment_retry" => false
                    ]);
    Try();
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) – a hostname or IP-address
  • port (number) – the TCP port to use
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. The default is disabled.
  • tls_protocols (string) Use one or many of the following TLS protocols; SSLv1, SSLv2, TLSv1, TLSv1.1 or TLSv1.2. 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.
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.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(netaddr[, options])

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

Parameters:
  • netaddr (string) – the netaddr:X to use
  • options (array) – options array
Return type:

none

Updates:

$sourceip to the actual IP address of netaddr:X

The following options are available in the options array.

  • nonlocal_source (boolean) if the system setting ‘system_nonlocal_source’ is enabled, netaddr may be an IP. The default is false.
predelivery.SetSender(sender)

Set the sender MAIL FROM for the current delivery attempt (it is not remembered for the next retry).

Parameters:sender (string) – an e-mail address
Return type:none
Updates:$sender and $senderdomain
predelivery.SetRecipient(recipient)

Set the sender RCPT TO for the current delivery attempt (it is not remembered for the next retry).

Parameters:recipient (string) – an e-mail address
Return type:none
Updates:$recipient and $recipientdomain
predelivery.SetMetaData(metadata)

This function sets the metadata for the current message. 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

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
senderip $senderip
saslusername $saslusername
sender $sender
senderdomain $senderdomain
recipientdomain $recipientdomain
transportid $transportid
retry 1
$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.

7.5.3. On script error

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

7.5.4. On implicit termination

If not explicitly terminated then Try() is called.