1Email::MIME(3)        User Contributed Perl Documentation       Email::MIME(3)
2
3
4

NAME

6       Email::MIME - easy MIME message handling
7

VERSION

9       version 1.949
10

SYNOPSIS

12       Wait!  Before you read this, maybe you just need Email::Stuffer, which
13       is a much easier-to-use tool for building simple email messages that
14       might have attachments or both plain text and HTML.  If that doesn't do
15       it for you, then by all means keep reading.
16
17         use Email::MIME;
18         my $parsed = Email::MIME->new($message);
19
20         my @parts = $parsed->parts; # These will be Email::MIME objects, too.
21         my $decoded = $parsed->body;
22         my $non_decoded = $parsed->body_raw;
23
24         my $content_type = $parsed->content_type;
25
26       ...or...
27
28         use Email::MIME;
29         use IO::All;
30
31         # multipart message
32         my @parts = (
33             Email::MIME->create(
34                 attributes => {
35                     filename     => "report.pdf",
36                     content_type => "application/pdf",
37                     encoding     => "quoted-printable",
38                     name         => "2004-financials.pdf",
39                 },
40                 body => io( "2004-financials.pdf" )->binary->all,
41             ),
42             Email::MIME->create(
43                 attributes => {
44                     content_type => "text/plain",
45                     disposition  => "attachment",
46                     charset      => "US-ASCII",
47                 },
48                 body_str => "Hello there!",
49             ),
50         );
51
52         my $email = Email::MIME->create(
53             header_str => [
54                 From => 'casey@geeknest.com',
55                 To => [ 'user1@host.com', 'Name <user2@host.com>' ],
56                 Cc => Email::Address::XS->new("Display Name \N{U+1F600}", 'user@example.com'),
57             ],
58             parts      => [ @parts ],
59         );
60
61         # nesting parts
62         $email->parts_set(
63             [
64               $email->parts,
65               Email::MIME->create( parts => [ @parts ] ),
66             ],
67         );
68
69         # standard modifications
70         $email->header_str_set( 'X-PoweredBy' => 'RT v3.0'      );
71         $email->header_str_set( To            => rcpts()        );
72         $email->header_str_set( Cc            => aux_rcpts()    );
73         $email->header_str_set( Bcc           => sekrit_rcpts() );
74
75         # more advanced
76         $_->encoding_set( 'base64' ) for $email->parts;
77
78         # Quick multipart creation
79         my $email = Email::MIME->create(
80             header_str => [
81                 From => 'my@address',
82                 To   => 'your@address',
83             ],
84             parts => [
85                 q[This is part one],
86                 q[This is part two],
87                 q[These could be binary too],
88             ],
89         );
90
91         print $email->as_string;
92

DESCRIPTION

94       This is an extension of the Email::Simple module, to handle MIME
95       encoded messages. It takes a message as a string, splits it up into its
96       constituent parts, and allows you access to various parts of the
97       message. Headers are decoded from MIME encoding.
98

METHODS

