bionic (3) Courier::Message.3pm.gz
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>