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
expired	boolean	false	If the maximum age or retry count of the message has been exceeded
action	string	“DELETE”	The default action of this execution (“DELETE”, “BOUNCE”, “QUEUE”). Missing on successful deliveries.
grouping	string	“&exampledomains”	The matched grouping
policy	array	[“tags” => [“backoff”], “polic…	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).
queue	array	[“plugin” => [“return”…]	The queue plugin data (not always available)

8.2.1.1.1. Policy

Array item	Type	Example	Description
tags	array	[“backoff”, …]	The policy tags applied
policies	array	[[“fields” => …], [“fields” …	The polices applied

8.2.1.1.1.1. Policies

Array item	Type	Example	Description
fields	array	[“remoteip”, “recipient…	List of matched fields; transportid, localip, remoteip, remotemx, recipientdomain, tenantid, jobid and grouping
grouping	array	[“remotemx” => “#google”]	List of policy groupings, index on transportid, localip, remoteip, remotemx, recipientdomain, tenantid, jobid and grouping (not always available)
dynamic	array	[0=>[“id”=>”…”, “tag”..]	List of all dynamic policies applied (not always available)
tags	array	[“backoff”, …]	The policy tags (not always available)
concurrency	number	100	The policy concurrency (not always available)
rate	array	[5, 100]	The policy rate (not always available)
stop	boolean	false	If the policy evaluation was stopped due to the stop flag
properties	array	[“myproperty1” => “foo”]	The policy properties (not always available)

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
plugin	array	[“return” => “plugin data”]	Custom delivery plugin return value (not always available)

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	string	“A generic error”	An error message
type	string	“dns”	One of config, dns, network, dane, protocol, smtp, tls or plugin
dns	string	“nullmx”	One of other, nxdomain, nullmx, ipfamily, nodata or excluded (only available if type is dns)

8.2.1.1.2.3. Connection

Array item	Type	Example	Description
id	string	“c7a7890f-a080-11ed-9f…”	The connection id
transactions	number	1	The number of transactions on this connection
localip	string	“1.2.3.4”	The source IP used
localipid	string	“bulkip1”	The source IP ID (name) used (not always available)
remoteip	string	“4.3.2.1”	The remote IP connected to
remotemx	string	“mail.example.com”	The remote MX 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-not-supported”	The tlsrpt error (if available)
tlsa	array		The tlsa record (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
error	number	18	The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3))

8.2.1.1.2.3.1.2. TLSA

Array item	Type	Example	Description
error	array	[“temporary” => true]	The TLSA name resolution error (if error)
records	array	[0=>[“usage”=>3	The TLSA records (if successful)

8.2.1.1.2.3.1.2.1. Records

Array item	Type	Example	Description
usage	number	3	The usage
selector	number	1	The selector
mtype	number	1	The mtype
data	string	fffffffffffffffffffffff…	The data (in hex format)

8.2.1.1.2.4. Plugin

Array item	Type	Example	Description
return	any	“plugin return value”	Any type passed from custom delivery plugin

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
status	array	[5, 0, 0]	The DSN status (if available)
diagnostictype	string	“smtp”	The DSN diagnostic type (eg. smtp or x-error)
diagnosticcode	string	“500 message not accepted”	The DSN diagnostic code

8.2.1.1.4. Queue

Array item	Type	Example	Description
plugin	array	[“return” => “plugin data”]	Custom queue plugin return value (not always available)

8.2.1.1.4.1. Plugin

Array item	Type	Example	Description
return	any	“plugin return value”	Any type passed from custom delivery plugin

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
tenantid	string	“customidentifier1”	Tenant ID of the message
jobid	string	“jobidentifier1”	Job ID of the message
priority	number	1	The queue priority
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.

• priority (number) Change the queue priority (0 - normal, 1 - high). The default is the current priority.

• 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 is the current transportid.

• quotas (array) An array of quotas to be associated with the message, for use with queue_quota().

• tenantid (string) Set tenantid of the message.

• jobid (string) Set jobid of the message.

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

• additional_recipients (array of recipients) A list of additional recipients (BCC).

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

• tenantid (string) Set tenantid of the message.

• jobid (string) Set jobid 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.

• ret (string) Include either FULL (message), HDRS (headers only) or false (do not include the original message) in bounces. The default is HDRS.

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

• fields (array) Override the original reportingmta (string), receivedfrommta (string), remotemta (string), status (array of three numbers), diagnosticcode (string), diagnostictype (string) and finalrecipient (address) fields.

• additional_fields (array) Array of additional fields to append to the DSN.

• additional_recipient_fields (array) Array of additional fields to append to the per recipient fields in the DSN.

if ($arguments["action"] == "BOUNCE")
{
   Bounce(["dsn" => [
       "from_name" => "The Postmaster" // change postmaster address
   ]]);
}

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(). Key names starting with a “_” (underscore) is reserved for Halon’s internal use.

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