Provided by: libemail-mime-perl_1.937-1_all 
NAME
Email::MIME - easy MIME message handling
VERSION
version 1.937
SYNOPSIS
Wait! Before you read this, maybe you just need Email::Stuffer, which is a much easier-
to-use tool for building simple email messages that might have attachments or both plain
text and HTML. If that doesn't do it for you, then by all means keep reading.
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;
...or...
use Email::MIME;
use IO::All;
# multipart message
my @parts = (
Email::MIME->create(
attributes => {
filename => "report.pdf",
content_type => "application/pdf",
encoding => "quoted-printable",
name => "2004-financials.pdf",
},
body => io( "2004-financials.pdf" )->binary->all,
),
Email::MIME->create(
attributes => {
content_type => "text/plain",
disposition => "attachment",
charset => "US-ASCII",
},
body_str => "Hello there!",
),
);
my $email = Email::MIME->create(
header_str => [ From => 'casey@geeknest.com' ],
parts => [ @parts ],
);
# nesting parts
$email->parts_set(
[
$email->parts,
Email::MIME->create( parts => [ @parts ] ),
],
);
# standard modifications
$email->header_str_set( 'X-PoweredBy' => 'RT v3.0' );
$email->header_str_set( To => rcpts() );
$email->header_str_set( Cc => aux_rcpts() );
$email->header_str_set( Bcc => sekrit_rcpts() );
# more advanced
$_->encoding_set( 'base64' ) for $email->parts;
# Quick multipart creation
my $quicky = Email::MIME->create(
header_str => [
From => 'my@address',
To => 'your@address',
],
parts => [
q[This is part one],
q[This is part two],
q[These could be binary too],
],
);
print $email->as_string;
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.
METHODS
Please see Email::Simple for the base set of methods. It won't take very long. Added to
that, you have:
create
my $single = Email::MIME->create(
header_str => [ ... ],
body_str => '...',
attributes => { ... },
);
my $multi = Email::MIME->create(
header_str => [ ... ],
parts => [ ... ],
attributes => { ... },
);
This method creates a new MIME part. The "header_str" parameter is a list of headers pairs
to include in the message. The value for each pair is expected to be a text string that
will be MIME-encoded as needed. A similar "header" parameter can be provided in addition
to or instead of "header_str". Its values will be used verbatim.
"attributes" is a hash of MIME attributes to assign to the part, and may override portions
of the header set in the "header" parameter.
The "parts" parameter is a list reference containing "Email::MIME" objects. Elements of
the "parts" list can also be a non-reference string of data. In that case, an
"Email::MIME" object will be created for you. Simple checks will determine if the part is
binary or not, and all parts created in this fashion are encoded with "base64", just in
case.
If "body" is given instead of "parts", it specifies the body to be used for a flat
(subpart-less) MIME message. It is assumed to be a sequence of octets.
If "body_str" is given instead of "body" or "parts", it is assumed to be a character
string to be used as the body. If you provide a "body_str" parameter, you must provide
"charset" and "encoding" attributes.
Back to "attributes". The hash keys correspond directly to methods or modifying a message
from "Email::MIME::Modifier". The allowed keys are: content_type, charset, name, format,
boundary, encoding, disposition, and filename. They will be mapped to "$attr\_set" for
message modification.
content_type_set
$email->content_type_set( 'text/html' );
Change the content type. All "Content-Type" header attributes will remain intact.
charset_set
name_set
format_set
boundary_set
$email->charset_set( 'UTF-8' );
$email->name_set( 'some_filename.txt' );
$email->format_set( 'flowed' );
$email->boundary_set( undef ); # remove the boundary
These four methods modify common "Content-Type" attributes. If set to "undef", the
attribute is removed. All other "Content-Type" header information is preserved when
modifying an attribute.
encoding_set
$email->encoding_set( 'base64' );
$email->encoding_set( 'quoted-printable' );
$email->encoding_set( '8bit' );
Convert the message body and alter the "Content-Transfer-Encoding" header using this
method. Your message body, the output of the "body()" method, will remain the same. The
raw body, output with the "body_raw()" method, will be changed to reflect the new
encoding.
body_set
$email->body_set( $unencoded_body_string );
This method will encode the new body you send using the encoding specified in the
"Content-Transfer-Encoding" header, then set the body to the new encoded body.
This method overrides the default "body_set()" method.
body_str_set
$email->body_str_set($unicode_str);
This method behaves like "body_set", but assumes that the given value is a Unicode string
that should be encoded into the message's charset before being set.
The charset must already be set, either manually (via the "attributes" argument to
"create" or "charset_set") or through the "Content-Type" of a parsed message. If the
charset can't be determined, an exception is thrown.
disposition_set
$email->disposition_set( 'attachment' );
Alter the "Content-Disposition" of a message. All header attributes will remain intact.
filename_set
$email->filename_set( 'boo.pdf' );
Sets the filename attribute in the "Content-Disposition" header. All other header
information is preserved when setting this attribute.
parts_set
$email->parts_set( \@new_parts );
Replaces the parts for an object. Accepts a reference to a list of "Email::MIME" objects,
representing the new parts. If this message was originally a single part, the
"Content-Type" header will be changed to "multipart/mixed", and given a new boundary
attribute.
parts_add
$email->parts_add( \@more_parts );
Adds MIME parts onto the current MIME part. This is a simple extension of "parts_set" to
make our lives easier. It accepts an array reference of additional parts.
walk_parts
$email->walk_parts(sub {
my ($part) = @_;
return if $part->subparts; # multipart
if ( $part->content_type =~ m[text/html]i ) {
my $body = $part->body;
$body =~ s/<link [^>]+>//; # simple filter example
$part->body_set( $body );
}
});
Walks through all the MIME parts in a message and applies a callback to each. Accepts a
code reference as its only argument. The code reference will be passed a single argument,
the current MIME part within the top-level MIME object. All changes will be applied in
place.
header
Achtung! Beware this method! In Email::MIME, it means the same as "header_str", but on
an Email::Simple object, it means "header_raw". Unless you always know what kind of
object you have, you could get one of two significantly different behaviors.
Try to use either "header_str" or "header_raw" as appropriate.
header_str_set
$email->header_str_set($header_name => @value_strings);
This behaves like "header_raw_set", but expects Unicode (character) strings as the values
to set, rather than pre-encoded byte strings. It will encode them as MIME encoded-words
if they contain any control or 8-bit characters.
header_str_pairs
my @pairs = $email->header_str_pairs;
This method behaves like "header_raw_pairs", returning a list of field name/value pairs,
but the values have been decoded to character strings, when possible.
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.
This is a stupid method. Don't use it.
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 as a byte string. 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_str
This decodes both the Content-Transfer-Encoding layer of the body (like the "body" method)
as well as the charset encoding of the body (unlike the "body" method), returning a
Unicode string.
If the charset is known, it is used. If there is no charset but the content type is
either "text/plain" or "text/html", us-ascii is assumed. Otherwise, an exception is
thrown.
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.
THANKS
This module was generously sponsored by Best Practical (http://www.bestpractical.com/),
Pete Sergeant, and Pobox.com.
AUTHORS
• Ricardo SIGNES <rjbs@cpan.org>
• Casey West <casey@geeknest.com>
• Simon Cozens <simon@cpan.org>
CONTRIBUTORS
• Alex Vandiver <alexmv@mit.edu>
• Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
• Brian Cassidy <bricas@cpan.org>
• David Steinbrunner <dsteinbrunner@pobox.com>
• Dotan Dimet <dotan@corky.net>
• Geraint Edwards <gedge-oss@yadn.org>
• Jesse Luehrs <doy@tozt.net>
• Kurt Anderson <kboth@drkurt.com>
• Lance A. Brown <lance@bearcircle.net>
• Matthew Horsfall (alh) <wolfsage@gmail.com>
• memememomo <memememomo@gmail.com>
• Shawn Sorichetti <ssoriche@coloredblocks.com>
• Tomohiro Hosaka <bokutin@bokut.in>
COPYRIGHT AND LICENSE
This software is copyright (c) 2004 by Simon Cozens and Casey West.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.