Email::MIME(3p)

NAME
Email::MIME - Easy MIME message parsing.

VERSION
version 1.861

 $Id: MIME.pm 780 2007-07-20 03:22:05Z rjbs@cpan.org $

SYNOPSIS
  use Email::MIME;
  my $parsed = Email::MIME->new($message);

  my @parts = $parsed->parts; # These will be Email::MIME objects, too.
  my $decoded = $parsed->body;
  my $non_decoded = $parsed->body_raw;

  my $content_type = $parsed->content_type;

DESCRIPTION
This is an extension of the Email::Simple module, to handle MIME encoded messages. It takes a message as a string, splits it up into its constituent parts, and allows you access to various parts of the message. Headers are decoded from MIME encoding.

NOTE
This is an alpha release, designed to stimulate discussion on the API, which may change in future releases. Please send me comments about any features you think "Email::MIME" should have. Note that I expect most things to be driven by subclassing and mix-ins.

METHODS
Please see Email::Simple for the base set of methods. It won't take very long. Added to that, you have:

  parts
This returns a list of "Email::MIME" objects reflecting the parts of the message. If it's a single-part message, you get the original object back.

In scalar context, this method returns the number of parts.

  subparts
This returns a list of "Email::MIME" objects reflecting the parts of the message. If it's a single-part message, this method returns an empty list.

In scalar context, this method returns the number of subparts.

  body
This decodes and returns the body of the object. For top-level objects in multi-part messages, this is highly likely to be something like "This is a multi-part message in MIME format."

  body_raw
This returns the body of the object, but doesn't decode the transfer encoding.

  decode_hook
This method is called before the Email::MIME::Encodings "decode" method, to decode the body of non-binary messages (or binary messages, if the "force_decode_hook" method returns true). By default, this method does nothing, but subclasses may define behavior.

This method could be used to implement the decryption of content in secure email, for example.

  content_type
This is a shortcut for access to the content type header.

  filename
This provides the suggested filename for the attachment part. Normally it will return the filename from the headers, but if "filename" is passed a true parameter, it will generate an appropriate "stable" filename if one is not found in the MIME headers.

  invent_filename
  my $filename = Email::MIME->invent_filename($content_type);

This routine is used by "filename" to generate filenames for attached files. It will attempt to choose a reasonable extension, falling back to dat.

  debug_structure
  my $description = $email->debug_structure;

This method returns a string that describes the structure of the MIME entity. For example:

  + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5"
    + text/plain
    + text/html

TODO
All of the Email::MIME-specific guts should move to a single entry on the object's guts. This will require changes to both Email::MIME and Email::MIME::Modifier, sadly.

SEE ALSO
Email::Simple, Email::MIME::Modifier, Email::MIME:Creator.

PERL EMAIL PROJECT
This module is maintained by the Perl Email Project

<http://emailproject.perl.org/wiki/Email::MIME>

AUTHOR
Casey West, "casey@geeknest.com"

Simon Cozens, "simon@cpan.org" (retired)

You may distribute this module under the terms of the Artistic or GPL licenses.

THANKS
This module was generously sponsored by Best Practical (http://www.bestpractical.com/) and Pete Sergeant.