Email::MIME(3) User Contributed Perl Documentation Email::MIME(3)NAMEEmail::MIME - Easy MIME message parsing.
VERSION
version 1.906
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;
...or...
use Email::MIME::Creator;
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" )->all,
),
Email::MIME->create(
attributes => {
content_type => "text/plain",
disposition => "attachment",
charset => "US-ASCII",
},
body => "Hello there!",
),
);
my $email = Email::MIME->create(
header => [ From => 'casey@geeknest.com' ],
parts => [ @parts ],
);
# nesting parts
$email->parts_set(
[
$email->parts,
Email::MIME->create( parts => [ @parts ] ),
],
);
# standard modifications
$email->header_set( 'X-PoweredBy' => 'RT v3.0' );
$email->header_set( To => rcpts() );
$email->header_set( Cc => aux_rcpts() );
$email->header_set( Bcc => sekrit_rcpts() );
# more advanced
$_->encoding_set( 'base64' ) for $email->parts;
# Quick multipart creation
my $quicky = Email::MIME->create(
header => [
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 => [ ... ],
attributes => { ... },
body => '...',
);
my $multi = Email::MIME->create(
header => [ ... ],
attributes => { ... },
parts => [ ... ],
);
This method creates a new MIME part. The "header" parameter is a lis of
headers to include in the message. "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( 'utf8' );
$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. 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->parts > 1; # multipart
if ( $part->content_type =~ m[text/html] ) {
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_str_set
$email->header_str_set($header_name => @value_strings);
This behaves like "header_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.
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 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.
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)
This software is copyright (c) 2004 by Simon Cozens.
This is free software; you can redistribute it and/or modify it under
the same terms as perl itself.
THANKS
This module was generously sponsored by Best Practical
(http://www.bestpractical.com/) and Pete Sergeant.
perl v5.14.1 2010-10-08 Email::MIME(3)
