Email-MIME
view release on metacpan or search on metacpan
lib/Email/MIME.pm view on Meta::CPAN
use v5.12.0;
use warnings;
package Email::MIME 1.954;
# ABSTRACT: easy MIME message handling
use Email::Simple 2.212; # nth header value
use parent qw(Email::Simple);
use Carp ();
use Email::MessageID;
use Email::MIME::Creator;
use Email::MIME::ContentType 1.023; # build_content_type
use Email::MIME::Encode;
use Email::MIME::Encodings 1.314;
use Email::MIME::Header;
use Encode 1.9801 ();
use Scalar::Util qw(reftype weaken);
our @CARP_NOT = qw(Email::MIME::ContentType);
our $MAX_DEPTH = 10;
our $CUR_PARTS = 0;
our $MAX_PARTS = 100;
#pod =head1 SYNOPSIS
#pod
#pod B<Wait!> Before you read this, maybe you just need L<Email::Stuffer>, which is
#pod a much easier-to-use tool for building simple email messages that might have
#pod attachments or both plain text and HTML. If that doesn't do it for you, then
#pod by all means keep reading.
#pod
#pod use Email::MIME;
#pod my $parsed = Email::MIME->new($message);
#pod
#pod my @parts = $parsed->parts; # These will be Email::MIME objects, too.
#pod my $decoded = $parsed->body;
#pod my $non_decoded = $parsed->body_raw;
#pod
#pod my $content_type = $parsed->content_type;
#pod
#pod ...or...
#pod
#pod use Email::MIME;
#pod use IO::All;
#pod
#pod # multipart message
#pod my @parts = (
#pod Email::MIME->create(
#pod attributes => {
#pod filename => "report.pdf",
#pod content_type => "application/pdf",
#pod encoding => "quoted-printable",
#pod name => "2004-financials.pdf",
#pod },
#pod body => io( "2004-financials.pdf" )->binary->all,
#pod ),
#pod Email::MIME->create(
#pod attributes => {
#pod content_type => "text/plain",
#pod disposition => "attachment",
#pod charset => "US-ASCII",
#pod },
#pod body_str => "Hello there!",
#pod ),
#pod );
#pod
#pod my $email = Email::MIME->create(
#pod header_str => [
#pod From => 'casey@geeknest.com',
#pod To => [ 'user1@host.com', 'Name <user2@host.com>' ],
#pod Cc => Email::Address::XS->new("Display Name \N{U+1F600}", 'user@example.com'),
#pod ],
#pod parts => [ @parts ],
#pod );
#pod
#pod # nesting parts
#pod $email->parts_set(
#pod [
#pod $email->parts,
#pod Email::MIME->create( parts => [ @parts ] ),
#pod ],
#pod );
#pod
#pod # standard modifications
#pod $email->header_str_set( 'X-PoweredBy' => 'RT v3.0' );
#pod $email->header_str_set( To => rcpts() );
#pod $email->header_str_set( Cc => aux_rcpts() );
#pod $email->header_str_set( Bcc => sekrit_rcpts() );
#pod
#pod # more advanced
#pod $_->encoding_set( 'base64' ) for $email->parts;
#pod
#pod # Quick multipart creation
#pod my $email = Email::MIME->create(
#pod header_str => [
#pod From => 'my@address',
#pod To => 'your@address',
#pod ],
#pod parts => [
#pod q[This is part one],
#pod q[This is part two],
#pod q[These could be binary too],
#pod ],
#pod );
#pod
#pod print $email->as_string;
#pod
#pod =head1 DESCRIPTION
#pod
#pod This is an extension of the L<Email::Simple> module, to handle MIME
#pod encoded messages. It takes a message as a string, splits it up into its
#pod constituent parts, and allows you access to various parts of the
#pod message. Headers are decoded from MIME encoding.
#pod
#pod =head1 METHODS
#pod
#pod Please see L<Email::Simple> for the base set of methods. It won't take
#pod very long. Added to that, you have:
#pod
#pod =cut
our $CREATOR = 'Email::MIME::Creator';
my $NO_ENCODE_RE = qr/
\A
(?:7bit|8bit|binary)\s*(?:;|$)
/ix;
sub new {
local $CUR_PARTS = 0;
my ($class, @rest) = @_;
$class->_new(@rest);
}
sub _new {
my ($class, $text, $arg, @rest) = @_;
$arg ||= {};
my $encode_check = exists $arg->{encode_check}
? delete $arg->{encode_check}
: Encode::FB_CROAK;
my $self = shift->SUPER::new($text, $arg, @rest);
$self->encode_check_set($encode_check);
$self->{ct} = parse_content_type($self->content_type_raw);
$self->parts;
return $self;
}
#pod =method create
#pod
#pod my $single = Email::MIME->create(
#pod header_str => [ ... ],
#pod body_str => '...',
#pod attributes => { ... },
#pod );
#pod
#pod my $multi = Email::MIME->create(
#pod header_str => [ ... ],
#pod parts => [ ... ],
#pod attributes => { ... },
#pod );
#pod
#pod This method creates a new MIME part. The C<header_str> parameter is a list of
#pod headers pairs to include in the message. The value for each pair is expected to
#pod be a text string that will be MIME-encoded as needed. Alternatively it can be
#pod an object with C<as_mime_string> method which implements conversion of that
#pod object to MIME-encoded string. That object method is called with two named
#pod input parameters: C<charset> and C<header_name_length>. It should return
#pod MIME-encoded representation of the object. As of 2017-07-25, the
#pod header-value-as-object code is very young, and may yet change.
#pod
#pod In case header name is registered in C<%Email::MIME::Header::header_to_class_map>
lib/Email/MIME.pm view on Meta::CPAN
my $ct = build_content_type({type => $ct_header->{type}, subtype => $ct_header->{subtype}, attributes => $ct_header->{attributes}});
$self->header_raw_set('Content-Type' => $ct);
$self->{ct} = $ct_header;
}
sub _get_cid {
Email::MessageID->new->address;
}
sub _reset_cids {
my ($self) = @_;
my $ct_header = parse_content_type($self->header('Content-Type'));
if ($self->parts > 1) {
if ($ct_header->{subtype} eq 'alternative') {
my %cids;
for my $part ($self->parts) {
my $cid = $part->header('Content-ID') // q{};
$cids{$cid}++;
}
return if keys(%cids) == 1;
my $cid = $self->_get_cid;
$_->header_raw_set('Content-ID' => "<$cid>") for $self->parts;
} else {
foreach ($self->parts) {
my $cid = $self->_get_cid;
$_->header_raw_set('Content-ID' => "<$cid>")
unless $_->header('Content-ID');
}
}
}
}
1;
=pod
=encoding UTF-8
=head1 NAME
Email::MIME - easy MIME message handling
=head1 VERSION
version 1.954
=head1 SYNOPSIS
B<Wait!> Before you read this, maybe you just need L<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',
To => [ 'user1@host.com', 'Name <user2@host.com>' ],
Cc => Email::Address::XS->new("Display Name \N{U+1F600}", 'user@example.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 $email = 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;
=head1 DESCRIPTION
This is an extension of the L<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.
=head1 PERL VERSION
This library should run on perls released even a long time ago. It should
work on any version of perl released in the last five years.
Although it may work on older versions of perl, no guarantee is made that the
minimum required version will not be increased. The version may be increased
for any reason, and there is no promise that patches will be accepted to
lower the minimum required perl.
=head1 METHODS
Please see L<Email::Simple> for the base set of methods. It won't take
very long. Added to that, you have:
=head2 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 C<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. Alternatively it can be
an object with C<as_mime_string> method which implements conversion of that
object to MIME-encoded string. That object method is called with two named
input parameters: C<charset> and C<header_name_length>. It should return
MIME-encoded representation of the object. As of 2017-07-25, the
header-value-as-object code is very young, and may yet change.
In case header name is registered in C<%Email::MIME::Header::header_to_class_map>
hash then registered class is used for conversion from Unicode string to 8bit
MIME encoding. Value can be either string or array reference to strings.
Object is constructed via method C<from_string> with string value (or values
in case of array reference) and converted to MIME-encoded string via
C<as_mime_string> method.
A similar C<header> parameter can be provided in addition to or instead of
C<header_str>. Its values will be used verbatim.
C<attributes> is a hash of MIME attributes to assign to the part, and may
override portions of the header set in the C<header> parameter. The hash keys
correspond directly to methods for modifying a message. The allowed keys are:
content_type, charset, name, format, boundary, encoding, disposition, and
filename. They will be mapped to C<"$attr\_set"> for message modification.
The C<parts> parameter is a list reference containing C<Email::MIME>
objects. Elements of the C<parts> list can also be a non-reference
string of data. In that case, an C<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 C<base64>, just in case.
lib/Email/MIME.pm view on Meta::CPAN
=head2 parts_set
$email->parts_set( \@new_parts );
Replaces the parts for an object. Accepts a reference to a list of
C<Email::MIME> objects, representing the new parts. If this message was
originally a single part, the C<Content-Type> header will be changed to
C<multipart/mixed>, and given a new boundary attribute.
=head2 parts_add
$email->parts_add( \@more_parts );
Adds MIME parts onto the current MIME part. This is a simple extension
of C<parts_set> to make our lives easier. It accepts an array reference
of additional parts.
=head2 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.
=head2 header
B<Achtung!> Beware this method! In Email::MIME, it means the same as
C<header_str>, but on an Email::Simple object, it means C<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 C<header_str> or C<header_raw> as appropriate.
=head2 header_str_set
$email->header_str_set($header_name => @value_strings);
This behaves like C<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.
Alternatively, values can be objects with C<as_mime_string> method. Same as in
method C<create>.
=head2 header_str_pairs
my @pairs = $email->header_str_pairs;
This method behaves like C<header_raw_pairs>, returning a list of field
name/value pairs, but the values have been decoded to character strings, when
possible.
=head2 header_as_obj
my $first_obj = $email->header_as_obj($field);
my $nth_obj = $email->header_as_obj($field, $index);
my @all_objs = $email->header_as_obj($field);
my $nth_obj_of_class = $email->header_as_obj($field, $index, $class);
my @all_objs_of_class = $email->header_as_obj($field, undef, $class);
This method returns an object representation of the header value. It instances
new object via method C<from_mime_string> of specified class. Input argument
for that class method is list of the raw MIME-encoded values. If class argument
is not specified then class name is taken from the hash
C<%Email::MIME::Header::header_to_class_map> via key field. Use class method
C<< Email::MIME::Header->set_class_for_header($class, $field) >> for adding new
mapping.
=head2 parts
This returns a list of C<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.
=head2 subparts
This returns a list of C<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.
=head2 body
This decodes and returns the body of the object I<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."
=head2 body_str
This decodes both the Content-Transfer-Encoding layer of the body (like the
C<body> method) as well as the charset encoding of the body (unlike the C<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 C<text/plain> or C<text/html>, us-ascii is assumed. Otherwise,
an exception is thrown.
=head2 body_raw
This returns the body of the object, but doesn't decode the transfer encoding.
=head2 decode_hook
This method is called before the L<Email::MIME::Encodings> C<decode> method, to
decode the body of non-binary messages (or binary messages, if the
C<force_decode_hook> method returns true). By default, this method does
lib/Email/MIME.pm view on Meta::CPAN
Mishrakk <48946018+Mishrakk@users.noreply.github.com>
=item *
Pali <pali@cpan.org>
=item *
Ricardo Signes <rjbs@semiotic.systems>
=item *
Ricardo Signes <rjbs@users.noreply.github.com>
=item *
Shawn Sorichetti <ssoriche@coloredblocks.com>
=item *
Tomohiro Hosaka <bokutin@bokut.in>
=back
=head1 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.
=cut
__END__
#pod =method header
#pod
#pod B<Achtung!> Beware this method! In Email::MIME, it means the same as
#pod C<header_str>, but on an Email::Simple object, it means C<header_raw>. Unless
#pod you always know what kind of object you have, you could get one of two
#pod significantly different behaviors.
#pod
#pod Try to use either C<header_str> or C<header_raw> as appropriate.
#pod
#pod =method header_str_set
#pod
#pod $email->header_str_set($header_name => @value_strings);
#pod
#pod This behaves like C<header_raw_set>, but expects Unicode (character) strings as
#pod the values to set, rather than pre-encoded byte strings. It will encode them
#pod as MIME encoded-words if they contain any control or 8-bit characters.
#pod
#pod Alternatively, values can be objects with C<as_mime_string> method. Same as in
#pod method C<create>.
#pod
#pod =method header_str_pairs
#pod
#pod my @pairs = $email->header_str_pairs;
#pod
#pod This method behaves like C<header_raw_pairs>, returning a list of field
#pod name/value pairs, but the values have been decoded to character strings, when
#pod possible.
#pod
#pod =method header_as_obj
#pod
#pod my $first_obj = $email->header_as_obj($field);
#pod my $nth_obj = $email->header_as_obj($field, $index);
#pod my @all_objs = $email->header_as_obj($field);
#pod
#pod my $nth_obj_of_class = $email->header_as_obj($field, $index, $class);
#pod my @all_objs_of_class = $email->header_as_obj($field, undef, $class);
#pod
#pod This method returns an object representation of the header value. It instances
#pod new object via method C<from_mime_string> of specified class. Input argument
#pod for that class method is list of the raw MIME-encoded values. If class argument
#pod is not specified then class name is taken from the hash
#pod C<%Email::MIME::Header::header_to_class_map> via key field. Use class method
#pod C<< Email::MIME::Header->set_class_for_header($class, $field) >> for adding new
#pod mapping.
#pod
#pod =method parts
#pod
#pod This returns a list of C<Email::MIME> objects reflecting the parts of the
#pod message. If it's a single-part message, you get the original object back.
#pod
#pod In scalar context, this method returns the number of parts.
#pod
#pod This is a stupid method. Don't use it.
#pod
#pod =method subparts
#pod
#pod This returns a list of C<Email::MIME> objects reflecting the parts of the
#pod message. If it's a single-part message, this method returns an empty list.
#pod
#pod In scalar context, this method returns the number of subparts.
#pod
#pod =method body
#pod
#pod This decodes and returns the body of the object I<as a byte string>. For
#pod top-level objects in multi-part messages, this is highly likely to be something
#pod like "This is a multi-part message in MIME format."
#pod
#pod =method body_str
#pod
#pod This decodes both the Content-Transfer-Encoding layer of the body (like the
#pod C<body> method) as well as the charset encoding of the body (unlike the C<body>
#pod method), returning a Unicode string.
#pod
#pod If the charset is known, it is used. If there is no charset but the content
#pod type is either C<text/plain> or C<text/html>, us-ascii is assumed. Otherwise,
#pod an exception is thrown.
#pod
#pod =method body_raw
#pod
#pod This returns the body of the object, but doesn't decode the transfer encoding.
#pod
#pod =method decode_hook
#pod
#pod This method is called before the L<Email::MIME::Encodings> C<decode> method, to
#pod decode the body of non-binary messages (or binary messages, if the
#pod C<force_decode_hook> method returns true). By default, this method does
( run in 0.702 second using v1.01-cache-2.11-cpan-c966e8aa7e8 )