1Email::MIME(3) User Contributed Perl Documentation Email::MIME(3)
2
6 Email::MIME - easy MIME message handling
7
9 version 1.949
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 Please see Email::Simple for the base set of methods. It won't take
101 very long. Added to that, you have:
102 create
104 my $single = Email::MIME->create(
105 header_str => [ ... ],
106 body_str => '...',
107 attributes => { ... },
108 );
109 my $multi = Email::MIME->create(
111 header_str => [ ... ],
112 parts => [ ... ],
113 attributes => { ... },
114 );
115 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 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 A similar "header" parameter can be provided in addition to or instead
135 of "header_str". Its values will be used verbatim.
136 "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 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 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 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 content_type_set
161 $email->content_type_set( 'text/html' );
162 Change the content type. All "Content-Type" header attributes will
164 remain intact.
165 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 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 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 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 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 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 See "Handling Malformed Data" in Encode for more information.
198 encoding_set
200 $email->encoding_set( 'base64' );
201 $email->encoding_set( 'quoted-printable' );
202 $email->encoding_set( '8bit' );
203 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 body_set
210 $email->body_set( $unencoded_body_string );
211 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 This method overrides the default "body_set()" method.
217 body_str_set
219 $email->body_str_set($unicode_str);
220 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 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 disposition_set
231 $email->disposition_set( 'attachment' );
232 Alter the "Content-Disposition" of a message. All header attributes
234 will remain intact.
235 filename_set
237 $email->filename_set( 'boo.pdf' );
238 Sets the filename attribute in the "Content-Disposition" header. All
240 other header information is preserved when setting this attribute.
241 parts_set
243 $email->parts_set( \@new_parts );
244 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 parts_add
251 $email->parts_add( \@more_parts );
252 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 walk_parts
258 $email->walk_parts(sub {
259 my ($part) = @_;
260 return if $part->subparts; # multipart
261 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 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 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 Try to use either "header_str" or "header_raw" as appropriate.
281 header_str_set
283 $email->header_str_set($header_name => @value_strings);
284 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 Alternatively, values can be objects with "as_mime_string" method.
291 Same as in method "create".
292 header_str_pairs
294 my @pairs = $email->header_str_pairs;
295 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 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 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 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 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 In scalar context, this method returns the number of parts.
322 This is a stupid method. Don't use it.
324 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 In scalar context, this method returns the number of subparts.
331 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 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 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 body_raw
347 This returns the body of the object, but doesn't decode the transfer
348 encoding.
349 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 This method could be used to implement the decryption of content in
357 secure email, for example.
358 content_type
360 This is a shortcut for access to the content type header.
361 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 invent_filename
369 my $filename = Email::MIME->invent_filename($content_type);
370 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 debug_structure
376 my $description = $email->debug_structure;
377 This method returns a string that describes the structure of the MIME
379 entity. For example:
380 + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5"
382 + text/plain
383 + text/html
384
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
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
397 Email::Simple, Email::MIME::Modifier, Email::MIME::Creator.
398
400 This module was generously sponsored by Best Practical
401 (http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.
402
404 • Ricardo SIGNES <rjbs@cpan.org>
405 • Casey West <casey@geeknest.com>
407 • Simon Cozens <simon@cpan.org>
409
411 • Alex Vandiver <alexmv@mit.edu>
412 • Anirvan Chatterjee <anirvan@users.noreply.github.com>
414 • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
416 • Brian Cassidy <bricas@cpan.org>
418 • Damian Lukowski <damian.lukowski@credativ.de>
420 • Dan Book <grinnz@gmail.com>
422 • David Steinbrunner <dsteinbrunner@pobox.com>
424 • Dotan Dimet <dotan@corky.net>
426 • dxdc <dan@element26.net>
428 • Eric Wong <e@80x24.org>
430 • Geraint Edwards <gedge-oss@yadn.org>
432 • Jesse Luehrs <doy@tozt.net>
434 • Kurt Anderson <kboth@drkurt.com>
436 • Lance A. Brown <lance@bearcircle.net>
438 • Matthew Horsfall (alh) <wolfsage@gmail.com>
440 • memememomo <memememomo@gmail.com>
442 • Michael McClimon <michael@mcclimon.org>
444 • Pali <pali@cpan.org>
446 • Ricardo Signes <rjbs@semiotic.systems>
448 • Shawn Sorichetti <ssoriche@coloredblocks.com>
450 • Tomohiro Hosaka <bokutin@bokut.in>
452
454 This software is copyright (c) 2004 by Simon Cozens and Casey West.
455 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.
458perl v5.32.1 2021-01-27 Email::MIME(3)