Courier::Message - A Perl class implementing an interface to a mail message in the Courier MTA's message queue.
0.1
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 $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:
Creates a new Courier::Message object from the given message file name and zero or more control file names.
Courier::Message
%options is a list of key/value pairs representing any of the following options:
REQUIRED. A scalar containing the absolute file name of the message file.
REQUIRED. An arrayref containing the absolute file name(s) of zero or more control files belonging to the message.
The following file name accessors are provided:
Returns the absolute file name of the message file.
Returns the absolute file names of the control files belonging to the message.
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 proper 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 a (case insensitive) field name is specified, returns a list of the values of all header fields of that name, in the order they occurred in the message header. If no field name is specified, returns a hashref containing all header fields and arrayrefs of their values.
Returns the raw message body as bytes (see bytes, and "bytes" in PerlIO).
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 hashref containing all control fields and arrayrefs of their values. Throws a Perl exception if any of the control files cannot be read.
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 authentication status in a control file field, that will be the preferred source. This mostly just means that the format of the authentication info will probably change in the future.
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.
authenticated
Returns the message's envelope sender (from the "MAIL FROM:" SMTP command).
Returns all of the message's envelope recipients (from the "RCPT TO:" SMTP commands).
Returns the IP address of the SMTP client that submitted the message.
Returns the host name (gained by Courier through a DNS reverse lookup) of the SMTP client that submitted the message, if available.
Returns the HELO string that the SMTP client specified, if available.
For AVAILABILITY, SUPPORT, COPYRIGHT, and LICENSE information, see Courier::Filter::Overview.
Julian Mehnle <julian@mehnle.net>
To install Courier::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Courier::Filter
CPAN shell
perl -MCPAN -e shell install Courier::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.