100       Please see Email::Simple for the base set of methods. It won't take
101       very long. Added to that, you have:
102
103   create
104         my $single = Email::MIME->create(
105           header_str => [ ... ],
106           body_str   => '...',
107           attributes => { ... },
108         );
109
110         my $multi = Email::MIME->create(
111           header_str => [ ... ],
112           parts      => [ ... ],
113           attributes => { ... },
114         );
115
116       This method creates a new MIME part. The "header_str" parameter is a
117       list of headers pairs to include in the message. The value for each
118       pair is expected to be a text string that will be MIME-encoded as
119       needed.  Alternatively it can be an object with "as_mime_string" method
120       which implements conversion of that object to MIME-encoded string.
121       That object method is called with two named input parameters: "charset"
122       and "header_name_length".  It should return MIME-encoded representation
123       of the object.  As of 2017-07-25, the header-value-as-object code is
124       very young, and may yet change.
125
126       In case header name is registered in
127       %Email::MIME::Header::header_to_class_map hash then registered class is
128       used for conversion from Unicode string to 8bit MIME encoding.  Value
129       can be either string or array reference to strings.  Object is
130       constructed via method "from_string" with string value (or values in
131       case of array reference) and converted to MIME-encoded string via
132       "as_mime_string" method.
133
134       A similar "header" parameter can be provided in addition to or instead
135       of "header_str".  Its values will be used verbatim.
136
137       "attributes" is a hash of MIME attributes to assign to the part, and
138       may override portions of the header set in the "header" parameter. The
139       hash keys correspond directly to methods for modifying a message from
140       "Email::MIME::Modifier". The allowed keys are: content_type, charset,
141       name, format, boundary, encoding, disposition, and filename. They will
142       be mapped to "$attr\_set" for message modification.
143
144       The "parts" parameter is a list reference containing "Email::MIME"
145       objects. Elements of the "parts" list can also be a non-reference
146       string of data. In that case, an "Email::MIME" object will be created
147       for you. Simple checks will determine if the part is binary or not, and
148       all parts created in this fashion are encoded with "base64", just in
149       case.
150
151       If "body" is given instead of "parts", it specifies the body to be used
152       for a flat (subpart-less) MIME message.  It is assumed to be a sequence
153       of octets.
154
155       If "body_str" is given instead of "body" or "parts", it is assumed to
156       be a character string to be used as the body.  If you provide a
157       "body_str" parameter, you must provide "charset" and "encoding"
158       attributes.
159
160   content_type_set
161         $email->content_type_set( 'text/html' );
162
163       Change the content type. All "Content-Type" header attributes will
164       remain intact.
165
166   charset_set
167   name_set
168   format_set
169   boundary_set
170         $email->charset_set( 'UTF-8' );
171         $email->name_set( 'some_filename.txt' );
172         $email->format_set( 'flowed' );
173         $email->boundary_set( undef ); # remove the boundary
174
175       These four methods modify common "Content-Type" attributes. If set to
176       "undef", the attribute is removed. All other "Content-Type" header
177       information is preserved when modifying an attribute.
178
179   encode_check
180   encode_check_set
181         $email->encode_check;
182         $email->encode_check_set(0);
183         $email->encode_check_set(Encode::FB_DEFAULT);
184
185       Gets/sets the current "encode_check" setting (default: FB_CROAK).  This
186       is the parameter passed to "decode" in Encode and "encode" in Encode
187       when "body_str()", "body_str_set()", and "create()" are called.
188
189       With the default setting, Email::MIME may crash if the claimed charset
190       of a body does not match its contents (for example - utf8 data in a
191       text/plain; charset=us-ascii message).
192
193       With an "encode_check" of 0, the unrecognized bytes will instead be
194       replaced with the "REPLACEMENT CHARACTER" (U+0FFFD), and may end up as
195       either that or question marks (?).
196
197       See "Handling Malformed Data" in Encode for more information.
198
199   encoding_set
200         $email->encoding_set( 'base64' );
201         $email->encoding_set( 'quoted-printable' );
202         $email->encoding_set( '8bit' );
203
204       Convert the message body and alter the "Content-Transfer-Encoding"
205       header using this method. Your message body, the output of the "body()"
206       method, will remain the same. The raw body, output with the
207       "body_raw()" method, will be changed to reflect the new encoding.
208
209   body_set
210         $email->body_set( $unencoded_body_string );
211
212       This method will encode the new body you send using the encoding
213       specified in the "Content-Transfer-Encoding" header, then set the body
214       to the new encoded body.
215
216       This method overrides the default "body_set()" method.
217
218   body_str_set
219         $email->body_str_set($unicode_str);
220
221       This method behaves like "body_set", but assumes that the given value
222       is a Unicode string that should be encoded into the message's charset
223       before being set.
224
225       The charset must already be set, either manually (via the "attributes"
226       argument to "create" or "charset_set") or through the "Content-Type" of
227       a parsed message.  If the charset can't be determined, an exception is
228       thrown.
229
230   disposition_set
231         $email->disposition_set( 'attachment' );
232
233       Alter the "Content-Disposition" of a message. All header attributes
234       will remain intact.
235
236   filename_set
237         $email->filename_set( 'boo.pdf' );
238
239       Sets the filename attribute in the "Content-Disposition" header. All
240       other header information is preserved when setting this attribute.
241
242   parts_set
243         $email->parts_set( \@new_parts );
244
245       Replaces the parts for an object. Accepts a reference to a list of
246       "Email::MIME" objects, representing the new parts. If this message was
247       originally a single part, the "Content-Type" header will be changed to
248       "multipart/mixed", and given a new boundary attribute.
249
250   parts_add
251         $email->parts_add( \@more_parts );
252
253       Adds MIME parts onto the current MIME part. This is a simple extension
254       of "parts_set" to make our lives easier. It accepts an array reference
255       of additional parts.
256
257   walk_parts
258         $email->walk_parts(sub {
259             my ($part) = @_;
260             return if $part->subparts; # multipart
261
262             if ( $part->content_type =~ m[text/html]i ) {
263                 my $body = $part->body;
264                 $body =~ s/<link [^>]+>//; # simple filter example
265                 $part->body_set( $body );
266             }
267         });
268
269       Walks through all the MIME parts in a message and applies a callback to
270       each. Accepts a code reference as its only argument. The code reference
271       will be passed a single argument, the current MIME part within the top-
272       level MIME object. All changes will be applied in place.
273
274   header
275       Achtung!  Beware this method!  In Email::MIME, it means the same as
276       "header_str", but on an Email::Simple object, it means "header_raw".
277       Unless you always know what kind of object you have, you could get one
278       of two significantly different behaviors.
279
280       Try to use either "header_str" or "header_raw" as appropriate.
281
282   header_str_set
283         $email->header_str_set($header_name => @value_strings);
284
285       This behaves like "header_raw_set", but expects Unicode (character)
286       strings as the values to set, rather than pre-encoded byte strings.  It
287       will encode them as MIME encoded-words if they contain any control or
288       8-bit characters.
289
290       Alternatively, values can be objects with "as_mime_string" method.
291       Same as in method "create".
292
293   header_str_pairs
294         my @pairs = $email->header_str_pairs;
295
296       This method behaves like "header_raw_pairs", returning a list of field
297       name/value pairs, but the values have been decoded to character
298       strings, when possible.
299
300   header_as_obj
301         my $first_obj = $email->header_as_obj($field);
302         my $nth_obj   = $email->header_as_obj($field, $index);
303         my @all_objs  = $email->header_as_obj($field);
304
305         my $nth_obj_of_class  = $email->header_as_obj($field, $index, $class);
306         my @all_objs_of_class = $email->header_as_obj($field, undef, $class);
307
308       This method returns an object representation of the header value.  It
309       instances new object via method "from_mime_string" of specified class.
310       Input argument for that class method is list of the raw MIME-encoded
311       values.  If class argument is not specified then class name is taken
312       from the hash %Email::MIME::Header::header_to_class_map via key field.
313       Use class method "Email::MIME::Header->set_class_for_header($class,
314       $field)" for adding new mapping.
315
316   parts
317       This returns a list of "Email::MIME" objects reflecting the parts of
318       the message. If it's a single-part message, you get the original object
319       back.
320
321       In scalar context, this method returns the number of parts.
322
323       This is a stupid method.  Don't use it.
324
325   subparts
326       This returns a list of "Email::MIME" objects reflecting the parts of
327       the message.  If it's a single-part message, this method returns an
328       empty list.
329
330       In scalar context, this method returns the number of subparts.
331
332   body
333       This decodes and returns the body of the object as a byte string. For
334       top-level objects in multi-part messages, this is highly likely to be
335       something like "This is a multi-part message in MIME format."
336
337   body_str
338       This decodes both the Content-Transfer-Encoding layer of the body (like
339       the "body" method) as well as the charset encoding of the body (unlike
340       the "body" method), returning a Unicode string.
341
342       If the charset is known, it is used.  If there is no charset but the
343       content type is either "text/plain" or "text/html", us-ascii is
344       assumed.  Otherwise, an exception is thrown.
345
346   body_raw
347       This returns the body of the object, but doesn't decode the transfer
348       encoding.
349
350   decode_hook
351       This method is called before the Email::MIME::Encodings "decode"
352       method, to decode the body of non-binary messages (or binary messages,
353       if the "force_decode_hook" method returns true).  By default, this
354       method does nothing, but subclasses may define behavior.
355
356       This method could be used to implement the decryption of content in
357       secure email, for example.
358
359   content_type
360       This is a shortcut for access to the content type header.
361
362   filename
363       This provides the suggested filename for the attachment part. Normally
364       it will return the filename from the headers, but if "filename" is
365       passed a true parameter, it will generate an appropriate "stable"
366       filename if one is not found in the MIME headers.
367
368   invent_filename
369         my $filename = Email::MIME->invent_filename($content_type);
370
371       This routine is used by "filename" to generate filenames for attached
372       files.  It will attempt to choose a reasonable extension, falling back
373       to dat.
374
375   debug_structure
376         my $description = $email->debug_structure;
377
378       This method returns a string that describes the structure of the MIME
379       entity.  For example:
380
381         + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5"
382           + text/plain
383           + text/html
384

