HSL Mail Transport

The Mail Transport extension to the HSL is used to handle errors in mail transports. In reality, it means that if no error occurs, the script will never be executed. 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.

Contents 1 Pre-defined variables 2 Context-specific functions 2.1 Delete() 2.2 GenerateDSN() 2.3 Retry() 2.4 Deliver($recipient, $transport) 3 Code examples

Pre-defined variables

Name	Example	Description
$serverip	"10.0.0.1"	IP to which we tried to connect (empty on DNS problems)
$serverport	25	Port on which we tried connect
$sender	"spam@example.com"	Mail address of sender
$senderip	"1.2.3.4"	IP-address of sender (of original message)
$senderdomain	"example.com"	Domain part of sender address
$recipient	"test@example.com"	Mail address of recipient
$recipientdomain	"example.com"	Domain part of recipient address
$retry	3	The current retry count
$errormsg	"5.7.1 <spam@example.org>... we do not relay <test@example.org>"	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)

Context-specific functions

In order to control how the H/OS unit 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 "catch-all@example.org" 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("catch-all@example.org", "mailtransport:2"); 

Code examples

Handle two common errors...

if ($errorcode == 501 and $errorndr == "5.7.1") {
 echo "Deleting mail since Sender-Domain-Must-Exists";
 Delete();
}
if ($errorcode == 550 and $errorndr == "5.7.1") {
 echo "Deleting mail since We-Do-Not-Relay";
 Delete();
} 

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

Retry();