The Amavis::check_mail function is the main MTA-independent mail checking function, which performs all the work of running content scanners and deciding message destinies. It also handles quarantining, recipient/admin notification messages, and forwarding the message or sending a DSN in cases where that is amavisd-new's responsibility. For each message, before calling check_mail you must call Amavis::check_mail_begin_task which clears the values of several variables. Amavis::In::SMTP calls this upon receiving the MAIL FROM command. Other packages call it immediately before calling check_mail. A reference to the check_mail function is passed as an argument to the MTA request function. It takes three arguments, described below.

The $conn object holds information about how the message was received by amavisd-new. This object is created by Amavis::process_request and passed to the MTA-specific request function, which may then set further properties before passing it on to check_mail. The proto property holds the type of socket by which it was received: either TCP or UNIX, and is set by Amavis::process_request. The client_ip, socket_ip and socket_port properties make sense only if the message was received by TCP, and are set by Amavis::process_request to the TCP/IP addresses of the client and of amavisd-new itself. The smtp_proto and smtp_helo properties are meaningful only if the message was received by SMTP, and are set by Amavis::In::SMTP::process_smtp_request. (The smtp_proto property is also set by Amavis::In::QMQPqq, to "QMQPqq"). These properties are used for generating the Received line which is inserted whenever amavisd-new is responsible for forwarding the message. They are used for dynamic message forwarding, in which the message is forwarded back to the same host from which it was received (and perhaps also to a port equal to the port on which amavisd-new received it, plus one). The client_ip and smtp_helo are included in the Received-From-MTA header of DSNs if they are specified. They are also used for logging within process_smtp_request.

The $msginfo object holds all the information about the message itself. The MTA-specific request function creates the object and sets various properties which are used by check_mail in processing. Further properties are set by check_mail itself, both for use within MTA-independent code and to instruct the MTA-specific code on how to handle the message. Those properties which may be considered by MTA-specific code after check_mail returns are considered below. Here are the properties which MTA-specific code should set before calling check_mail. rx_time The time at which the message was received by amavisd-new client_addr IP address of the client MTA client_name DNS name of the client MTA client_proto Protocol by which mail was received ("ESMTP") - only used if mail is forwarded to an MTA which supports XFORWARD client_helo Client MTA HELO name - only used if mail is forwarded to an MTA which supports XFORWARD queue_id MTA queue ID of the message msg_size The message size - Amavis::In::SMTP sets it from the ESMTP SIZE option; however if it is not set, check_mail can calculate it from the message auth_user ESMTP AUTH user (set by Amavis::In::SMTP when ESMTP AUTH is used) - used to authenticate to the next-hop MTA auth_pass ESMTP AUTH password (set by Amavis::In::SMTP when ESMTP AUTH is used) - used to authenticate to the next-hop MTA sender The envelope sender of the message mail_text File handle of the message text mail_text_fn Path to the mail text file mail_tempdir Temporary directory for use by check_mail delivery_method The method by which the mail will be delivered, or "" if this is the MTA's responsibility (set from the forward_method policy bank variable) In addition the per_recip_data property must also be initialised. This property holds an array of Amavis::In::Message::PerRecip objects, one holding information on each recipient of the message. The per_recip_data method can be used to access this array. To initialise it, you should use the recips method which simply takes a reference to an array of recipient addresses as an argument. It takes care of creating an Amavis::In::Message::PerRecip object for each recipient, and setting their recip_addr properties.

The $dsn_per_recip_capable should be 1 if your MTA can handle different destinies for different recipients, and 0 if it cannot. It is passed on to the mail_dispatch and one_response_for_all functions. one_response_for_all uses it to declare that amavisd-new must send DSNs if some but not all recipients REJECT the message and the MTA is not DSN-per-recip-capable. mail_dispatch hands it on to the various specific delivery method functions. mail_via_smtp_single uses it to abort sending the message if there is an temporary error in response to one of the RCPT TO commands. None of the others use it.

The check_mail function returns a list of three values.

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: If any recipient has a temporary failure (4xx), then the first such failure is returned. 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. 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. 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. If at least one recipient has a 2xx response and a destiny of D_PASS, then the first such is returned. 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.

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.

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.

After check_mail returns, the per_recip_data of $msginfo will be filled in with instructions for MTAs capable of handling per-recipient destinies. Note that the order of elements of this array is preserved, which may assist processing. Each element has the following useful properties: recip_done This is set to 1 if the message has been bounced by check_mail or marked for discard or rejection, and to 2 if the message has been forwarded (in these cases the MTA should be told to drop the recipient). It is left undefined if the MTA should be left to forward the message for this recipient. recip_smtp_response Per-recipient SMTP response recip_addr The original recipient address - useful for comparing to recip_final_addr recip_final_addr The final recipient address, after any necessary modifications have been applied You may also wish to consult the $msginfo->dsn_sent property. This is set to 1 if check_mail has sent a DSN and 2 if it has pretended to send one. In these cases, the mail should be discarded for any recipients with a 5xx response code to prevent the MTA sending another DSN. If your MTA can handle per-recipient SMTP responses, then you should simply use the recip_smtp_response properties in combination with $msginfo->dsn_sent. If it can handle per-recipient discards but not per-recipient responses, then you should simply use the global SMTP response if it is not 2xx. If it is 2xx, then you should instruct the MTA to drop recipients who have recip_done non-zero, and (if possible) to change any non-done recipients for whom recip_final_addr is not equal to recip_addr.

