1Email::MIME(3) User Contributed Perl Documentation Email::MIME(3)
2
6 Email::MIME - easy MIME message handling
7
9 version 1.952
10
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 use Email::MIME;
18 my $parsed = Email::MIME->new($message);
19 my @parts = $parsed->parts; # These will be Email::MIME objects, too.
21 my $decoded = $parsed->body;
22 my $non_decoded = $parsed->body_raw;
23 my $content_type = $parsed->content_type;
25 ...or...
27 use Email::MIME;
29 use IO::All;
30 # 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 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 # nesting parts
62 $email->parts_set(
63 [
64 $email->parts,
65 Email::MIME->create( parts => [ @parts ] ),
66 ],
67 );
68 # 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 # more advanced
76 $_->encoding_set( 'base64' ) for $email->parts;
77 # 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 print $email->as_string;
92
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
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 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
109 Please see Email::Simple for the base set of methods. It won't take
110 very long. Added to that, you have:
111 create
113 my $single = Email::MIME->create(
114 header_str => [ ... ],
115 body_str => '...',
116 attributes => { ... },
117 );
118 my $multi = Email::MIME->create(
120 header_str => [ ... ],
121 parts => [ ... ],
122 attributes => { ... },
123 );
124 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 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 A similar "header" parameter can be provided in addition to or instead
144 of "header_str". Its values will be used verbatim.
145 "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 from
149 "Email::MIME::Modifier". The allowed keys are: content_type, charset,
150 name, format, boundary, encoding, disposition, and filename. They will
151 be mapped to "$attr\_set" for message modification.
152 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 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 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 content_type_set
170 $email->content_type_set( 'text/html' );
171 Change the content type. All "Content-Type" header attributes will
173 remain intact.
174 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 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 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 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 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 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 See "Handling Malformed Data" in Encode for more information.
207 encoding_set
209 $email->encoding_set( 'base64' );
210 $email->encoding_set( 'quoted-printable' );
211 $email->encoding_set( '8bit' );
212 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
216 "body_raw()" method, will be changed to reflect the new encoding.
217 body_set
219 $email->body_set( $unencoded_body_string );
220 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 This method overrides the default "body_set()" method.
226 body_str_set
228 $email->body_str_set($unicode_str);
229 This method behaves like "body_set", but assumes that the given value
231 is a Unicode string that should be encoded into the message's charset
232 before being set.
233 The charset must already be set, either manually (via the "attributes"
235 argument to "create" or "charset_set") or through the "Content-Type" of
236 a parsed message. If the charset can't be determined, an exception is
237 thrown.
238 disposition_set
240 $email->disposition_set( 'attachment' );
241 Alter the "Content-Disposition" of a message. All header attributes
243 will remain intact.
244 filename_set
246 $email->filename_set( 'boo.pdf' );
247 Sets the filename attribute in the "Content-Disposition" header. All
249 other header information is preserved when setting this attribute.
250 parts_set
252 $email->parts_set( \@new_parts );
253 Replaces the parts for an object. Accepts a reference to a list of
255 "Email::MIME" objects, representing the new parts. If this message was
256 originally a single part, the "Content-Type" header will be changed to
257 "multipart/mixed", and given a new boundary attribute.
258 parts_add
260 $email->parts_add( \@more_parts );
261 Adds MIME parts onto the current MIME part. This is a simple extension
263 of "parts_set" to make our lives easier. It accepts an array reference
264 of additional parts.
265 walk_parts
267 $email->walk_parts(sub {
268 my ($part) = @_;
269 return if $part->subparts; # multipart
270 if ( $part->content_type =~ m[text/html]i ) {
272 my $body = $part->body;
273 $body =~ s/<link [^>]+>//; # simple filter example
274 $part->body_set( $body );
275 }
276 });
277 Walks through all the MIME parts in a message and applies a callback to
279 each. Accepts a code reference as its only argument. The code reference
280 will be passed a single argument, the current MIME part within the top-
281 level MIME object. All changes will be applied in place.
282 header
284 Achtung! Beware this method! In Email::MIME, it means the same as
285 "header_str", but on an Email::Simple object, it means "header_raw".
286 Unless you always know what kind of object you have, you could get one
287 of two significantly different behaviors.
288 Try to use either "header_str" or "header_raw" as appropriate.
290 header_str_set
292 $email->header_str_set($header_name => @value_strings);
293 This behaves like "header_raw_set", but expects Unicode (character)
295 strings as the values to set, rather than pre-encoded byte strings. It
296 will encode them as MIME encoded-words if they contain any control or
297 8-bit characters.
298 Alternatively, values can be objects with "as_mime_string" method.
300 Same as in method "create".
301 header_str_pairs
303 my @pairs = $email->header_str_pairs;
304 This method behaves like "header_raw_pairs", returning a list of field
306 name/value pairs, but the values have been decoded to character
307 strings, when possible.
308 header_as_obj
310 my $first_obj = $email->header_as_obj($field);
311 my $nth_obj = $email->header_as_obj($field, $index);
312 my @all_objs = $email->header_as_obj($field);
313 my $nth_obj_of_class = $email->header_as_obj($field, $index, $class);
315 my @all_objs_of_class = $email->header_as_obj($field, undef, $class);
316 This method returns an object representation of the header value. It
318 instances new object via method "from_mime_string" of specified class.
319 Input argument for that class method is list of the raw MIME-encoded
320 values. If class argument is not specified then class name is taken
321 from the hash %Email::MIME::Header::header_to_class_map via key field.
322 Use class method "Email::MIME::Header->set_class_for_header($class,
323 $field)" for adding new mapping.
324 parts
326 This returns a list of "Email::MIME" objects reflecting the parts of
327 the message. If it's a single-part message, you get the original object
328 back.
329 In scalar context, this method returns the number of parts.
331 This is a stupid method. Don't use it.
333 subparts
335 This returns a list of "Email::MIME" objects reflecting the parts of
336 the message. If it's a single-part message, this method returns an
337 empty list.
338 In scalar context, this method returns the number of subparts.
340 body
342 This decodes and returns the body of the object as a byte string. For
343 top-level objects in multi-part messages, this is highly likely to be
344 something like "This is a multi-part message in MIME format."
345 body_str
347 This decodes both the Content-Transfer-Encoding layer of the body (like
348 the "body" method) as well as the charset encoding of the body (unlike
349 the "body" method), returning a Unicode string.
350 If the charset is known, it is used. If there is no charset but the
352 content type is either "text/plain" or "text/html", us-ascii is
353 assumed. Otherwise, an exception is thrown.
354 body_raw
356 This returns the body of the object, but doesn't decode the transfer
357 encoding.
358 decode_hook
360 This method is called before the Email::MIME::Encodings "decode"
361 method, to decode the body of non-binary messages (or binary messages,
362 if the "force_decode_hook" method returns true). By default, this
363 method does nothing, but subclasses may define behavior.
364 This method could be used to implement the decryption of content in
366 secure email, for example.
367 content_type
369 This is a shortcut for access to the content type header.
370 filename
372 This provides the suggested filename for the attachment part. Normally
373 it will return the filename from the headers, but if "filename" is
374 passed a true parameter, it will generate an appropriate "stable"
375 filename if one is not found in the MIME headers.
376 invent_filename
378 my $filename = Email::MIME->invent_filename($content_type);
379 This routine is used by "filename" to generate filenames for attached
381 files. It will attempt to choose a reasonable extension, falling back
382 to dat.
383 debug_structure
385 my $description = $email->debug_structure;
386 This method returns a string that describes the structure of the MIME
388 entity. For example:
389 + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5"
391 + text/plain
392 + text/html
393
395 The variable $Email::MIME::MAX_DEPTH is the maximum depth of parts that
396 will be processed. It defaults to 10, already higher than legitimate
397 mail is ever likely to be. This value may go up over time as the
398 parser is improved.
399
401 All of the Email::MIME-specific guts should move to a single entry on
402 the object's guts. This will require changes to both Email::MIME and
403 Email::MIME::Modifier, sadly.
404
406 Email::Simple, Email::MIME::Modifier, Email::MIME::Creator.
407
409 This module was generously sponsored by Best Practical
410 (http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.
411
413 • Ricardo SIGNES <rjbs@semiotic.systems>
414 • Casey West <casey@geeknest.com>
416 • Simon Cozens <simon@cpan.org>
418
420 • Alex Vandiver <alexmv@mit.edu>
421 • Anirvan Chatterjee <anirvan@users.noreply.github.com>
423 • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
425 • Brian Cassidy <bricas@cpan.org>
427 • Damian Lukowski <damian.lukowski@credativ.de>
429 • Dan Book <grinnz@gmail.com>
431 • David Steinbrunner <dsteinbrunner@pobox.com>
433 • Dotan Dimet <dotan@corky.net>
435 • dxdc <dan@element26.net>
437 • Eric Wong <e@80x24.org>
439 • Geraint Edwards <gedge-oss@yadn.org>
441 • ivulfson <9122139+ivulfson@users.noreply.github.com>
443 • Jesse Luehrs <doy@tozt.net>
445 • Kurt Anderson <kboth@drkurt.com>
447 • Lance A. Brown <lance@bearcircle.net>
449 • Matthew Horsfall <wolfsage@gmail.com>
451 • memememomo <memememomo@gmail.com>
453 • Michael McClimon <michael@mcclimon.org>
455 • Mishrakk <48946018+Mishrakk@users.noreply.github.com>
457 • Pali <pali@cpan.org>
459 • Shawn Sorichetti <ssoriche@coloredblocks.com>
461 • Tomohiro Hosaka <bokutin@bokut.in>
463
465 This software is copyright (c) 2004 by Simon Cozens and Casey West.
466 This is free software; you can redistribute it and/or modify it under
468 the same terms as the Perl 5 programming language system itself.
469perl v5.34.0 2022-01-21 Email::MIME(3)