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

8.2.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 (with modifications from pre-delivery)
$context any no This variable is only defined if the pre-delivery has been executed

8.2.1.1. Arguments

Array item Type Example Description
retry number 3 The current retry
action string “DELETE” The default action of this execution (“DELETE”, “BOUNCE”, “QUEUE”). Missing on successful deliveries.
policy array [“tags” => [“backoff”] The pickup policy information (if an attempt was made)
attempt array [“result” => [ “code” => 200, ... The delivery attempt result (if an attempt was made)
dsn array [“action”=> “delayed”, ...] The DSN action and a DSN message id (if generated).

8.2.1.1.1. Policy

Array item Type Example Description
tags array [“backoff”, ...] The policy tags applied

8.2.1.1.2. Attempt

Array item Type Example Description
result array [“code” => 250, “enhanced” => [1, ...] A SMTP protocol response (if available)
error array [“temporary” => true, “reason” => ...] A generic eror message (if no SMTP result)
connection array [“localip” => “1.2.3.4”, “remoteip”...] Connection information
duration number 1.012 The delivery attempt duration
8.2.1.1.2.1. Result
Array item Type Example Description
code number 250 A SMTP status code
enhanced array [2, 0, 0] A SMTP enhanced status code
reason array [“Ok: queued as 18c19...”] A SMTP response text
state string “MAIL” An enum to indicate which issued SMTP command triggerd the result
8.2.1.1.2.2. Error
Array item Type Example Description
temporary boolean true If the error may be transient
message message “A generic error” An error message
8.2.1.1.2.3. Connection
Array item Type Example Description
localip string “1.2.3.4” The source IP used
remoteip string “4.3.2.1” The remote IP connected to
remotemx string “mail.example.com” The remotemx used
tls array [“started” => true, ...] TLS information (if TLS was started)
8.2.1.1.2.3.1. TLS
Array item Type Example Description
started boolean true If STARTTLS was successfully started
protocol string “TLSv1.3” The protocol (if available)
cipher string “ECDHE-RSA-AES256-SHA384” The cipher (if available)
keysize number 256 The keysize (if available)
peercert array   The peer certificate (if available)
tlsrpt string “starttls” The tlsrpt error (if available)
8.2.1.1.2.3.1.1. Peercert
Array item Type Example Description
x509 X509Resource   An X509Resource to be used with the X509 class

8.2.1.1.3. DSN

Array item Type Example Description
action string “delayed” DSN type to be generated (delayed, failed, relayed or delivered)
id array [“transaction” => “18...” ID of the DSN message to be generated

8.2.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.2.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.2.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.2.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.2.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.2.2. Functions

postdelivery.Queue([options])

Queue the message to be retried later. This is the default action for non-permanent (temporary) errors while the retry count isn’t exceeded. Permanent errors include 5xx SMTP responses, permanent DNS failures, etc.

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) Change 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().
  • dsn (array) The DSN settings. See Bounce() for options.
  • dsn_delayed (boolean) Override the current transports delay notification setting.

Warning

If the message was delivered (!isset($arguments["action"])) this function will raise a runtime error.

Note

It’s possible to forcefully queue the message exceeding its max retry.

postdelivery.Bounce([options])

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

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

The following options are available in the options array.

  • dsn (array) The DSN settings.

The following options are available in the dsn array.

  • transportid (string) Set the transport ID. The default is either choosen by the transport or automatically assigned.
  • recipient (string or array) Set the recipient of the DSN, either as a string or an associative array with a localpart and domain.
  • metadata (array) Add additional metadata (KVP) to the DSN.
  • from (string or array) Set the From-header address of the DSN, either as a string or an associative array with a localpart and domain.
  • 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()).
  • jobid (string) Job ID of the message.
  • subject (string) A custom subject.
  • subject_prepend (string) A custom string to append to the subject line (in addition to the original subject).
  • headers (array) Array of additional headers to append to the DSN.
  • readable_mimepart (string) A full MIME part to be included as the human readable part of the DSN.
  • original_headers (boolean) Include the original message headers. The default is true.

Warning

If the message was delivered (!isset($arguments["action"])) this function will raise a runtime error.

Note

If the message has a null return path (empty sender) or the transport has DSN disabled, it will cause a Delete() instead.

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 (!isset($arguments["action"])) this function will raise a runtime error.

postdelivery.Default([options])

Run the default action pending the current $arguments["action"]. This is the default action if not calling Queue(), Bounce() or Delete(). If the message was delivered no action will be taken and the script will terminate.

Returns:doesn’t return, script is terminated

The following options are available in the options array.

  • dsn (array) The DSN settings. See Bounce() for options.
postdelivery.SetMetaData(metadata)

This function updates the queued message’s metadata in 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().

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

8.2.3. On script error

On script error the default action is taken.

8.2.4. On implicit termination

If not explicitly terminated then the default action is taken.

8.2.5. References

8.2.5.1. SMTP states

BANNER The initial SMTP greeting
HELO  
EHLO  
LHLO  
STARTTLS  
AUTH-CRAM-MD5 In reply to sending AUTH CRAM-MD5 command
AUTH-PLAIN In reply to sending AUTH PLAIN command
AUTH-LOGIN In reply to sending AUTH LOGIN command
AUTH-LOGIN-USER In reply to sending AUTH LOGIN username
AUTH In reply to last command of AUTH login attempt
XCLIENT In reply to sending a XCLIENT command
MAIL  
RCPT  
DATA In reply to sending the DATA command
BDAT In reply to sending the BDAT command
EOD In reply sending the End-of-DATA
RSET  
NOOP  
QUIT