The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Courriel-0.21-TRIAL
River stage zero No dependents
3 ++
/ Courriel

NAME

Courriel - High level email parsing and manipulation

VERSION

version 0.21

SYNOPSIS

    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

This software is still very alpha, and the API may change without warning in future versions.

This class exists to provide a high level API for working with emails, particular for processing incoming email. It is primarily a wrapper around the other classes in the Courriel distro, especially Courriel::Headers, Courriel::Part::Single, and Courriel::Part::Multipart. If you need lower level information about an email, it should be available from one of this classes.

API

This class provides the following methods:

Courriel->parse( text => $raw_email )

This parses the given text and returns a new Courriel object. The text can be provided as a string or a reference to a string.

If you pass a reference, then the scalar underlying the reference will be modified, so don't pass in something you don't want modified.

$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.

$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 one. 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 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 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 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 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 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.

$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.

$part->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 I have 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 a lot of email modules/distros on CPAN. Why didn't I 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 I generally find it to be too much module for me.

  • 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. I've hacked on these enough to know that I can never make them do what I want.

  • 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.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Dave Rolsky.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)