MAN page from RedHat EL 7 perl-Email-MIME-1.926-2.1.noarch.rpm

Email::MIME

Section: User Contributed Perl Documentation (3)
Updated: 2017-06-22
Index

NAME

Email::MIME - easy MIME message handling

VERSION

version 1.926

SYNOPSIS

Wait! Before you read this, maybe you just need Email::Stuffer, which isa much easier-to-use tool for building simple email messages that might haveattachments or both plain text and HTML. If that doesn't do it for you, thenby 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::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_str => "Hello there!",      ),  );  my $email = Email::MIME->create(      header_str => [ From => 'caseyAATTgeeknest.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 => 'myAATTaddress',          To   => 'yourAATTaddress',      ],      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 MIMEencoded messages. It takes a message as a string, splits it up into itsconstituent parts, and allows you access to various parts of themessage. Headers are decoded from MIME encoding.

METHODS

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 ofheaders pairs to include in the message. The value for each pair is expected tobe 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". Itsvalues will be used verbatim.

"attributes" is a hash of MIME attributes to assign to the part, and mayoverride 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-referencestring of data. In that case, an "Email::MIME" object will be createdfor you. Simple checks will determine if the part is binary or not, andall 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 aflat (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 acharacter 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 ormodifying 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 messagemodification.

content_type_set

  $email->content_type_set( 'text/html' );

Change the content type. All "Content-Type" header attributeswill 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" headerinformation 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 encodingspecified in the "Content-Transfer-Encoding" header, then setthe 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 aUnicode string that should be encoded into the message's charsetbefore 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 aparsed 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 attributeswill remain intact.

filename_set

  $email->filename_set( 'boo.pdf' );

Sets the filename attribute in the "Content-Disposition" header. All otherheader 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 wasoriginally 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 extensionof "parts_set" to make our lives easier. It accepts an array referenceof 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 toeach. Accepts a code reference as its only argument. The code referencewill be passed a single argument, the current MIME part within thetop-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 thevalues to set, rather than pre-encoded byte strings. It will encode them asMIME encoded-words if they contain any control or 8-bit characters.

parts

This returns a list of "Email::MIME" objects reflecting the parts of themessage. 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 themessage. 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. Fortop-level objects in multi-part messages, this is highly likely to be somethinglike ``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 contenttype 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, todecode the body of non-binary messages (or binary messages, if the"force_decode_hook" method returns true). By default, this method doesnothing, but subclasses may define behavior.

This method could be used to implement the decryption of content in secureemail, 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. Normallyit will return the filename from the headers, but if "filename" ispassed 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

METHODS

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

TODO

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