CONFIGURATION

386       The variable $Email::MIME::MAX_DEPTH is the maximum depth of parts that
387       will be processed.  It defaults to 10, already higher than legitimate
388       mail is ever likely to be.  This value may go up over time as the
389       parser is improved.
390

TODO

392       All of the Email::MIME-specific guts should move to a single entry on
393       the object's guts.  This will require changes to both Email::MIME and
394       Email::MIME::Modifier, sadly.
395

SEE ALSO

397       Email::Simple, Email::MIME::Modifier, Email::MIME::Creator.
398

THANKS

400       This module was generously sponsored by Best Practical
401       (http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.
402

AUTHORS

404       •   Ricardo SIGNES <rjbs@cpan.org>
405
406       •   Casey West <casey@geeknest.com>
407
408       •   Simon Cozens <simon@cpan.org>
409

CONTRIBUTORS

411       •   Alex Vandiver <alexmv@mit.edu>
412
413       •   Anirvan Chatterjee <anirvan@users.noreply.github.com>
414
415       •   Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
416
417       •   Brian Cassidy <bricas@cpan.org>
418
419       •   Damian Lukowski <damian.lukowski@credativ.de>
420
421       •   Dan Book <grinnz@gmail.com>
422
423       •   David Steinbrunner <dsteinbrunner@pobox.com>
424
425       •   Dotan Dimet <dotan@corky.net>
426
427       •   dxdc <dan@element26.net>
428
429       •   Eric Wong <e@80x24.org>
430
431       •   Geraint Edwards <gedge-oss@yadn.org>
432
433       •   Jesse Luehrs <doy@tozt.net>
434
435       •   Kurt Anderson <kboth@drkurt.com>
436
437       •   Lance A. Brown <lance@bearcircle.net>
438
439       •   Matthew Horsfall (alh) <wolfsage@gmail.com>
440
441       •   memememomo <memememomo@gmail.com>
442
443       •   Michael McClimon <michael@mcclimon.org>
444
445       •   Pali <pali@cpan.org>
446
447       •   Ricardo Signes <rjbs@semiotic.systems>
448
449       •   Shawn Sorichetti <ssoriche@coloredblocks.com>
450
451       •   Tomohiro Hosaka <bokutin@bokut.in>
452
454       This software is copyright (c) 2004 by Simon Cozens and Casey West.
455
456       This is free software; you can redistribute it and/or modify it under
457       the same terms as the Perl 5 programming language system itself.
458
459
460
461perl v5.32.1                      2021-01-27                    Email::MIME(3)
Impressum