Courriel(3pm)

💌 Courriel — the manual page, but make it cute

okay bestie, so this is the manpage for Courriel, and in the docs it lives under the name Courriel(3pm) in the User Contributed Perl Documentation section. grab a snack, we're doing email parsing 💖

---

✨ NAME ✨

Courriel — high level email parsing and manipulation. that's the whole vibe. 🦋

---

🌸 VERSION 🌸

version 0.49 — yes, she has a number, she's official.

---

🎀 SYNOPSIS 🎀

here's the whole thing in action, look at her go:

my $email = Courriel->parse( text => $raw_email );

print $email->subject;

print $_->address for $email->participants;

print $email->datetime->year;

if ( my $part = $email->plain_body_part ) {
    print $part->content;
}

---

💅 DESCRIPTION 💅

okay so the whole point of this class is to hand you a high level API for working with emails — especially for processing incoming email. it's basically a wrapper around the other classes in the Courriel distro, and the main characters it wraps are Courriel::Headers, Courriel::Part::Single, and Courriel::Part::Multipart. if you need lower level info about an email, it should be available from one of those classes. iykyk 💜

---

🔥 API 🔥

this class provides the following methods:

Courriel->parse( text => $raw_email, is_character => 0|1 )

this parses the given text and returns a new Courriel object. the text can come in as a string or as a reference to a string.

⚠️ if you pass a reference, the scalar underlying that reference gets modified, so don't pass in something you don't want modified. fr fr.

by default, Courriel expects that content passed in text is binary data. meaning it has not been decoded into utf-8 with Encode::decode() or by using a :encoding(UTF-8) IO layer.

in practice, this doesn't matter for most emails, since they either contain only ASCII data or they actually do contain binary (non-character) data. however, if an email is using the 8bit Content-Transfer-Encoding, then this does matter.

if the email has already been decoded, you must set is_character to a true value.

it's safest to simply pass binary data to Courriel and let it handle decoding internally. trust the process 💖

$email->parts()

returns an array (not a reference) of the parts this email contains.

$email->part_count()

returns the number of parts this email contains. simple math, slay.

$email->is_multipart()

returns true if the top-level part is a multipart part, false otherwise.

$email->top_level_part()

returns the actual top level part for the object. you're probably better off just calling $email->parts() most of the time, since when the email is multipart, the top level part is just a container. 🫶

$email->subject()

returns the email's Subject header value, or undef if it doesn't have one.

$email->datetime()

returns a DateTime object for the email. the DateTime object is always in the UTC time zone.

this uses the Date header by default. otherwise it looks at the date in each Received header, and then it looks for a Resent-Date header. if none of these exists, it just returns DateTime->now().

$email->from()

this returns a single Email::Address::XS object based on the From header of the email. if the email has no From header or if the From header is broken, it returns undef. 💀

$email->participants()

this returns a list of Email::Address::XS objects, one for each unique participant in the email. this includes any address in the From, To, or CC headers.

just like with the From header, broken addresses will not be included.

$email->recipients()

this returns a list of Email::Address::XS objects, one for each unique recipient in the email. this includes any address in the To or CC headers.

just like with the From header, broken addresses will not be included.

$email->to()

this returns a list of Email::Address::XS objects, one for each unique address in the To header.

just like with the From header, broken addresses will not be included.

$email->cc()

this returns a list of Email::Address::XS objects, one for each unique address in the CC header.

just like with the From header, broken addresses will not be included.

$email->plain_body_part()

this returns the first Courriel::Part::Single object in the email with a mime type of text/plain and an inline disposition, if one exists.

$email->html_body_part()

this returns the first Courriel::Part::Single object in the email with a mime type of text/html and an inline disposition, if one exists.

$email->clone_without_attachments()

returns a new Courriel object that only contains inline parts from the original email, effectively removing all attachments. bye bye files ✨

$email->first_part_matching( sub { ... } )

given a subroutine reference, this method calls that subroutine for each part in the email, in a depth-first search.

the subroutine receives the part as its only argument. if it returns true, this method returns that part.

$email->all_parts_matching( sub { ... } )

given a subroutine reference, this method calls that subroutine for each part in the email, in a depth-first search.

