view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

This returns a list of [Email::Address::XS](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) 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](https://metacpan.org/pod/Email%3A%3AAddress%3A%3AXS) 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](https://metacpan.org/pod/Courriel%3A%3APart%3A%3ASingle) 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](https://metacpan.org/pod/Courriel%3A%3APart%3A%3ASingle) 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](https://metacpan.org/pod/Courriel%3A%3AHeader%3A%3AContentType) object associated with the email.

## $email->headers()

Returns the [Courriel::Headers](https://metacpan.org/pod/Courriel%3A%3AHeaders) 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](https://metacpan.org/pod/Courriel%3A%3ABuilder) 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](https://metacpan.org/pod/Mail%3A%3ABox)

    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](https://metacpan.org/pod/Email%3A%3ASimple) and [Email::MIME](https://metacpan.org/pod/Email%3A%3AMIME)

    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