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