NAME

       Courier::Message - Class implementing an interface to a mail message in the Courier MTA's
       message queue.

VERSION

       0.200

SYNOPSIS

           use Courier::Message;

           my $message = Courier::Message->new(
               file_name           => $message_file_name,
               control_file_names  => \@control_file_names,
           );

           # File names:
           my $message_file_name   = $message->file_name;
           my @control_file_names  = $message->control_file_names;

           # Message data properties:
           my $raw_message_text    = $message->text;
           my $header_hash         = $message->header;
           my $header_field        = $message->header($field);
           my $raw_body            = $message->body;

           # Control properties:
           my $control_hash        = $message->control;
           my $is_authenticated    = $message->authenticated;
           my $authenticated_user  = $message->authenticated_user;
           my $is_trusted          = $message->trusted;
           my $sender              = $message->sender;
           my @recipients          = $message->recipients;
           my $remote_host         = $message->remote_host;
           my $remote_host_name    = $message->remote_host_name;

DESCRIPTION

       Courier::Message encapsulates a mail message that is stored in the Courier MTA's message
       queue, including the belonging control file(s), and provides an easy to use, read-only
       interface through its message data and control properties.  For light-weight calling of
       library functions or external commands, the message and control file names may be
       retrieved without causing the files to be parsed by Courier::Message.

   Constructor
       The following constructor is provided:

       new(%options): returns Courier::Message
           Creates a new "Courier::Message" object from the given message file name and zero or
           more control file names.

           %options is a list of key/value pairs representing any of the following options:

           file_name
               Required.  The absolute file name of the message file.

           control_file_names
               Required.  An array-ref containing the absolute file name(s) of zero or more
               control files belonging to the message.

   Instance methods
       File names

       The following file name accessors are provided:

       file_name: returns string
           Returns the absolute file name of the message file.

       control_file_names: returns list of string
           Returns the absolute file names of the control files belonging to the message.

       Message data properties

       text: returns string; throws Perl exceptions
           Reads the message text from the message file into memory once.  Returns the raw
           message text as bytes (see bytes, and "bytes" in PerlIO).  Throws a Perl exception if
           the message file cannot be read.

       header: returns hash-ref of string
       header($field): returns list of string
           Parses the message header once by doing the following: tries to interpret the header
           as UTF-8, falling back to the 8-bit legacy encoding Windows-1252 (a superset of
           ISO-8859-1) and decoding that to UTF-8; parses header fields from the header; and
           decodes any MIME encoded words in field values.  If no field name is specified,
           returns a hash-ref containing all header fields and array-refs of their values.  If a
           (case insensitive) field name is specified, in list context returns a list of the
           values of all header fields of that name, in the order they occurred in the message
           header, or in scalar context returns the value of the first header field of that name
           (or undef if no such header field exists).

       body: returns string
           Returns the raw message body as bytes (see bytes, and "bytes" in PerlIO).

       Control properties

       control: returns hash-ref of string; throws Perl exceptions
       control($field): returns list of string; throws Perl exceptions
           Reads and parses all of the message's control files once.  If a (case sensitive) field
           name (i.e. record type) is specified, returns a list of the values of all control
           fields of that name, in the order they occurred in the control file(s).  If no field
           name is specified, returns a hash-ref containing all control fields and array-refs of
           their values.  Throws a Perl exception if any of the control files cannot be read.

       authenticated: returns boolean
           Returns the authentication information (guaranteed to be a true value) if the message
           has been submitted by an authenticated user.  Returns false otherwise.

           Note:  The authentication status and information is currently determined and taken
           from the message's first (i.e. the trustworthy) "Received" header field.  This is
           guaranteed to work correctly, but is not very elegant, so this is subject to change.
           As soon as Courier supports storing the complete authentication info (including the
           authenticated user name) in a control field, that will be the preferred source.  This
           mostly just means that the format of the authentication info will probably change in
           the future.

       authenticated_user: returns string
           Returns the user name that was used for authentication during submission of the
           message.  Returns undef if no authentication took place.

       trusted: returns boolean
           Returns a boolean value indicating whether the message is trusted.  Currently, trusted
           messages are defined to be messages directly submitted by an authenticated user.  For
           details on how the authenticated status is determined, see the description of the
           "authenticated" property.

       sender: returns string
           Returns the message's envelope sender (from the "MAIL FROM" SMTP command).

       recipients: returns list of string
           Returns all of the message's envelope recipients (from the "RCPT TO" SMTP commands).

       remote_host: returns string
           Returns the IP address of the SMTP client that submitted the message.

       remote_host_name: returns string
           Returns the host name (gained by Courier through a DNS reverse lookup) of the SMTP
           client that submitted the message, if available.

       remote_host_helo: returns string
           Returns the HELO string that the SMTP client specified, if available.

SEE ALSO

       For AVAILABILITY, SUPPORT, and LICENSE information, see Courier::Filter::Overview.

AUTHOR

       Julian Mehnle <julian@mehnle.net>