.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Email::MIME 3pm"
.TH Email::MIME 3pm "2016-02-02" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Email::MIME \- easy MIME message handling
.SH "VERSION"
.IX Header "VERSION"
version 1.937
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBWait!\fR 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 \s-1HTML. \s0 If that doesn't do it for you, then
by all means keep reading.
.PP
.Vb 2
\& 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;
.Ve
.PP
\&...or...
.PP
.Vb 2
\& 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 => \*(Aqcasey@geeknest.com\*(Aq ],
\& parts => [ @parts ],
\& );
\&
\& # nesting parts
\& $email\->parts_set(
\& [
\& $email\->parts,
\& Email::MIME\->create( parts => [ @parts ] ),
\& ],
\& );
\&
\& # standard modifications
\& $email\->header_str_set( \*(AqX\-PoweredBy\*(Aq => \*(AqRT v3.0\*(Aq );
\& $email\->header_str_set( To => rcpts() );
\& $email\->header_str_set( Cc => aux_rcpts() );
\& $email\->header_str_set( Bcc => sekrit_rcpts() );
\&
\& # more advanced
\& $_\->encoding_set( \*(Aqbase64\*(Aq ) for $email\->parts;
\&
\& # Quick multipart creation
\& my $quicky = Email::MIME\->create(
\& header_str => [
\& From => \*(Aqmy@address\*(Aq,
\& To => \*(Aqyour@address\*(Aq,
\& ],
\& parts => [
\& q[This is part one],
\& q[This is part two],
\& q[These could be binary too],
\& ],
\& );
\&
\& print $email\->as_string;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an extension of the Email::Simple module, to handle \s-1MIME\s0
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 \s-1MIME\s0 encoding.
.SH "METHODS"
.IX Header "METHODS"
Please see Email::Simple for the base set of methods. It won't take
very long. Added to that, you have:
.SS "create"
.IX Subsection "create"
.Vb 5
\& my $single = Email::MIME\->create(
\& header_str => [ ... ],
\& body_str => \*(Aq...\*(Aq,
\& attributes => { ... },
\& );
\&
\& my $multi = Email::MIME\->create(
\& header_str => [ ... ],
\& parts => [ ... ],
\& attributes => { ... },
\& );
.Ve
.PP
This method creates a new \s-1MIME\s0 part. The \f(CW\*(C`header_str\*(C'\fR 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 \f(CW\*(C`header\*(C'\fR
parameter can be provided in addition to or instead of \f(CW\*(C`header_str\*(C'\fR. Its
values will be used verbatim.
.PP
\&\f(CW\*(C`attributes\*(C'\fR is a hash of \s-1MIME\s0 attributes to assign to the part, and may
override portions of the header set in the \f(CW\*(C`header\*(C'\fR parameter.
.PP
The \f(CW\*(C`parts\*(C'\fR parameter is a list reference containing \f(CW\*(C`Email::MIME\*(C'\fR
objects. Elements of the \f(CW\*(C`parts\*(C'\fR list can also be a non-reference
string of data. In that case, an \f(CW\*(C`Email::MIME\*(C'\fR 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 \f(CW\*(C`base64\*(C'\fR, just in case.
.PP
If \f(CW\*(C`body\*(C'\fR is given instead of \f(CW\*(C`parts\*(C'\fR, it specifies the body to be used for a
flat (subpart-less) \s-1MIME\s0 message. It is assumed to be a sequence of octets.
.PP
If \f(CW\*(C`body_str\*(C'\fR is given instead of \f(CW\*(C`body\*(C'\fR or \f(CW\*(C`parts\*(C'\fR, it is assumed to be a
character string to be used as the body. If you provide a \f(CW\*(C`body_str\*(C'\fR
parameter, you \fBmust\fR provide \f(CW\*(C`charset\*(C'\fR and \f(CW\*(C`encoding\*(C'\fR attributes.
.PP
Back to \f(CW\*(C`attributes\*(C'\fR. The hash keys correspond directly to methods or
modifying a message from \f(CW\*(C`Email::MIME::Modifier\*(C'\fR. The allowed keys are:
content_type, charset, name, format, boundary, encoding, disposition,
and filename. They will be mapped to \f(CW"$attr\e_set"\fR for message
modification.
.SS "content_type_set"
.IX Subsection "content_type_set"
.Vb 1
\& $email\->content_type_set( \*(Aqtext/html\*(Aq );
.Ve
.PP
Change the content type. All \f(CW\*(C`Content\-Type\*(C'\fR header attributes
will remain intact.
.SS "charset_set"
.IX Subsection "charset_set"
.SS "name_set"
.IX Subsection "name_set"
.SS "format_set"
.IX Subsection "format_set"
.SS "boundary_set"
.IX Subsection "boundary_set"
.Vb 4
\& $email\->charset_set( \*(AqUTF\-8\*(Aq );
\& $email\->name_set( \*(Aqsome_filename.txt\*(Aq );
\& $email\->format_set( \*(Aqflowed\*(Aq );
\& $email\->boundary_set( undef ); # remove the boundary
.Ve
.PP
These four methods modify common \f(CW\*(C`Content\-Type\*(C'\fR attributes. If set to
\&\f(CW\*(C`undef\*(C'\fR, the attribute is removed. All other \f(CW\*(C`Content\-Type\*(C'\fR header
information is preserved when modifying an attribute.
.SS "encoding_set"
.IX Subsection "encoding_set"
.Vb 3
\& $email\->encoding_set( \*(Aqbase64\*(Aq );
\& $email\->encoding_set( \*(Aqquoted\-printable\*(Aq );
\& $email\->encoding_set( \*(Aq8bit\*(Aq );
.Ve
.PP
Convert the message body and alter the \f(CW\*(C`Content\-Transfer\-Encoding\*(C'\fR
header using this method. Your message body, the output of the \f(CW\*(C`body()\*(C'\fR
method, will remain the same. The raw body, output with the \f(CW\*(C`body_raw()\*(C'\fR
method, will be changed to reflect the new encoding.
.SS "body_set"
.IX Subsection "body_set"
.Vb 1
\& $email\->body_set( $unencoded_body_string );
.Ve
.PP
This method will encode the new body you send using the encoding
specified in the \f(CW\*(C`Content\-Transfer\-Encoding\*(C'\fR header, then set
the body to the new encoded body.
.PP
This method overrides the default \f(CW\*(C`body_set()\*(C'\fR method.
.SS "body_str_set"
.IX Subsection "body_str_set"
.Vb 1
\& $email\->body_str_set($unicode_str);
.Ve
.PP
This method behaves like \f(CW\*(C`body_set\*(C'\fR, but assumes that the given value is a
Unicode string that should be encoded into the message's charset
before being set.
.PP
The charset must already be set, either manually (via the \f(CW\*(C`attributes\*(C'\fR
argument to \f(CW\*(C`create\*(C'\fR or \f(CW\*(C`charset_set\*(C'\fR) or through the \f(CW\*(C`Content\-Type\*(C'\fR of a
parsed message. If the charset can't be determined, an exception is thrown.
.SS "disposition_set"
.IX Subsection "disposition_set"
.Vb 1
\& $email\->disposition_set( \*(Aqattachment\*(Aq );
.Ve
.PP
Alter the \f(CW\*(C`Content\-Disposition\*(C'\fR of a message. All header attributes
will remain intact.
.SS "filename_set"
.IX Subsection "filename_set"
.Vb 1
\& $email\->filename_set( \*(Aqboo.pdf\*(Aq );
.Ve
.PP
Sets the filename attribute in the \f(CW\*(C`Content\-Disposition\*(C'\fR header. All other
header information is preserved when setting this attribute.
.SS "parts_set"
.IX Subsection "parts_set"
.Vb 1
\& $email\->parts_set( \e@new_parts );
.Ve
.PP
Replaces the parts for an object. Accepts a reference to a list of
\&\f(CW\*(C`Email::MIME\*(C'\fR objects, representing the new parts. If this message was
originally a single part, the \f(CW\*(C`Content\-Type\*(C'\fR header will be changed to
\&\f(CW\*(C`multipart/mixed\*(C'\fR, and given a new boundary attribute.
.SS "parts_add"
.IX Subsection "parts_add"
.Vb 1
\& $email\->parts_add( \e@more_parts );
.Ve
.PP
Adds \s-1MIME\s0 parts onto the current \s-1MIME\s0 part. This is a simple extension
of \f(CW\*(C`parts_set\*(C'\fR to make our lives easier. It accepts an array reference
of additional parts.
.SS "walk_parts"
.IX Subsection "walk_parts"
.Vb 3
\& $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/]+>//; # simple filter example
\& $part\->body_set( $body );
\& }
\& });
.Ve
.PP
Walks through all the \s-1MIME\s0 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 \s-1MIME\s0 part within the
top-level \s-1MIME\s0 object. All changes will be applied in place.
.SS "header"
.IX Subsection "header"
\&\fBAchtung!\fR Beware this method! In Email::MIME, it means the same as
\&\f(CW\*(C`header_str\*(C'\fR, but on an Email::Simple object, it means \f(CW\*(C`header_raw\*(C'\fR. Unless
you always know what kind of object you have, you could get one of two
significantly different behaviors.
.PP
Try to use either \f(CW\*(C`header_str\*(C'\fR or \f(CW\*(C`header_raw\*(C'\fR as appropriate.
.SS "header_str_set"
.IX Subsection "header_str_set"
.Vb 1
\& $email\->header_str_set($header_name => @value_strings);
.Ve
.PP
This behaves like \f(CW\*(C`header_raw_set\*(C'\fR, but expects Unicode (character) strings as
the values to set, rather than pre-encoded byte strings. It will encode them
as \s-1MIME\s0 encoded-words if they contain any control or 8\-bit characters.
.SS "header_str_pairs"
.IX Subsection "header_str_pairs"
.Vb 1
\& my @pairs = $email\->header_str_pairs;
.Ve
.PP
This method behaves like \f(CW\*(C`header_raw_pairs\*(C'\fR, returning a list of field
name/value pairs, but the values have been decoded to character strings, when
possible.
.SS "parts"
.IX Subsection "parts"
This returns a list of \f(CW\*(C`Email::MIME\*(C'\fR objects reflecting the parts of the
message. If it's a single-part message, you get the original object back.
.PP
In scalar context, this method returns the number of parts.
.PP
This is a stupid method. Don't use it.
.SS "subparts"
.IX Subsection "subparts"
This returns a list of \f(CW\*(C`Email::MIME\*(C'\fR objects reflecting the parts of the
message. If it's a single-part message, this method returns an empty list.
.PP
In scalar context, this method returns the number of subparts.
.SS "body"
.IX Subsection "body"
This decodes and returns the body of the object \fIas a byte string\fR. For
top-level objects in multi-part messages, this is highly likely to be something
like \*(L"This is a multi-part message in \s-1MIME\s0 format.\*(R"
.SS "body_str"
.IX Subsection "body_str"
This decodes both the Content-Transfer-Encoding layer of the body (like the
\&\f(CW\*(C`body\*(C'\fR method) as well as the charset encoding of the body (unlike the \f(CW\*(C`body\*(C'\fR
method), returning a Unicode string.
.PP
If the charset is known, it is used. If there is no charset but the content
type is either \f(CW\*(C`text/plain\*(C'\fR or \f(CW\*(C`text/html\*(C'\fR, us-ascii is assumed. Otherwise,
an exception is thrown.
.SS "body_raw"
.IX Subsection "body_raw"
This returns the body of the object, but doesn't decode the transfer encoding.
.SS "decode_hook"
.IX Subsection "decode_hook"
This method is called before the Email::MIME::Encodings \f(CW\*(C`decode\*(C'\fR method, to
decode the body of non-binary messages (or binary messages, if the
\&\f(CW\*(C`force_decode_hook\*(C'\fR method returns true). By default, this method does
nothing, but subclasses may define behavior.
.PP
This method could be used to implement the decryption of content in secure
email, for example.
.SS "content_type"
.IX Subsection "content_type"
This is a shortcut for access to the content type header.
.SS "filename"
.IX Subsection "filename"
This provides the suggested filename for the attachment part. Normally
it will return the filename from the headers, but if \f(CW\*(C`filename\*(C'\fR is
passed a true parameter, it will generate an appropriate \*(L"stable\*(R"
filename if one is not found in the \s-1MIME\s0 headers.
.SS "invent_filename"
.IX Subsection "invent_filename"
.Vb 1
\& my $filename = Email::MIME\->invent_filename($content_type);
.Ve
.PP
This routine is used by \f(CW\*(C`filename\*(C'\fR to generate filenames for attached files.
It will attempt to choose a reasonable extension, falling back to \fIdat\fR.
.SS "debug_structure"
.IX Subsection "debug_structure"
.Vb 1
\& my $description = $email\->debug_structure;
.Ve
.PP
This method returns a string that describes the structure of the \s-1MIME\s0 entity.
For example:
.PP
.Vb 3
\& + multipart/alternative; boundary="=_NextPart_2"; charset="BIG\-5"
\& + text/plain
\& + text/html
.Ve
.SH "TODO"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Email::Simple, Email::MIME::Modifier, Email::MIME::Creator.
.SH "THANKS"
.IX Header "THANKS"
This module was generously sponsored by Best Practical
(http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Ricardo \s-1SIGNES\s0
.IP "\(bu" 4
Casey West
.IP "\(bu" 4
Simon Cozens
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Alex Vandiver
.IP "\(bu" 4
Arthur Axel 'fREW' Schmidt
.IP "\(bu" 4
Brian Cassidy
.IP "\(bu" 4
David Steinbrunner
.IP "\(bu" 4
Dotan Dimet
.IP "\(bu" 4
Geraint Edwards
.IP "\(bu" 4
Jesse Luehrs
.IP "\(bu" 4
Kurt Anderson
.IP "\(bu" 4
Lance A. Brown
.IP "\(bu" 4
Matthew Horsfall (alh)
.IP "\(bu" 4
memememomo
.IP "\(bu" 4
Shawn Sorichetti
.IP "\(bu" 4
Tomohiro Hosaka
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2004 by Simon Cozens and Casey West.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.