7.8. Post-delivery¶

7.8.1. Pre-defined variables¶

These are the read-only pre-defined variables available each time after a delivery attempt is made.

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
$serverip	string	“172.16.1.25”	IP which we tried to connect to (empty on DNS problems)
$serverport	number	25	Port which we tried to connect to
$senderip	string	“192.168.1.11”	IP address of the sender
$saslusername	string	“mailuser”	SASL username
$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)
$retry	number	3	The current retry count
$retries	number	30	The maximum number of retries for that message
$errormsg	string	“5.7.1... we do not relay”	The error message from the server
$errorcode	number	550	The error code from the server (A value 0 of indicates network problems)
$errorndr	string	“5.7.1”	The NDR code from the server (if available)
$transfertime	number	0.512	The transfer time for this delivery attempt (seconds)
$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
$transportid	string	“mailtransport:1”	ID of the transport profile that was used
$action	string	“DELETE”	The default action of this execution (“DELETE”, “BOUNCE”, “RETRY” or “”)
$context	any	none	This variable is only defined if the pre-delivery context has been executed

7.8.2. Functions¶

postdelivery.Bounce()¶

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

Returns:	doesn’t return, script is terminated

Warning

If the message was delivered ($action == "") this function will raise a runtime error.

postdelivery.Delete()¶

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

Returns:	doesn’t return, script is terminated

Warning

If the message was delivered ($action == "") this function will raise a runtime error.

postdelivery.Retry([options])¶

Retry the message again later. This is the default action for non-permanent (5XX) $errorcode‘s. If the maximum retry count is exceeded; the message is either bounced or deleted depending on the transport’s settings.

Parameters:	options (array) – options array
Returns:	doesn’t return, script is terminated

The following options are available in the options array.

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

Warning

If the message was delivered ($action == "") this function will raise a runtime error.

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

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

postdelivery.GetTLS([options])¶

Get the TLS information for the delivery attempt.

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

The following options are available in the options array.

• fingerprint (string) Generate the fingerprint of the certificate using one of the following hash function (md5, sha1, sha256 or sha512). The default no hashing.

The following items are available in the result.

• started (boolean) If STARTTLS was issued.
• protocol (string) The protocol used (eg. TLSv1.2)
• ciphers (string) The cipher used (eg. ECDHE-RSA-AES256-SHA384).
• keysize (number) The keysize used (eg. 256).
• peer_cert (array) The peer certificate (if requested by predelivery.SetTLS()). Same format as TLSSocket.getpeercert().
• tlsrpt (string) TLS reporting result.

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

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

7.8.3. On script error¶

On script error the default action is taken.

7.8.4. On implicit termination¶

If not explicitly terminated then the default action is taken.