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	yes	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, “message” => …]	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.

• modified_original (boolean) Included original message headers as modified by end-of-DATA script. The default is false (as received).

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