view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Courriel - High level email parsing and manipulation

# VERSION

version 0.49

# 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 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](https://metacpan.org/pod/Courriel%3A%3AHeaders),
[Courriel::Part::Single](https://metacpan.org/pod/Courriel%3A%3APart%3A%3ASingle), and [Courriel::Part::Multipart](https://metacpan.org/pod/Courriel%3A%3APart%3A%3AMultipart). If you need lower
level information about an email, it should be available from one of these
classes.

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

By default, Courriel expects that content passed in text is binary data. This
means that 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.

## $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](https://metacpan.org/pod/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::XS](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) 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](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) 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](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) 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](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) objects, one for each unique