7.7. Post-delivery

The post-delivery script is executed after a delivery attempt or when a message is deleted or bounced from the queue. If the message was deleted from the queue (either manually or by retention) the $context variable will not be defined.

7.7.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” E-mail address of sender (envelope)
$senderdomain string “example.org” Domain part of sender’s address (envelope)
$recipient string “test@example.com” E-mail address of recipient (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.7.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 transportid. 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 transportid. The default is either choosen by the transport or automatically assigned.
  • recipient (string) Set the recipient. The default is $sender.
  • metadata (array) Add additional metadata to the DSN (KVP).
postdelivery.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().

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

Return a File class to the current mail file.

Returns:A File class to the current mail file.
Return type:File

Note

The file is returned in an unmodified state as received (only with a Recieived header applied).

7.7.3. On script error

On script error the default action is taken.

7.7.4. On implicit termination

If not explicitly terminated then the default action is taken.