1use 5.008001; 2use strict; 3use warnings; 4package Email::MIME; 5# ABSTRACT: easy MIME message handling 6$Email::MIME::VERSION = '1.952'; 7use Email::Simple 2.212; # nth header value 8use parent qw(Email::Simple); 9 10use Carp (); 11use Email::MessageID; 12use Email::MIME::Creator; 13use Email::MIME::ContentType 1.023; # build_content_type 14use Email::MIME::Encode; 15use Email::MIME::Encodings 1.314; 16use Email::MIME::Header; 17use Email::MIME::Modifier; 18use Encode 1.9801 (); 19use Scalar::Util qw(reftype weaken); 20 21our @CARP_NOT = qw(Email::MIME::ContentType); 22 23#pod =head1 SYNOPSIS 24#pod 25#pod B<Wait!> Before you read this, maybe you just need L<Email::Stuffer>, which is 26#pod a much easier-to-use tool for building simple email messages that might have 27#pod attachments or both plain text and HTML. If that doesn't do it for you, then 28#pod by all means keep reading. 29#pod 30#pod use Email::MIME; 31#pod my $parsed = Email::MIME->new($message); 32#pod 33#pod my @parts = $parsed->parts; # These will be Email::MIME objects, too. 34#pod my $decoded = $parsed->body; 35#pod my $non_decoded = $parsed->body_raw; 36#pod 37#pod my $content_type = $parsed->content_type; 38#pod 39#pod ...or... 40#pod 41#pod use Email::MIME; 42#pod use IO::All; 43#pod 44#pod # multipart message 45#pod my @parts = ( 46#pod Email::MIME->create( 47#pod attributes => { 48#pod filename => "report.pdf", 49#pod content_type => "application/pdf", 50#pod encoding => "quoted-printable", 51#pod name => "2004-financials.pdf", 52#pod }, 53#pod body => io( "2004-financials.pdf" )->binary->all, 54#pod ), 55#pod Email::MIME->create( 56#pod attributes => { 57#pod content_type => "text/plain", 58#pod disposition => "attachment", 59#pod charset => "US-ASCII", 60#pod }, 61#pod body_str => "Hello there!", 62#pod ), 63#pod ); 64#pod 65#pod my $email = Email::MIME->create( 66#pod header_str => [ 67#pod From => 'casey@geeknest.com', 68#pod To => [ 'user1@host.com', 'Name <user2@host.com>' ], 69#pod Cc => Email::Address::XS->new("Display Name \N{U+1F600}", 'user@example.com'), 70#pod ], 71#pod parts => [ @parts ], 72#pod ); 73#pod 74#pod # nesting parts 75#pod $email->parts_set( 76#pod [ 77#pod $email->parts, 78#pod Email::MIME->create( parts => [ @parts ] ), 79#pod ], 80#pod ); 81#pod 82#pod # standard modifications 83#pod $email->header_str_set( 'X-PoweredBy' => 'RT v3.0' ); 84#pod $email->header_str_set( To => rcpts() ); 85#pod $email->header_str_set( Cc => aux_rcpts() ); 86#pod $email->header_str_set( Bcc => sekrit_rcpts() ); 87#pod 88#pod # more advanced 89#pod $_->encoding_set( 'base64' ) for $email->parts; 90#pod 91#pod # Quick multipart creation 92#pod my $email = Email::MIME->create( 93#pod header_str => [ 94#pod From => 'my@address', 95#pod To => 'your@address', 96#pod ], 97#pod parts => [ 98#pod q[This is part one], 99#pod q[This is part two], 100#pod q[These could be binary too], 101#pod ], 102#pod ); 103#pod 104#pod print $email->as_string; 105#pod 106#pod =head1 DESCRIPTION 107#pod 108#pod This is an extension of the L<Email::Simple> module, to handle MIME 109#pod encoded messages. It takes a message as a string, splits it up into its 110#pod constituent parts, and allows you access to various parts of the 111#pod message. Headers are decoded from MIME encoding. 112#pod 113#pod =head1 METHODS 114#pod 115#pod Please see L<Email::Simple> for the base set of methods. It won't take 116#pod very long. Added to that, you have: 117#pod 118#pod =cut 119 120our $CREATOR = 'Email::MIME::Creator'; 121 122my $NO_ENCODE_RE = qr/ 123 \A 124 (?:7bit|8bit|binary)\s*(?:;|$) 125/ix; 126 127sub new { 128 my ($class, $text, $arg, @rest) = @_; 129 $arg ||= {}; 130 131 my $encode_check = exists $arg->{encode_check} 132 ? delete $arg->{encode_check} 133 : Encode::FB_CROAK; 134 135 my $self = shift->SUPER::new($text, $arg, @rest); 136 $self->encode_check_set($encode_check); 137 $self->{ct} = parse_content_type($self->content_type_raw); 138 $self->parts; 139 return $self; 140} 141 142#pod =method create 143#pod 144#pod my $single = Email::MIME->create( 145#pod header_str => [ ... ], 146#pod body_str => '...', 147#pod attributes => { ... }, 148#pod ); 149#pod 150#pod my $multi = Email::MIME->create( 151#pod header_str => [ ... ], 152#pod parts => [ ... ], 153#pod attributes => { ... }, 154#pod ); 155#pod 156#pod This method creates a new MIME part. The C<header_str> parameter is a list of 157#pod headers pairs to include in the message. The value for each pair is expected to 158#pod be a text string that will be MIME-encoded as needed. Alternatively it can be 159#pod an object with C<as_mime_string> method which implements conversion of that 160#pod object to MIME-encoded string. That object method is called with two named 161#pod input parameters: C<charset> and C<header_name_length>. It should return 162#pod MIME-encoded representation of the object. As of 2017-07-25, the 163#pod header-value-as-object code is very young, and may yet change. 164#pod 165#pod In case header name is registered in C<%Email::MIME::Header::header_to_class_map> 166#pod hash then registered class is used for conversion from Unicode string to 8bit 167#pod MIME encoding. Value can be either string or array reference to strings. 168#pod Object is constructed via method C<from_string> with string value (or values 169#pod in case of array reference) and converted to MIME-encoded string via 170#pod C<as_mime_string> method. 171#pod 172#pod A similar C<header> parameter can be provided in addition to or instead of 173#pod C<header_str>. Its values will be used verbatim. 174#pod 175#pod C<attributes> is a hash of MIME attributes to assign to the part, and may 176#pod override portions of the header set in the C<header> parameter. The hash keys 177#pod correspond directly to methods for modifying a message from 178#pod C<Email::MIME::Modifier>. The allowed keys are: content_type, charset, name, 179#pod format, boundary, encoding, disposition, and filename. They will be mapped to 180#pod C<"$attr\_set"> for message modification. 181#pod 182#pod The C<parts> parameter is a list reference containing C<Email::MIME> 183#pod objects. Elements of the C<parts> list can also be a non-reference 184#pod string of data. In that case, an C<Email::MIME> object will be created 185#pod for you. Simple checks will determine if the part is binary or not, and 186#pod all parts created in this fashion are encoded with C<base64>, just in case. 187#pod 188#pod If C<body> is given instead of C<parts>, it specifies the body to be used for a 189#pod flat (subpart-less) MIME message. It is assumed to be a sequence of octets. 190#pod 191#pod If C<body_str> is given instead of C<body> or C<parts>, it is assumed to be a 192#pod character string to be used as the body. If you provide a C<body_str> 193#pod parameter, you B<must> provide C<charset> and C<encoding> attributes. 194#pod 195#pod =cut 196 197my %CT_SETTER = map {; $_ => 1 } qw( 198 content_type charset name format boundary 199 encoding 200 disposition filename 201); 202 203sub create { 204 my ($class, %args) = @_; 205 206 my $header = ''; 207 my %headers; 208 if (exists $args{header}) { 209 my @headers = @{ $args{header} }; 210 pop @headers if @headers % 2 == 1; 211 while (my ($key, $value) = splice @headers, 0, 2) { 212 $headers{$key} = 1; 213 $CREATOR->_add_to_header(\$header, $key, $value); 214 } 215 } 216 217 if (exists $args{header_str}) { 218 my @headers = @{ $args{header_str} }; 219 pop @headers if @headers % 2 == 1; 220 while (my ($key, $value) = splice @headers, 0, 2) { 221 $headers{$key} = 1; 222 223 $value = Email::MIME::Encode::maybe_mime_encode_header( 224 $key, $value, 'UTF-8' 225 ); 226 $CREATOR->_add_to_header(\$header, $key, $value); 227 } 228 } 229 230 $CREATOR->_add_to_header(\$header, Date => $CREATOR->_date_header) 231 unless exists $headers{Date}; 232 $CREATOR->_add_to_header(\$header, 'MIME-Version' => '1.0',); 233 234 my %attrs = $args{attributes} ? %{ $args{attributes} } : (); 235 236 # XXX: This is awful... but if we don't do this, then Email::MIME->new will 237 # end up calling parse_content_type($self->content_type) which will mean 238 # parse_content_type(undef) which, for some reason, returns the default. 239 # It's really sort of mind-boggling. Anyway, the default ends up being 240 # q{text/plain; charset="us-ascii"} so that if content_type is in the 241 # attributes, but not charset, then charset isn't changed and you up with 242 # something that's q{image/jpeg; charset="us-ascii"} and you look like a 243 # moron. -- rjbs, 2009-01-20 244 if ( 245 grep { exists $attrs{$_} } qw(content_type charset name format boundary) 246 ) { 247 $CREATOR->_add_to_header(\$header, 'Content-Type' => 'text/plain',); 248 } 249 250 my %pass_on; 251 252 if (exists $args{encode_check}) { 253 $pass_on{encode_check} = $args{encode_check}; 254 } 255 256 my $email = $class->new($header, \%pass_on); 257 258 for my $key (sort keys %attrs) { 259 $email->content_type_attribute_set($key => $attrs{$key}); 260 } 261 262 my $body_args = grep { defined $args{$_} } qw(parts body body_str); 263 Carp::confess("only one of parts, body, or body_str may be given") 264 if $body_args > 1; 265 266 if ($args{parts} && @{ $args{parts} }) { 267 foreach my $part (@{ $args{parts} }) { 268 $part = $CREATOR->_construct_part($part) 269 unless ref($part); 270 } 271 $email->parts_set($args{parts}); 272 } elsif (defined $args{body}) { 273 $email->body_set($args{body}); 274 } elsif (defined $args{body_str}) { 275 Carp::confess("body_str was given, but no charset is defined") 276 unless my $charset = $attrs{charset}; 277 278 Carp::confess("body_str was given, but no encoding is defined") 279 unless $attrs{encoding}; 280 281 my $body_octets = Encode::encode($attrs{charset}, $args{body_str}, $email->encode_check); 282 $email->body_set($body_octets); 283 } 284 285 $email; 286} 287 288sub as_string { 289 my $self = shift; 290 return $self->__head->as_string 291 . ($self->{mycrlf} || "\n") # XXX: replace with ->crlf 292 . $self->body_raw; 293} 294 295sub parts { 296 my $self = shift; 297 298 $self->fill_parts unless $self->{parts}; 299 300 my @parts = @{ $self->{parts} }; 301 @parts = $self unless @parts; 302 return @parts; 303} 304 305sub subparts { 306 my ($self) = @_; 307 308 $self->fill_parts unless $self->{parts}; 309 my @parts = @{ $self->{parts} }; 310 return @parts; 311} 312 313sub fill_parts { 314 my $self = shift; 315 316 if ( 317 $self->{ct}{type} eq "multipart" 318 or $self->{ct}{type} eq "message" 319 ) { 320 $self->parts_multipart; 321 } else { 322 $self->parts_single_part; 323 } 324 325 return $self; 326} 327 328sub body { 329 my $self = shift; 330 my $body = $self->SUPER::body; 331 my $cte = $self->header("Content-Transfer-Encoding") || ''; 332 333 $cte =~ s/\A\s+//; 334 $cte =~ s/\s+\z//; 335 $cte =~ s/;.+//; # For S/MIME, etc. 336 337 return $body unless $cte; 338 339 if (!$self->force_decode_hook and $cte =~ $NO_ENCODE_RE) { 340 return $body; 341 } 342 343 $body = $self->decode_hook($body) if $self->can("decode_hook"); 344 345 $body = Email::MIME::Encodings::decode($cte, $body, '7bit'); 346 return $body; 347} 348 349sub parts_single_part { 350 my $self = shift; 351 $self->{parts} = []; 352 return $self; 353} 354 355sub body_raw { 356 return $_[0]->{body_raw} || $_[0]->SUPER::body; 357} 358 359sub body_str { 360 my ($self) = @_; 361 my $encoding = $self->{ct}{attributes}{charset}; 362 363 unless ($encoding) { 364 if ($self->{ct}{type} eq 'text' 365 and 366 ($self->{ct}{subtype} eq 'plain' or $self->{ct}{subtype} eq 'html') 367 ) { 368 369 # assume that plaintext or html without ANY charset is us-ascii 370 return $self->body; 371 } 372 373 Carp::confess("can't get body as a string for " . $self->content_type); 374 } 375 376 my $str = Encode::decode($encoding, $self->body, $self->encode_check); 377 return $str; 378} 379 380our $MAX_DEPTH = 10; 381 382sub parts_multipart { 383 my $self = shift; 384 my $boundary = $self->{ct}->{attributes}->{boundary}; 385 386 our $DEPTH ||= 0; 387 388 Carp::croak("attempted to parse a MIME message more than $MAX_DEPTH deep") 389 if $MAX_DEPTH && $DEPTH > $MAX_DEPTH; 390 391 # Take a message, join all its lines together. Now try to Email::MIME->new 392 # it with 1.861 or earlier. Death! It tries to recurse endlessly on the 393 # body, because every time it splits on boundary it gets itself. Obviously 394 # that means it's a bogus message, but a mangled result (or exception) is 395 # better than endless recursion. -- rjbs, 2008-01-07 396 return $self->parts_single_part 397 unless defined $boundary and length $boundary and 398 $self->body_raw =~ /^--\Q$boundary\E\s*$/sm; 399 400 $self->{body_raw} = $self->SUPER::body; 401 402 # rfc1521 7.2.1 403 my ($body, $epilogue) = split /^--\Q$boundary\E--\s*$/sm, $self->body_raw, 2; 404 405 my @bits = split /^--\Q$boundary\E\s*$/sm, ($body || ''); 406 407 $self->SUPER::body_set(undef); 408 409 # If there are no headers in the potential MIME part, it's just part of the 410 # body. This is a horrible hack, although it's debatable whether it was 411 # better or worse when it was $self->{body} = shift @bits ... -- rjbs, 412 # 2006-11-27 413 $self->SUPER::body_set(shift @bits) if index(($bits[0] || ''), ':') == -1; 414 415 my $bits = @bits; 416 417 my @parts; 418 for my $bit (@bits) { 419 $bit =~ s/\A[\n\r]+//smg; 420 $bit =~ s/(?<!\x0d)$self->{mycrlf}\Z//sm; 421 local $DEPTH = $DEPTH + 1; 422 my $email = (ref $self)->new($bit, { encode_check => $self->encode_check }); 423 push @parts, $email; 424 } 425 426 $self->{parts} = \@parts; 427 428 return @{ $self->{parts} }; 429} 430 431sub force_decode_hook { 0 } 432sub decode_hook { return $_[1] } 433sub content_type { scalar shift->header("Content-type"); } 434sub content_type_raw { scalar shift->header_raw("Content-type"); } 435 436sub debug_structure { 437 my ($self, $level) = @_; 438 $level ||= 0; 439 my $rv = " " x (5 * $level); 440 $rv .= "+ " . ($self->content_type || '') . "\n"; 441 my @parts = $self->subparts; 442 $rv .= $_->debug_structure($level + 1) for @parts; 443 return $rv; 444} 445 446my %gcache; 447 448sub filename { 449 my ($self, $force) = @_; 450 return $gcache{$self} if exists $gcache{$self}; 451 452 my $dis = $self->header_raw("Content-Disposition") || ''; 453 my $attrs = parse_content_disposition($dis)->{attributes}; 454 my $name = $attrs->{filename} 455 || $self->{ct}{attributes}{name}; 456 return $name if $name or !$force; 457 return $gcache{$self} = $self->invent_filename( 458 $self->{ct}->{type} . "/" . $self->{ct}->{subtype}); 459} 460 461my $gname = 0; 462 463sub invent_filename { 464 my ($self, $ct) = @_; 465 require MIME::Types; 466 my $type = MIME::Types->new->type($ct); 467 my $ext = $type && (($type->extensions)[0]); 468 $ext ||= "dat"; 469 return "attachment-$$-" . $gname++ . ".$ext"; 470} 471 472sub default_header_class { 'Email::MIME::Header' } 473 474sub header_str { 475 my $self = shift; 476 $self->header_obj->header_str(@_); 477} 478 479sub header_str_set { 480 my $self = shift; 481 $self->header_obj->header_str_set(@_); 482} 483 484sub header_str_pairs { 485 my $self = shift; 486 $self->header_obj->header_str_pairs(@_); 487} 488 489sub header_as_obj { 490 my $self = shift; 491 $self->header_obj->header_as_obj(@_); 492} 493 494#pod =method content_type_set 495#pod 496#pod $email->content_type_set( 'text/html' ); 497#pod 498#pod Change the content type. All C<Content-Type> header attributes 499#pod will remain intact. 500#pod 501#pod =cut 502 503sub content_type_set { 504 my ($self, $ct) = @_; 505 my $ct_header = parse_content_type($self->header('Content-Type')); 506 @{$ct_header}{qw[type subtype]} = split m[/], $ct; 507 $self->_compose_content_type($ct_header); 508 $self->_reset_cids; 509 return $ct; 510} 511 512#pod =method charset_set 513#pod 514#pod =method name_set 515#pod 516#pod =method format_set 517#pod 518#pod =method boundary_set 519#pod 520#pod $email->charset_set( 'UTF-8' ); 521#pod $email->name_set( 'some_filename.txt' ); 522#pod $email->format_set( 'flowed' ); 523#pod $email->boundary_set( undef ); # remove the boundary 524#pod 525#pod These four methods modify common C<Content-Type> attributes. If set to 526#pod C<undef>, the attribute is removed. All other C<Content-Type> header 527#pod information is preserved when modifying an attribute. 528#pod 529#pod =cut 530 531BEGIN { 532 foreach my $attr (qw[charset name format]) { 533 my $code = sub { 534 my ($self, $value) = @_; 535 my $ct_header = parse_content_type($self->header('Content-Type')); 536 if ($value) { 537 $ct_header->{attributes}->{$attr} = $value; 538 } else { 539 delete $ct_header->{attributes}->{$attr}; 540 } 541 $self->_compose_content_type($ct_header); 542 return $value; 543 }; 544 545 no strict 'refs'; ## no critic strict 546 *{"$attr\_set"} = $code; 547 } 548} 549 550sub boundary_set { 551 my ($self, $value) = @_; 552 my $ct_header = parse_content_type($self->header('Content-Type')); 553 554 if (defined $value and length $value) { 555 $ct_header->{attributes}->{boundary} = $value; 556 } else { 557 delete $ct_header->{attributes}->{boundary}; 558 } 559 $self->_compose_content_type($ct_header); 560 561 $self->parts_set([ $self->parts ]) if $self->parts > 1; 562} 563 564sub content_type_attribute_set { 565 my ($self, $key, $value) = @_; 566 $key = lc $key; 567 568 if ($CT_SETTER{$key}) { 569 my $method = "$key\_set"; 570 return $self->$method($value); 571 } 572 573 my $ct_header = parse_content_type($self->header('Content-Type')); 574 my $attrs = $ct_header->{attributes}; 575 576 for my $existing_key (keys %$attrs) { 577 delete $attrs->{$existing_key} if lc $existing_key eq $key; 578 } 579 580 if ($value) { 581 $ct_header->{attributes}->{$key} = $value; 582 } else { 583 delete $ct_header->{attributes}->{$key}; 584 } 585 $self->_compose_content_type($ct_header); 586} 587 588#pod =method encode_check 589#pod 590#pod =method encode_check_set 591#pod 592#pod $email->encode_check; 593#pod $email->encode_check_set(0); 594#pod $email->encode_check_set(Encode::FB_DEFAULT); 595#pod 596#pod Gets/sets the current C<encode_check> setting (default: I<FB_CROAK>). 597#pod This is the parameter passed to L<Encode/"decode"> and L<Encode/"encode"> 598#pod when C<body_str()>, C<body_str_set()>, and C<create()> are called. 599#pod 600#pod With the default setting, Email::MIME may crash if the claimed charset 601#pod of a body does not match its contents (for example - utf8 data in a 602#pod text/plain; charset=us-ascii message). 603#pod 604#pod With an C<encode_check> of 0, the unrecognized bytes will instead be 605#pod replaced with the C<REPLACEMENT CHARACTER> (U+0FFFD), and may end up 606#pod as either that or question marks (?). 607#pod 608#pod See L<Encode/"Handling Malformed Data"> for more information. 609#pod 610#pod =cut 611 612sub encode_check { 613 my ($self) = @_; 614 615 return $self->{encode_check}; 616} 617 618sub encode_check_set { 619 my ($self, $val) = @_; 620 621 return $self->{encode_check} = $val; 622} 623 624#pod =method encoding_set 625#pod 626#pod $email->encoding_set( 'base64' ); 627#pod $email->encoding_set( 'quoted-printable' ); 628#pod $email->encoding_set( '8bit' ); 629#pod 630#pod Convert the message body and alter the C<Content-Transfer-Encoding> 631#pod header using this method. Your message body, the output of the C<body()> 632#pod method, will remain the same. The raw body, output with the C<body_raw()> 633#pod method, will be changed to reflect the new encoding. 634#pod 635#pod =cut 636 637sub encoding_set { 638 my ($self, $enc) = @_; 639 $enc ||= '7bit'; 640 my $body = $self->body; 641 $self->header_raw_set('Content-Transfer-Encoding' => $enc); 642 $self->body_set($body); 643} 644 645#pod =method body_set 646#pod 647#pod $email->body_set( $unencoded_body_string ); 648#pod 649#pod This method will encode the new body you send using the encoding 650#pod specified in the C<Content-Transfer-Encoding> header, then set 651#pod the body to the new encoded body. 652#pod 653#pod This method overrides the default C<body_set()> method. 654#pod 655#pod =cut 656 657sub body_set { 658 my ($self, $body) = @_; 659 my $body_ref; 660 661 if (ref $body) { 662 Carp::croak("provided body reference is not a scalar reference") 663 unless reftype($body) eq 'SCALAR'; 664 $body_ref = $body; 665 } else { 666 $body_ref = \$body; 667 } 668 my $enc = $self->header('Content-Transfer-Encoding'); 669 670 # XXX: This is a disgusting hack and needs to be fixed, probably by a 671 # clearer definition and reengineering of Simple construction. The bug 672 # this fixes is an indirect result of the previous behavior in which all 673 # Simple subclasses were free to alter the guts of the Email::Simple 674 # object. -- rjbs, 2007-07-16 675 unless (((caller(1))[3] || '') eq 'Email::Simple::new') { 676 $$body_ref = Email::MIME::Encodings::encode($enc, $$body_ref) 677 unless !$enc || $enc =~ $NO_ENCODE_RE; 678 } 679 680 $self->{body_raw} = $$body_ref; 681 $self->SUPER::body_set($body_ref); 682} 683 684#pod =method body_str_set 685#pod 686#pod $email->body_str_set($unicode_str); 687#pod 688#pod This method behaves like C<body_set>, but assumes that the given value is a 689#pod Unicode string that should be encoded into the message's charset 690#pod before being set. 691#pod 692#pod The charset must already be set, either manually (via the C<attributes> 693#pod argument to C<create> or C<charset_set>) or through the C<Content-Type> of a 694#pod parsed message. If the charset can't be determined, an exception is thrown. 695#pod 696#pod =cut 697 698sub body_str_set { 699 my ($self, $body_str) = @_; 700 701 my $ct = parse_content_type($self->content_type); 702 Carp::confess("body_str was given, but no charset is defined") 703 unless my $charset = $ct->{attributes}{charset}; 704 705 my $body_octets = Encode::encode($charset, $body_str, $self->encode_check); 706 $self->body_set($body_octets); 707} 708 709#pod =method disposition_set 710#pod 711#pod $email->disposition_set( 'attachment' ); 712#pod 713#pod Alter the C<Content-Disposition> of a message. All header attributes 714#pod will remain intact. 715#pod 716#pod =cut 717 718sub disposition_set { 719 my ($self, $dis) = @_; 720 $dis ||= 'inline'; 721 my $dis_header = $self->header('Content-Disposition'); 722 $dis_header 723 ? ($dis_header =~ s/^([^;]+)/$dis/) 724 : ($dis_header = $dis); 725 $self->header_raw_set('Content-Disposition' => $dis_header); 726} 727 728#pod =method filename_set 729#pod 730#pod $email->filename_set( 'boo.pdf' ); 731#pod 732#pod Sets the filename attribute in the C<Content-Disposition> header. All other 733#pod header information is preserved when setting this attribute. 734#pod 735#pod =cut 736 737sub filename_set { 738 my ($self, $filename) = @_; 739 my $dis_header = $self->header('Content-Disposition'); 740 my ($disposition, $attrs) = ('inline', {}); 741 if ($dis_header) { 742 my $struct = parse_content_disposition($dis_header); 743 $disposition = $struct->{type}; 744 $attrs = $struct->{attributes}; 745 } 746 $filename ? $attrs->{filename} = $filename : delete $attrs->{filename}; 747 my $dis = build_content_disposition({type => $disposition, attributes => $attrs}); 748 $self->header_raw_set('Content-Disposition' => $dis); 749} 750 751#pod =method parts_set 752#pod 753#pod $email->parts_set( \@new_parts ); 754#pod 755#pod Replaces the parts for an object. Accepts a reference to a list of 756#pod C<Email::MIME> objects, representing the new parts. If this message was 757#pod originally a single part, the C<Content-Type> header will be changed to 758#pod C<multipart/mixed>, and given a new boundary attribute. 759#pod 760#pod =cut 761 762sub parts_set { 763 my ($self, $parts) = @_; 764 my $body = q{}; 765 766 my $ct_header = parse_content_type($self->header('Content-Type')); 767 768 if (@{$parts} > 1 or $ct_header->{type} eq 'multipart') { 769 770 # setup multipart 771 $ct_header->{attributes}->{boundary} = Email::MessageID->new->user 772 unless defined $ct_header->{attributes}->{boundary} and length $ct_header->{attributes}->{boundary}; 773 my $bound = $ct_header->{attributes}->{boundary}; 774 foreach my $part (@{$parts}) { 775 $body .= "$self->{mycrlf}--$bound$self->{mycrlf}"; 776 $body .= $part->as_string; 777 } 778 $body .= "$self->{mycrlf}--$bound--$self->{mycrlf}"; 779 780 unless (grep { $ct_header->{type} eq $_ } qw[multipart message]) { 781 if (scalar $self->header('Content-Type')) { 782 Carp::carp("replacing non-multipart type ($ct_header->{type}/$ct_header->{subtype}) with multipart/mixed"); 783 } 784 @{$ct_header}{qw[type subtype]} = qw[multipart mixed]; 785 } 786 787 $self->encoding_set('7bit'); 788 delete $ct_header->{attributes}{charset}; 789 } elsif (@$parts == 1) { # setup singlepart 790 $body .= $parts->[0]->body; 791 792 my $from_ct = parse_content_type($parts->[0]->header('Content-Type')); 793 @{$ct_header}{qw[type subtype]} = @{ $from_ct }{qw[type subtype]}; 794 795 if (exists $from_ct->{attributes}{charset}) { 796 $ct_header->{attributes}{charset} = $from_ct->{attributes}{charset}; 797 } else { 798 delete $ct_header->{attributes}{charset}; 799 } 800 801 $self->encoding_set($parts->[0]->header('Content-Transfer-Encoding')); 802 delete $ct_header->{attributes}->{boundary}; 803 } 804 805 $self->_compose_content_type($ct_header); 806 $self->body_set($body); 807 $self->fill_parts; 808 $self->_reset_cids; 809} 810 811#pod =method parts_add 812#pod 813#pod $email->parts_add( \@more_parts ); 814#pod 815#pod Adds MIME parts onto the current MIME part. This is a simple extension 816#pod of C<parts_set> to make our lives easier. It accepts an array reference 817#pod of additional parts. 818#pod 819#pod =cut 820 821sub parts_add { 822 my ($self, $parts) = @_; 823 $self->parts_set([ $self->parts, @{$parts}, ]); 824} 825 826#pod =method walk_parts 827#pod 828#pod $email->walk_parts(sub { 829#pod my ($part) = @_; 830#pod return if $part->subparts; # multipart 831#pod 832#pod if ( $part->content_type =~ m[text/html]i ) { 833#pod my $body = $part->body; 834#pod $body =~ s/<link [^>]+>//; # simple filter example 835#pod $part->body_set( $body ); 836#pod } 837#pod }); 838#pod 839#pod Walks through all the MIME parts in a message and applies a callback to 840#pod each. Accepts a code reference as its only argument. The code reference 841#pod will be passed a single argument, the current MIME part within the 842#pod top-level MIME object. All changes will be applied in place. 843#pod 844#pod =cut 845 846sub walk_parts { 847 my ($self, $callback) = @_; 848 849 my %changed; 850 851 my $walk_weak; 852 my $walk = sub { 853 my ($part) = @_; 854 $callback->($part); 855 856 if (my @orig_subparts = $part->subparts) { 857 my $differ; 858 my @subparts; 859 860 for my $part (@orig_subparts) { 861 my $str = $part->as_string; 862 next unless my $new = $walk_weak->($part); 863 $differ = 1 if $str ne $new->as_string; 864 push @subparts, $new; 865 } 866 867 $differ 868 ||= (@subparts != @orig_subparts) 869 || (grep { $subparts[$_] != $orig_subparts[$_] } (0 .. $#subparts)) 870 || (grep { $changed{ 0+$subparts[$_] } } (0 .. $#subparts)); 871 872 if ($differ) { 873 $part->parts_set(\@subparts); 874 $changed{ 0+$part }++; 875 } 876 } 877 878 return $part; 879 }; 880 881 $walk_weak = $walk; 882 weaken $walk_weak; 883 884 my $rv = $walk->($self); 885 886 undef $walk; 887 888 return $rv; 889} 890 891sub _compose_content_type { 892 my ($self, $ct_header) = @_; 893 my $ct = build_content_type({type => $ct_header->{type}, subtype => $ct_header->{subtype}, attributes => $ct_header->{attributes}}); 894 $self->header_raw_set('Content-Type' => $ct); 895 $self->{ct} = $ct_header; 896} 897 898sub _get_cid { 899 Email::MessageID->new->address; 900} 901 902sub _reset_cids { 903 my ($self) = @_; 904 905 my $ct_header = parse_content_type($self->header('Content-Type')); 906 907 if ($self->parts > 1) { 908 if ($ct_header->{subtype} eq 'alternative') { 909 my %cids; 910 for my $part ($self->parts) { 911 my $cid 912 = defined $part->header('Content-ID') 913 ? $part->header('Content-ID') 914 : q{}; 915 $cids{$cid}++; 916 } 917 return if keys(%cids) == 1; 918 919 my $cid = $self->_get_cid; 920 $_->header_raw_set('Content-ID' => "<$cid>") for $self->parts; 921 } else { 922 foreach ($self->parts) { 923 my $cid = $self->_get_cid; 924 $_->header_raw_set('Content-ID' => "<$cid>") 925 unless $_->header('Content-ID'); 926 } 927 } 928 } 929} 930 9311; 932 933=pod 934 935=encoding UTF-8 936 937=head1 NAME 938 939Email::MIME - easy MIME message handling 940 941=head1 VERSION 942 943version 1.952 944 945=head1 SYNOPSIS 946 947B<Wait!> Before you read this, maybe you just need L<Email::Stuffer>, which is 948a much easier-to-use tool for building simple email messages that might have 949attachments or both plain text and HTML. If that doesn't do it for you, then 950by all means keep reading. 951 952 use Email::MIME; 953 my $parsed = Email::MIME->new($message); 954 955 my @parts = $parsed->parts; # These will be Email::MIME objects, too. 956 my $decoded = $parsed->body; 957 my $non_decoded = $parsed->body_raw; 958 959 my $content_type = $parsed->content_type; 960 961...or... 962 963 use Email::MIME; 964 use IO::All; 965 966 # multipart message 967 my @parts = ( 968 Email::MIME->create( 969 attributes => { 970 filename => "report.pdf", 971 content_type => "application/pdf", 972 encoding => "quoted-printable", 973 name => "2004-financials.pdf", 974 }, 975 body => io( "2004-financials.pdf" )->binary->all, 976 ), 977 Email::MIME->create( 978 attributes => { 979 content_type => "text/plain", 980 disposition => "attachment", 981 charset => "US-ASCII", 982 }, 983 body_str => "Hello there!", 984 ), 985 ); 986 987 my $email = Email::MIME->create( 988 header_str => [ 989 From => 'casey@geeknest.com', 990 To => [ 'user1@host.com', 'Name <user2@host.com>' ], 991 Cc => Email::Address::XS->new("Display Name \N{U+1F600}", 'user@example.com'), 992 ], 993 parts => [ @parts ], 994 ); 995 996 # nesting parts 997 $email->parts_set( 998 [ 999 $email->parts, 1000 Email::MIME->create( parts => [ @parts ] ), 1001 ], 1002 ); 1003 1004 # standard modifications 1005 $email->header_str_set( 'X-PoweredBy' => 'RT v3.0' ); 1006 $email->header_str_set( To => rcpts() ); 1007 $email->header_str_set( Cc => aux_rcpts() ); 1008 $email->header_str_set( Bcc => sekrit_rcpts() ); 1009 1010 # more advanced 1011 $_->encoding_set( 'base64' ) for $email->parts; 1012 1013 # Quick multipart creation 1014 my $email = Email::MIME->create( 1015 header_str => [ 1016 From => 'my@address', 1017 To => 'your@address', 1018 ], 1019 parts => [ 1020 q[This is part one], 1021 q[This is part two], 1022 q[These could be binary too], 1023 ], 1024 ); 1025 1026 print $email->as_string; 1027 1028=head1 DESCRIPTION 1029 1030This is an extension of the L<Email::Simple> module, to handle MIME 1031encoded messages. It takes a message as a string, splits it up into its 1032constituent parts, and allows you access to various parts of the 1033message. Headers are decoded from MIME encoding. 1034 1035=head1 PERL VERSION 1036 1037This library should run on perls released even a long time ago. It should work 1038on any version of perl released in the last five years. 1039 1040Although it may work on older versions of perl, no guarantee is made that the 1041minimum required version will not be increased. The version may be increased 1042for any reason, and there is no promise that patches will be accepted to lower 1043the minimum required perl. 1044 1045=head1 METHODS 1046 1047Please see L<Email::Simple> for the base set of methods. It won't take 1048very long. Added to that, you have: 1049 1050=head2 create 1051 1052 my $single = Email::MIME->create( 1053 header_str => [ ... ], 1054 body_str => '...', 1055 attributes => { ... }, 1056 ); 1057 1058 my $multi = Email::MIME->create( 1059 header_str => [ ... ], 1060 parts => [ ... ], 1061 attributes => { ... }, 1062 ); 1063 1064This method creates a new MIME part. The C<header_str> parameter is a list of 1065headers pairs to include in the message. The value for each pair is expected to 1066be a text string that will be MIME-encoded as needed. Alternatively it can be 1067an object with C<as_mime_string> method which implements conversion of that 1068object to MIME-encoded string. That object method is called with two named 1069input parameters: C<charset> and C<header_name_length>. It should return 1070MIME-encoded representation of the object. As of 2017-07-25, the 1071header-value-as-object code is very young, and may yet change. 1072 1073In case header name is registered in C<%Email::MIME::Header::header_to_class_map> 1074hash then registered class is used for conversion from Unicode string to 8bit 1075MIME encoding. Value can be either string or array reference to strings. 1076Object is constructed via method C<from_string> with string value (or values 1077in case of array reference) and converted to MIME-encoded string via 1078C<as_mime_string> method. 1079 1080A similar C<header> parameter can be provided in addition to or instead of 1081C<header_str>. Its values will be used verbatim. 1082 1083C<attributes> is a hash of MIME attributes to assign to the part, and may 1084override portions of the header set in the C<header> parameter. The hash keys 1085correspond directly to methods for modifying a message from 1086C<Email::MIME::Modifier>. The allowed keys are: content_type, charset, name, 1087format, boundary, encoding, disposition, and filename. They will be mapped to 1088C<"$attr\_set"> for message modification. 1089 1090The C<parts> parameter is a list reference containing C<Email::MIME> 1091objects. Elements of the C<parts> list can also be a non-reference 1092string of data. In that case, an C<Email::MIME> object will be created 1093for you. Simple checks will determine if the part is binary or not, and 1094all parts created in this fashion are encoded with C<base64>, just in case. 1095 1096If C<body> is given instead of C<parts>, it specifies the body to be used for a 1097flat (subpart-less) MIME message. It is assumed to be a sequence of octets. 1098 1099If C<body_str> is given instead of C<body> or C<parts>, it is assumed to be a 1100character string to be used as the body. If you provide a C<body_str> 1101parameter, you B<must> provide C<charset> and C<encoding> attributes. 1102 1103=head2 content_type_set 1104 1105 $email->content_type_set( 'text/html' ); 1106 1107Change the content type. All C<Content-Type> header attributes 1108will remain intact. 1109 1110=head2 charset_set 1111 1112=head2 name_set 1113 1114=head2 format_set 1115 1116=head2 boundary_set 1117 1118 $email->charset_set( 'UTF-8' ); 1119 $email->name_set( 'some_filename.txt' ); 1120 $email->format_set( 'flowed' ); 1121 $email->boundary_set( undef ); # remove the boundary 1122 1123These four methods modify common C<Content-Type> attributes. If set to 1124C<undef>, the attribute is removed. All other C<Content-Type> header 1125information is preserved when modifying an attribute. 1126 1127=head2 encode_check 1128 1129=head2 encode_check_set 1130 1131 $email->encode_check; 1132 $email->encode_check_set(0); 1133 $email->encode_check_set(Encode::FB_DEFAULT); 1134 1135Gets/sets the current C<encode_check> setting (default: I<FB_CROAK>). 1136This is the parameter passed to L<Encode/"decode"> and L<Encode/"encode"> 1137when C<body_str()>, C<body_str_set()>, and C<create()> are called. 1138 1139With the default setting, Email::MIME may crash if the claimed charset 1140of a body does not match its contents (for example - utf8 data in a 1141text/plain; charset=us-ascii message). 1142 1143With an C<encode_check> of 0, the unrecognized bytes will instead be 1144replaced with the C<REPLACEMENT CHARACTER> (U+0FFFD), and may end up 1145as either that or question marks (?). 1146 1147See L<Encode/"Handling Malformed Data"> for more information. 1148 1149=head2 encoding_set 1150 1151 $email->encoding_set( 'base64' ); 1152 $email->encoding_set( 'quoted-printable' ); 1153 $email->encoding_set( '8bit' ); 1154 1155Convert the message body and alter the C<Content-Transfer-Encoding> 1156header using this method. Your message body, the output of the C<body()> 1157method, will remain the same. The raw body, output with the C<body_raw()> 1158method, will be changed to reflect the new encoding. 1159 1160=head2 body_set 1161 1162 $email->body_set( $unencoded_body_string ); 1163 1164This method will encode the new body you send using the encoding 1165specified in the C<Content-Transfer-Encoding> header, then set 1166the body to the new encoded body. 1167 1168This method overrides the default C<body_set()> method. 1169 1170=head2 body_str_set 1171 1172 $email->body_str_set($unicode_str); 1173 1174This method behaves like C<body_set>, but assumes that the given value is a 1175Unicode string that should be encoded into the message's charset 1176before being set. 1177 1178The charset must already be set, either manually (via the C<attributes> 1179argument to C<create> or C<charset_set>) or through the C<Content-Type> of a 1180parsed message. If the charset can't be determined, an exception is thrown. 1181 1182=head2 disposition_set 1183 1184 $email->disposition_set( 'attachment' ); 1185 1186Alter the C<Content-Disposition> of a message. All header attributes 1187will remain intact. 1188 1189=head2 filename_set 1190 1191 $email->filename_set( 'boo.pdf' ); 1192 1193Sets the filename attribute in the C<Content-Disposition> header. All other 1194header information is preserved when setting this attribute. 1195 1196=head2 parts_set 1197 1198 $email->parts_set( \@new_parts ); 1199 1200Replaces the parts for an object. Accepts a reference to a list of 1201C<Email::MIME> objects, representing the new parts. If this message was 1202originally a single part, the C<Content-Type> header will be changed to 1203C<multipart/mixed>, and given a new boundary attribute. 1204 1205=head2 parts_add 1206 1207 $email->parts_add( \@more_parts ); 1208 1209Adds MIME parts onto the current MIME part. This is a simple extension 1210of C<parts_set> to make our lives easier. It accepts an array reference 1211of additional parts. 1212 1213=head2 walk_parts 1214 1215 $email->walk_parts(sub { 1216 my ($part) = @_; 1217 return if $part->subparts; # multipart 1218 1219 if ( $part->content_type =~ m[text/html]i ) { 1220 my $body = $part->body; 1221 $body =~ s/<link [^>]+>//; # simple filter example 1222 $part->body_set( $body ); 1223 } 1224 }); 1225 1226Walks through all the MIME parts in a message and applies a callback to 1227each. Accepts a code reference as its only argument. The code reference 1228will be passed a single argument, the current MIME part within the 1229top-level MIME object. All changes will be applied in place. 1230 1231=head2 header 1232 1233B<Achtung!> Beware this method! In Email::MIME, it means the same as 1234C<header_str>, but on an Email::Simple object, it means C<header_raw>. Unless 1235you always know what kind of object you have, you could get one of two 1236significantly different behaviors. 1237 1238Try to use either C<header_str> or C<header_raw> as appropriate. 1239 1240=head2 header_str_set 1241 1242 $email->header_str_set($header_name => @value_strings); 1243 1244This behaves like C<header_raw_set>, but expects Unicode (character) strings as 1245the values to set, rather than pre-encoded byte strings. It will encode them 1246as MIME encoded-words if they contain any control or 8-bit characters. 1247 1248Alternatively, values can be objects with C<as_mime_string> method. Same as in 1249method C<create>. 1250 1251=head2 header_str_pairs 1252 1253 my @pairs = $email->header_str_pairs; 1254 1255This method behaves like C<header_raw_pairs>, returning a list of field 1256name/value pairs, but the values have been decoded to character strings, when 1257possible. 1258 1259=head2 header_as_obj 1260 1261 my $first_obj = $email->header_as_obj($field); 1262 my $nth_obj = $email->header_as_obj($field, $index); 1263 my @all_objs = $email->header_as_obj($field); 1264 1265 my $nth_obj_of_class = $email->header_as_obj($field, $index, $class); 1266 my @all_objs_of_class = $email->header_as_obj($field, undef, $class); 1267 1268This method returns an object representation of the header value. It instances 1269new object via method C<from_mime_string> of specified class. Input argument 1270for that class method is list of the raw MIME-encoded values. If class argument 1271is not specified then class name is taken from the hash 1272C<%Email::MIME::Header::header_to_class_map> via key field. Use class method 1273C<< Email::MIME::Header->set_class_for_header($class, $field) >> for adding new 1274mapping. 1275 1276=head2 parts 1277 1278This returns a list of C<Email::MIME> objects reflecting the parts of the 1279message. If it's a single-part message, you get the original object back. 1280 1281In scalar context, this method returns the number of parts. 1282 1283This is a stupid method. Don't use it. 1284 1285=head2 subparts 1286 1287This returns a list of C<Email::MIME> objects reflecting the parts of the 1288message. If it's a single-part message, this method returns an empty list. 1289 1290In scalar context, this method returns the number of subparts. 1291 1292=head2 body 1293 1294This decodes and returns the body of the object I<as a byte string>. For 1295top-level objects in multi-part messages, this is highly likely to be something 1296like "This is a multi-part message in MIME format." 1297 1298=head2 body_str 1299 1300This decodes both the Content-Transfer-Encoding layer of the body (like the 1301C<body> method) as well as the charset encoding of the body (unlike the C<body> 1302method), returning a Unicode string. 1303 1304If the charset is known, it is used. If there is no charset but the content 1305type is either C<text/plain> or C<text/html>, us-ascii is assumed. Otherwise, 1306an exception is thrown. 1307 1308=head2 body_raw 1309 1310This returns the body of the object, but doesn't decode the transfer encoding. 1311 1312=head2 decode_hook 1313 1314This method is called before the L<Email::MIME::Encodings> C<decode> method, to 1315decode the body of non-binary messages (or binary messages, if the 1316C<force_decode_hook> method returns true). By default, this method does 1317nothing, but subclasses may define behavior. 1318 1319This method could be used to implement the decryption of content in secure 1320email, for example. 1321 1322=head2 content_type 1323 1324This is a shortcut for access to the content type header. 1325 1326=head2 filename 1327 1328This provides the suggested filename for the attachment part. Normally 1329it will return the filename from the headers, but if C<filename> is 1330passed a true parameter, it will generate an appropriate "stable" 1331filename if one is not found in the MIME headers. 1332 1333=head2 invent_filename 1334 1335 my $filename = Email::MIME->invent_filename($content_type); 1336 1337This routine is used by C<filename> to generate filenames for attached files. 1338It will attempt to choose a reasonable extension, falling back to F<dat>. 1339 1340=head2 debug_structure 1341 1342 my $description = $email->debug_structure; 1343 1344This method returns a string that describes the structure of the MIME entity. 1345For example: 1346 1347 + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5" 1348 + text/plain 1349 + text/html 1350 1351=head1 CONFIGURATION 1352 1353The variable C<$Email::MIME::MAX_DEPTH> is the maximum depth of parts that will 1354be processed. It defaults to 10, already higher than legitimate mail is ever 1355likely to be. This value may go up over time as the parser is improved. 1356 1357=head1 TODO 1358 1359All of the Email::MIME-specific guts should move to a single entry on the 1360object's guts. This will require changes to both Email::MIME and 1361L<Email::MIME::Modifier>, sadly. 1362 1363=head1 SEE ALSO 1364 1365L<Email::Simple>, L<Email::MIME::Modifier>, L<Email::MIME::Creator>. 1366 1367=head1 THANKS 1368 1369This module was generously sponsored by Best Practical 1370(http://www.bestpractical.com/), Pete Sergeant, and Pobox.com. 1371 1372=head1 AUTHORS 1373 1374=over 4 1375 1376=item * 1377 1378Ricardo SIGNES <rjbs@semiotic.systems> 1379 1380=item * 1381 1382Casey West <casey@geeknest.com> 1383 1384=item * 1385 1386Simon Cozens <simon@cpan.org> 1387 1388=back 1389 1390=head1 CONTRIBUTORS 1391 1392=for stopwords Alex Vandiver Anirvan Chatterjee Arthur Axel 'fREW' Schmidt Brian Cassidy Damian Lukowski Dan Book David Steinbrunner Dotan Dimet dxdc Eric Wong Geraint Edwards ivulfson Jesse Luehrs Kurt Anderson Lance A. Brown Matthew Horsfall memememomo Michael McClimon Mishrakk Pali Shawn Sorichetti Tomohiro Hosaka 1393 1394=over 4 1395 1396=item * 1397 1398Alex Vandiver <alexmv@mit.edu> 1399 1400=item * 1401 1402Anirvan Chatterjee <anirvan@users.noreply.github.com> 1403 1404=item * 1405 1406Arthur Axel 'fREW' Schmidt <frioux@gmail.com> 1407 1408=item * 1409 1410Brian Cassidy <bricas@cpan.org> 1411 1412=item * 1413 1414Damian Lukowski <damian.lukowski@credativ.de> 1415 1416=item * 1417 1418Dan Book <grinnz@gmail.com> 1419 1420=item * 1421 1422David Steinbrunner <dsteinbrunner@pobox.com> 1423 1424=item * 1425 1426Dotan Dimet <dotan@corky.net> 1427 1428=item * 1429 1430dxdc <dan@element26.net> 1431 1432=item * 1433 1434Eric Wong <e@80x24.org> 1435 1436=item * 1437 1438Geraint Edwards <gedge-oss@yadn.org> 1439 1440=item * 1441 1442ivulfson <9122139+ivulfson@users.noreply.github.com> 1443 1444=item * 1445 1446Jesse Luehrs <doy@tozt.net> 1447 1448=item * 1449 1450Kurt Anderson <kboth@drkurt.com> 1451 1452=item * 1453 1454Lance A. Brown <lance@bearcircle.net> 1455 1456=item * 1457 1458Matthew Horsfall <wolfsage@gmail.com> 1459 1460=item * 1461 1462memememomo <memememomo@gmail.com> 1463 1464=item * 1465 1466Michael McClimon <michael@mcclimon.org> 1467 1468=item * 1469 1470Mishrakk <48946018+Mishrakk@users.noreply.github.com> 1471 1472=item * 1473 1474Pali <pali@cpan.org> 1475 1476=item * 1477 1478Shawn Sorichetti <ssoriche@coloredblocks.com> 1479 1480=item * 1481 1482Tomohiro Hosaka <bokutin@bokut.in> 1483 1484=back 1485 1486=head1 COPYRIGHT AND LICENSE 1487 1488This software is copyright (c) 2004 by Simon Cozens and Casey West. 1489 1490This is free software; you can redistribute it and/or modify it under 1491the same terms as the Perl 5 programming language system itself. 1492 1493=cut 1494 1495__END__ 1496 1497#pod =method header 1498#pod 1499#pod B<Achtung!> Beware this method! In Email::MIME, it means the same as 1500#pod C<header_str>, but on an Email::Simple object, it means C<header_raw>. Unless 1501#pod you always know what kind of object you have, you could get one of two 1502#pod significantly different behaviors. 1503#pod 1504#pod Try to use either C<header_str> or C<header_raw> as appropriate. 1505#pod 1506#pod =method header_str_set 1507#pod 1508#pod $email->header_str_set($header_name => @value_strings); 1509#pod 1510#pod This behaves like C<header_raw_set>, but expects Unicode (character) strings as 1511#pod the values to set, rather than pre-encoded byte strings. It will encode them 1512#pod as MIME encoded-words if they contain any control or 8-bit characters. 1513#pod 1514#pod Alternatively, values can be objects with C<as_mime_string> method. Same as in 1515#pod method C<create>. 1516#pod 1517#pod =method header_str_pairs 1518#pod 1519#pod my @pairs = $email->header_str_pairs; 1520#pod 1521#pod This method behaves like C<header_raw_pairs>, returning a list of field 1522#pod name/value pairs, but the values have been decoded to character strings, when 1523#pod possible. 1524#pod 1525#pod =method header_as_obj 1526#pod 1527#pod my $first_obj = $email->header_as_obj($field); 1528#pod my $nth_obj = $email->header_as_obj($field, $index); 1529#pod my @all_objs = $email->header_as_obj($field); 1530#pod 1531#pod my $nth_obj_of_class = $email->header_as_obj($field, $index, $class); 1532#pod my @all_objs_of_class = $email->header_as_obj($field, undef, $class); 1533#pod 1534#pod This method returns an object representation of the header value. It instances 1535#pod new object via method C<from_mime_string> of specified class. Input argument 1536#pod for that class method is list of the raw MIME-encoded values. If class argument 1537#pod is not specified then class name is taken from the hash 1538#pod C<%Email::MIME::Header::header_to_class_map> via key field. Use class method 1539#pod C<< Email::MIME::Header->set_class_for_header($class, $field) >> for adding new 1540#pod mapping. 1541#pod 1542#pod =method parts 1543#pod 1544#pod This returns a list of C<Email::MIME> objects reflecting the parts of the 1545#pod message. If it's a single-part message, you get the original object back. 1546#pod 1547#pod In scalar context, this method returns the number of parts. 1548#pod 1549#pod This is a stupid method. Don't use it. 1550#pod 1551#pod =method subparts 1552#pod 1553#pod This returns a list of C<Email::MIME> objects reflecting the parts of the 1554#pod message. If it's a single-part message, this method returns an empty list. 1555#pod 1556#pod In scalar context, this method returns the number of subparts. 1557#pod 1558#pod =method body 1559#pod 1560#pod This decodes and returns the body of the object I<as a byte string>. For 1561#pod top-level objects in multi-part messages, this is highly likely to be something 1562#pod like "This is a multi-part message in MIME format." 1563#pod 1564#pod =method body_str 1565#pod 1566#pod This decodes both the Content-Transfer-Encoding layer of the body (like the 1567#pod C<body> method) as well as the charset encoding of the body (unlike the C<body> 1568#pod method), returning a Unicode string. 1569#pod 1570#pod If the charset is known, it is used. If there is no charset but the content 1571#pod type is either C<text/plain> or C<text/html>, us-ascii is assumed. Otherwise, 1572#pod an exception is thrown. 1573#pod 1574#pod =method body_raw 1575#pod 1576#pod This returns the body of the object, but doesn't decode the transfer encoding. 1577#pod 1578#pod =method decode_hook 1579#pod 1580#pod This method is called before the L<Email::MIME::Encodings> C<decode> method, to 1581#pod decode the body of non-binary messages (or binary messages, if the 1582#pod C<force_decode_hook> method returns true). By default, this method does 1583#pod nothing, but subclasses may define behavior. 1584#pod 1585#pod This method could be used to implement the decryption of content in secure 1586#pod email, for example. 1587#pod 1588#pod =method content_type 1589#pod 1590#pod This is a shortcut for access to the content type header. 1591#pod 1592#pod =method filename 1593#pod 1594#pod This provides the suggested filename for the attachment part. Normally 1595#pod it will return the filename from the headers, but if C<filename> is 1596#pod passed a true parameter, it will generate an appropriate "stable" 1597#pod filename if one is not found in the MIME headers. 1598#pod 1599#pod =method invent_filename 1600#pod 1601#pod my $filename = Email::MIME->invent_filename($content_type); 1602#pod 1603#pod This routine is used by C<filename> to generate filenames for attached files. 1604#pod It will attempt to choose a reasonable extension, falling back to F<dat>. 1605#pod 1606#pod =method debug_structure 1607#pod 1608#pod my $description = $email->debug_structure; 1609#pod 1610#pod This method returns a string that describes the structure of the MIME entity. 1611#pod For example: 1612#pod 1613#pod + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5" 1614#pod + text/plain 1615#pod + text/html 1616#pod 1617#pod =head1 CONFIGURATION 1618#pod 1619#pod The variable C<$Email::MIME::MAX_DEPTH> is the maximum depth of parts that will 1620#pod be processed. It defaults to 10, already higher than legitimate mail is ever 1621#pod likely to be. This value may go up over time as the parser is improved. 1622#pod 1623#pod =head1 TODO 1624#pod 1625#pod All of the Email::MIME-specific guts should move to a single entry on the 1626#pod object's guts. This will require changes to both Email::MIME and 1627#pod L<Email::MIME::Modifier>, sadly. 1628#pod 1629#pod =head1 SEE ALSO 1630#pod 1631#pod L<Email::Simple>, L<Email::MIME::Modifier>, L<Email::MIME::Creator>. 1632#pod 1633#pod =head1 THANKS 1634#pod 1635#pod This module was generously sponsored by Best Practical 1636#pod (http://www.bestpractical.com/), Pete Sergeant, and Pobox.com. 1637#pod 1638#pod =cut 1639