the subroutine receives the part as its only argument. if it returns true, this method includes that part.

this method returns all of the parts that match the subroutine.

$email->content_type()

returns the Courriel::Header::ContentType object associated with the email.

$email->headers()

returns the Courriel::Headers object for this email.

$email->stream_to( output => $output )

this method will send the stringified email to the specified output. the output can be a subroutine reference, a filehandle, or an object with a print() method. the output may be sent as a single string, as a list of strings, or via multiple calls to the output.

for large emails, streaming can be much more memory efficient than generating a single string in memory. 🌈

$email->as_string()

returns the email as a string, along with its headers. lines will be terminated with "\r\n".

---

👑 ROBUSTNESS PRINCIPLE 👑

Courriel aims to respect the common Internet robustness principle (aka Postel's law). Courriel is conservative in the output it generates, and liberal in what it accepts.

when parsing, the goal is to never die and always return as much information as possible. any input that causes the Courriel->parse() to die means there's a bug in the parser. please report these bugs. 🐛

conversely, Courriel aims to respect all relevant RFCs in its output, except when it preserves the original data in a parsed email. if you're using Courriel::Builder to create emails from scratch, any output that isn't RFC-compliant is a bug.

---

🦋 FUTURE PLANS 🦋

this release is still rough, and the author has some plans for additional features:

more methods for walking all parts

some more methods for walking/collecting multiple parts would be useful.

more?

stay tuned for details. 👀

---

💭 WHY DID I WRITE THIS MODULE? 💭

there are a lot of email modules/distros on CPAN. why didn't the author use/fix one of them?

• Mail::Box — this one probably does everything this module does and more, but it's really, really big and complicated, forcing the end user to make a lot of choices just to get started. if you need it, it's great, but it's generally found to be too much module for the job.
• Email::Simple and Email::MIME — these are surprisingly not simple. they suffer from a problematic API (too high level in some spots, too low in others), and a poor separation of concerns. the author has hacked on these enough to know that they can never be made to do what he wants.
• everything else — there's a lot of other email modules on CPAN, but none of them really seem any better than the ones mentioned above.

---

💖 CREDITS 💖

this module rips some chunks of code from a few other places, notably several of the Email suite modules. giving credit where credit is due 🫶

---

🐛 BUGS 🐛

please report any bugs or feature requests to bug-courriel@rt.cpan.org, or through the web interface at http://rt.cpan.org. the author will be notified, and then you'll automatically be notified of progress on your bug as changes are made.

bugs may be submitted at https://github.com/houseabsolute/Courriel/issues.

the author is also usually active on IRC as 'autarch' on irc://irc.perl.org.

---

📦 SOURCE 📦

the source code repository for Courriel can be found at https://github.com/houseabsolute/Courriel.

---

💸 DONATIONS 💸

if you'd like to thank the author for the work done on this module, please consider making a "donation" via PayPal. he spends a lot of free time creating free software, and would appreciate any support you'd care to offer.

please note that this is not a suggestion that you must do this in order for him to continue working on this particular software. he will continue to do so, inasmuch as he has in the past, for as long as it interests him.

similarly, a donation made in this way will probably not make him work on this software much more, unless he gets so many donations that he can consider working on free software full time (let's all have a chuckle at that together 😭).

to donate, log into PayPal and send money to autarch@urth.org, or use the button at https://www.urth.org/fs-donation.html.

---

🌟 AUTHOR 🌟

Dave Rolsky <autarch@urth.org>

---

💜 CONTRIBUTORS 💜

• Gregory Oschwald <goschwald@maxmind.com>
• Ricardo Signes <rjbs@users.noreply.github.com>
• Vitaly Gimly <vgimly@gmail.com>
• Zbigniew Łukasiak <zzbbyy@gmail.com>

---

⚖️ COPYRIGHT AND LICENSE ⚖️

this software is Copyright (c) 2021 by Dave Rolsky.

this is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

the full text of the license can be found in the LICENSE file included with this distribution.

---

and that's the whole page, bestie 🎀 this was Courriel(3pm) from perl v5.32.1, dated 2021-08-22. go parse something gorgeous 💖✨