HSL Mail Transport

From Halon, SMTP software for hosting providers
Revision as of 15:06, 28 January 2015 by Anders (talk | contribs)
Jump to: navigation, search

The Mail Transport (post-queue) extension to the HSL is used to handle return codes (250 OK or 400-500 errors) in mail transports. If an error higher or equal to 500 is trigged, the default action will be to delete the mail and generate a DSN according to the transport settings (but this behavior can be overridden with the functions below). The concept should be to have the best possible default settings for the transport but then if necessary override specific errors.

Pre-defined variables

Name Example Description
$transportid "mailtransport:1" Which transport profile is chosen for delivery settings
$messageid "18c190a3-93fb-47d7-bd4c-c83a4c421832" Message ID of message
$queueid 123456 Queue ID of message
$actionid 1 Same as $actionid in DATA flow
$saslusername "joe" Which username was used to submit the message
$serverip "10.0.0.1" IP to which we tried to connect (empty on DNS problems)
$serverport 25 Port on which we tried connect
$senderip "1.2.3.4" IP-address of sender (of original message)
$sender "[email protected]" Mail address of sender
$senderdomain "example.com" Domain part of sender address
$recipient "[email protected]" Mail address of recipient
$recipientdomain "example.com" Domain part of recipient address
$retry 3 The current retry count
$retries 30 The maximum number of retries for that message
$errormsg "5.7.1 <[email protected]>... we do not relay <[email protected]>" The error message from the server
$errorcode 550 The error code from the server (A value 0 of indicates network problems).
$errorndr "5.7.1" The NDR code from the server (if available)
$transfertime 0.512 The transfer time for this delivery attempt (seconds)

Context-specific functions

In order to control how the system should handle errors when delivering mail, you may use these function.

Delete()

If you want to delete the mail from the outgoing queue without generating a DSN. This is a final action, the execution of the script will terminate after a final action.

Delete(); 

GenerateDSN()

If you want to delete the mail from the outgoing queue and generate a DSN to the sender regardless of the transport DSN settings. This is a final action, the execution of the script will terminate after a final action.

GenerateDSN(); 

Retry()

If you want to queue the mail from a retry later. This function is implicit but provided as a final action. When the Retry count is reached the mail will be deleted and generate a DSN according to the transport settings. This is a final action, the execution of the script will terminate after a final action.

Retry(); 

Deliver($recipient, $transport)

This function allows you to change the recipient and/or transport upon failure. For example if you receive a "No such user" failure you may change the recipient to a "[email protected]" or if a transport is unavailable (down) you may try another one. This can be use for a simple type of fail-over. The retry-count is set back to zero and it will be queue for a immediately delivery. Use this function with caution since strange loops may occur if the secondary transport falls back to the first one upon the first failure (consider checking if $retry is not zero). This is a final action, the execution of the script will terminate after a final action.

Deliver("[email protected]""mailtransport:2"); 

SetMetaData($array)

Documented in the DATA context.

GetMetaData()

Documented in the pre-delivery context.

Code examples

Always retry until retry count is reached, even if the $errorcode is equal or higher than 500.

if ($errorcode >= 500)
   
Retry();