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.
The time at which the message was received by amavisd-new
IP address of the client MTA
DNS name of the client MTA
Protocol by which mail was received ("ESMTP") - only used if mail is forwarded to an MTA which supports XFORWARD
Client MTA HELO name - only used if mail is forwarded to an MTA which supports XFORWARD
MTA queue ID of the message
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
ESMTP AUTH user (set by Amavis::In::SMTP when ESMTP AUTH is used) - used to authenticate to the next-hop MTA
ESMTP AUTH password (set by Amavis::In::SMTP when ESMTP AUTH is used) - used to authenticate to the next-hop MTA
The envelope sender of the message
File handle of the message text
Path to the mail text file
Temporary directory for use by check_mail
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.