2. Return value

The check_mail function returns a list of three values.

2.1. SMTP response

The SMTP response is a string matching /^([1-5]\d\d) ([245]\.\d{1,3}\.\d{1,3})(?: |\z)(.*)\z/ i.e. an SMTP response conforming to RFC 2821. This is the default SMTP response you should use if you cannot use per-recipient responses.

It is determined from the per-recipient responses and the $dsn_per_recip_capable argument by Amavis::rfc2821_2822_Tools::one_response_for_all. It is decided as follows:

  1. If any recipient has a temporary failure (4xx), then the first such failure is returned.

  2. If any recipient has an invalid response (i.e. one not beginning 2, 4 or 5), then "450 4.5.1 Bad SMTP response??? " is returned.

  3. If all recipients have a destiny of D_DISCARD (in which case the response will begin 2xx), then the first recip SMTP response is returned.

  4. If all recipients have either a destiny of D_DISCARD or a REJECT (i.e. a 5xx response but destiny not D_BOUNCE), then a 5xx response is returned. Errors returned while trying to dispatch the mail for some recipients are preferred to errors from content scanning; subject to that, the first error is returned.

  5. If at least one recipient has a 2xx response and a destiny of D_PASS, then the first such is returned.

  6. If we get here, it means that there are some BOUNCEs, perhaps mixed with DISCARDs and REJECTs. "250 2.5.0 OK" is returned.

In the last two cases, the number of DISCARDs, BOUNCEs and REJECTs is also counted. If there is at least one of these, these count values are appended to the response.

The SMTP response will be set to "451 4.5.1 Error in processing" if an exception is thrown in check_mail before any mails (forwards, notifications or DSNs) are sent.

2.2. Exit code

The exit code again is an overall summary of the action to be taken by the MTA. It is very much milter-specific. It can take the values EX_OK (deliver the message), EX_NOUSER, EX_UNAVAILABLE, EX_NOPERM (reject the message), EX_TEMPFAIL (temporary failure) or 99 (discard the message). These constants are exported by Amavis::rfc2821_2822_Tools.

The exit code is also determined by one_response_for_all. This will return EX_TEMPFAIL if it returns a 4xx SMTP response (rules 1 and 2). It returns EX_UNAVAILABLE if it returns a 5xx response (rule 4). If there it returns a PASS response (rule 5), then it returns EX_OK. And finally, for rules 3 and 6 the MTA should discard the mail and amavisd-new will handle DSNs. In this case, it returns 99 if $msginfo->delivery_method is "" (i.e. delivery is handled by the MTA) and EX_OK otherwise.

It will also be set to EX_TEMPFAIL if an exception occurs which causes check_mail to set the SMTP response to 451.

2.3. Preserve evidence

This is 1 if an error occurred which should cause the temporary directory to be preserved to be analysed by the admin, and 0 if the temporary directory should be reused or deleted.