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

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

More methods for walking all parts¶

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

More?¶

Stay tuned for details.