Header edits are determined by the add_forwarding_header_edits_common and add_forwarding_header_edits_per_recip functions. If notify_method is non-empty, so that forwarding the message is check_mail's responsibility, then it can apply the correct per-recip header edits independently for each recipient. If notify_method is empty so that forwarding is the MTA's responsibility, then only a single set of header edits can be applied. In this case the edits for the first passed recipient will be used (the common headers alone are insufficient as spam and virus tagging is only done in per-recip headers). The header edits are recorded in an Amavis::Out::EditHeader object, which is found in the $msginfo->header_edits property. This object does not provide methods to access its properties, so you will have to treat it as a hash reference and access keys directly. The prepend and append keys each contain an array of headers to be added, before or after existing headers respectively. Each element of these arrays is simply a string containing the entire header line. Both arrays contain the set of additional headers in the order in which they should appear in the message. The edit key contains a hash of headers to be edited. The hash keys are the names of the header fields. If a value is undef, then that header should simply be deleted. Otherwise the value will be a code reference, which takes two arguments: the header name and the original value. It returns the new value for the header. If you need to obtain the original header value to pass to a header edit function, this can be obtained from $msginfo->mime_entity->head->get(header_name, 0).

Policy banks are used to provide policy switching between different sources of mail. The most important thing you need to know about them is that configuration variables which are part of policy banks should be accessed using the c (to access a scalar), cr (to obtain a reference to the value) or ca (to access an array, returning a reference) functions to access configuration variables which are part of policy banks, instead of accessing the global variables directly. In addition, you should load the MYNETS policy bank if the client MTA has a local IP address and MYUSERS if the sender has a local address. This is determined using the mynetworks_maps and local_domains_maps settings respectively. The code looks like this: my($cl_ip) = $msginfo->client_addr; my($sender) = $msginfo->sender; if ($cl_ip ne '' && defined $policy_bank{'MYNETS'} && lookup_ip_acl($cl_ip,@{ca('mynetworks_maps')}) ) { Amavis::load_policy_bank('MYNETS'); $policy_changed = 1; } if ($sender ne '' && defined $policy_bank{'MYUSERS'} && lookup(0,$sender,@{ca('local_domains_maps')})) { Amavis::load_policy_bank('MYUSERS'); $policy_changed = 1; } Before changing the policy bank, you need to save a copy of the %current_policy_bank hash. After mail processing is completed, you need to restore this hash to its original value. (Is this strictly necessary?) You should also enable debugging if the sender matches debug_sender_maps, by doing debug_oneshot(1) if lookup(0, $sender, @{ca('debug_sender_maps')}); (after loading relevant policy banks).

The check_mail function requires a temporary directory to unpack the parts of the mail into. It is the responsibility of the MTA-specific code to maintain this directory - it is suggested to create one directory per child process and reuse it for each message, as creating and removing directories is a slow operation. You can store the path to the temporary directory in a property of your persistent object. If the preserve_evidence return value of check_mail is 1, then you should leave (not delete) the existing temporary directory and create a new one. This can be done by setting the persistent property to undef immediately, ensuring that the directory will not be deleted if the process terminates, and leaving it until the next message to create the directory since one does not exist already.

You must ensure that your temporary directory has a name which will differ both from other child processes running at the same time and from other directories created by your own process (or even an earlier child with the same PID). A suggested way of achieving this is to include the time and the PID in the temporary directory name: the standard format is amavis-DATE-PID where DATE is in ISO 8601 format. Amavis::rfc2821_2822_Tools::iso8601_timestamp can be used to create this. The directory should be a subdirectory of the $TEMPBASE directory. After choosing the directory name, you must ensure that the directory exists and is a directory (it is best to check this before calling check_mail for every message). If it is not a directory, you should return a temporary failure. It is a good idea to check that the device or inode number of the directory remain the same, and if not to report this in the log. If it does not exist, you should create the directory with mode 0750 and record its device and inode number.

Your function may need to create a file to hold the text of the email. This should be a file called email.txt in the temporary directory. Creating it is done after creating the temporary directory, and in a similar way. If the device/inode numbers have changed this is not as serious a problem as for the directory, as the file may have been replaced by some other tool. In this case you should delete and re-create the file.

The temporary directory should be cleaned after calling check_mail, unless evidence is to be preserved. This can be done simply by calling Amavis::Util::strip_tempdir(dir). This deletes all files in the parts subdirectory (creating this is handled for you by check_mail) and ensures that the temporary directory holds nothing other than a parts subdirectory and file email.txt. If $can_truncate is 0, you will also need to close and delete the email.txt file.

When the child process terminates, the current temporary directory should be deleted. This can be done in your class's destructor. If the directory exists, then simply use Amavis::Util::rmdir_recursively(dir) to delete it.