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.953
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

PERL VERSION

100       This library should run on perls released even a long time ago.  It
101       should work on any version of perl released in the last five years.
102
103       Although it may work on older versions of perl, no guarantee is made
104       that the minimum required version will not be increased.  The version
105       may be increased for any reason, and there is no promise that patches
106       will be accepted to lower the minimum required perl.
107

METHODS

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

CONFIGURATION

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

SEE ALSO

399       Email::Simple
400

THANKS

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

AUTHORS

406       •   Ricardo SIGNES <cpan@semiotic.systems>
407
408       •   Casey West <casey@geeknest.com>
409
410       •   Simon Cozens <simon@cpan.org>
411

CONTRIBUTORS

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