8.2. Post-delivery¶

8.2.1. Variables¶

These are the pre-defined variables available.

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()¶

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

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¶