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>