Courier::Message(3pm)

💌 Courier::Message 💌

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about Courier::Message — the class that lets you peek at a mail message chillin' in the Courier MTA's message queue. come learn with me 🫶

✨ VERSION ✨

0.200 — that's the one, no cap.

---

🌸 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 🌈

So Courier::Message is the class that wraps up a mail message stored in the Courier MTA's message queue — plus the control file(s) that belong to it — and it hands you an easy-to-use, read-only interface through its message data properties and its control properties. 💅

And here's the cute little trick: for light-weight calling of library functions or external commands, you can grab the message file name and the control file names without making Courier::Message parse anything. it's giving lazy-in-the-best-way energy ✨

---

🎀 Constructor 🎀

There's exactly one, bestie, and it's this one:

• new(%options) — returns Courier::Message

Makes a brand new Courier::Message object out of the message file name you give it and zero or more control file names.

%options is just a list of key/value pairs, and these are the keys you can use:

• file_name — Required. The absolute file name of the message file.
• control_file_names — Required. An array-ref holding the absolute file name(s) of zero or more control files belonging to the message.

don't skip the required ones, bestie, they're literally required 💀

---

🦋 Instance methods 🦋

📁 File names 📁

These are the file name accessors, and they are chef's kiss simple:

• file_name — returns string. Gives you back the absolute file name of the message file.
• control_file_names — returns list of string. Gives you back the absolute file names of the control files that belong 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). And if the message file can't be read? It throws a Perl exception. 😭

• header — returns hash-ref of string
• header($field) — returns list of string

Parses the message header once, and it does it like this: it tries to interpret the header as UTF-8, then falls back to the 8-bit legacy encoding Windows-1252 (which is a superset of ISO-8859-1) and decodes that to UTF-8; then it parses the header fields out of the header; and then it decodes any MIME encoded words sitting in the field values. 🫶

• If you don't pass a field name, you get back a hash-ref with all the header fields and array-refs of their values.
• If you do pass a field name (and it's case insensitive, fyi), then in list context you get a list of the values of all header fields with that name, in the order they showed up in the message header. In scalar context, you get the value of the first header field with 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 you specify a field name (and heads up, this one is case sensitive — it's the record type), you get a list of the values of all control fields with that name, in the order they occurred in the control file(s).
• If you don't specify a field name, you get a hash-ref with all the control fields and array-refs of their values.

And if any of the control files can't be read, it throws a Perl exception. periodt.

• authenticated — returns boolean

Returns the authentication information (which is guaranteed to be a true value) if the message was submitted by an authenticated user. Otherwise it returns false.

Note: the authentication status and info is currently determined and taken from the message's first (i.e. the trustworthy) "Received" header field. This is guaranteed to work correctly, but it's not very elegant, so it's 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. What that mostly means is that the format of the authentication info will probably change in the future. 👀

• authenticated_user — returns string

Returns the user name that was used to authenticate while the message was being submitted. Returns undef if no authentication happened. 💜

• trusted — returns boolean

Returns a boolean telling you whether the message is trusted. Currently, trusted messages are just defined as messages directly submitted by an authenticated user. For the deets on how the authenticated status is figured out, go look at the description of the "authenticated" property. 👑

• sender — returns string

Returns the message's envelope sender — that's the one from the "MAIL FROM" SMTP command. 📬

• recipients — returns list of string

Returns all of the message's envelope recipients — those come 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 (which Courier got through a DNS reverse lookup) of the SMTP client that submitted the message, if it's available. 🔍

• remote_host_helo — returns string

Returns the HELO string that the SMTP client specified, if it's available. 🌟

---

🔥 SEE ALSO 🔥

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

⭐ AUTHOR ⭐

Julian Mehnle <julian@mehnle.net> — icon ✨

---

okay that's the whole page, bestie!! this was Courier::Message(3pm) from perl v5.34.0, dated 2022-10-21, living under User Contributed Perl Documentation 💖 happy queuing, you absolute main character 🎀💅🌸