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.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¶
-
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.
- hold (boolean) Put the message in the hold (inactive) queue. The default is
-
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
anddomain
. - 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
anddomain
. - 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 inMIME.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.
-
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.
-
Default
()¶ Run the default action pending the current
$arguments["action"]
. This is the default action if not callingQueue()
,Bounce()
orDelete()
. If the message was delivered no action will be taken and the script will terminate.Returns: doesn’t return, script is terminated
-
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()
.
-
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 |
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 |