Courier::Message - Class implementing an interface to a mail
message in the Courier MTA's message queue.
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;
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.
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.
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.
- 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.
For AVAILABILITY, SUPPORT, and LICENSE information, see
Courier::Filter::Overview.
Julian Mehnle <julian@mehnle.net>