Controlling error messages associated with rewriting

From Messaging Server Technical Reference Wiki
Jump to: navigation, search


Controlling error messages associated with rewriting, $?, $nxxxyyy?

The MTA provides default error messages when rewriting and channel matching fail. The ability to change these messages can be useful under certain circumstances. For example, if someone tries to send mail to an ethernet router box, it may be considered more informative to say something like "our routers cannot accept mail" rather than the usual "unknown host or domain" (see the error_text_unknown_host MTA option). A special control sequence can be used to change the error message that will be printed if the rule fails. The sequence $? is used to specify an error message. Text following the $?, up until either an at sign, percent sign, $N, $M, $Q, $C, $T, or $? is taken to be the text of the error message to print if the result of this rewrite fails to match any channel. The setting of an error message is "sticky" and will last through the rewriting process.

A rule that contains a $? operates just like any other rule. The special case of a rule containing only a $? and nothing else receives special attention --- the rewriting process is terminated without changing the mailbox or host portions of the address and the host is looked up as-is in the channel table. This lookup is expected to fail and the error message will be returned as a result.

For instance, if the final rewrite rule in the MTA configuration file is

.     $?Unrecognized address; contact postmaster@xyzzy.com 
 

then any unrecognized host/domain specifications which will fail will, in the process of failing, generate the error message "Unrecognized address; contact postmaster@xyzzy.com".

Optionally, an extended SMTP error code may be included in the $? template, controlling among other things whether the error returned is a temporary error, or a permanent error; the format is:


$nxxxyyy?error-text

where the n is either 4 (meaning a temporary error) or 5 (meaning a permanent error) and the xxx and yyy specify the second and third digits, respectively, of the extended SMTP error code. E.g.,


offline.domain.com   $4002001?Mailboxes$ temporarily$ unavailable;$ try$ later 

will result in extended SMTP error code and error text "4.2.1 Mailboxes temporarily unavailable; try later". If an extended SMTP error code is specified but no error-text is specified, then the text of error_text_temporary_failure or error_text_permanent_failure will be used, as appropriate.


See also: