1Email::MIME(3) User Contributed Perl Documentation Email::MIME(3)
2
6 Email::MIME - easy MIME message handling
7
9 version 1.953
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. 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 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 body_raw()
216 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 body_str_set
226 $email->body_str_set($unicode_str);
227 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 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 disposition_set
238 $email->disposition_set( 'attachment' );
239 Alter the "Content-Disposition" of a message. All header attributes
241 will remain intact.
242 filename_set
244 $email->filename_set( 'boo.pdf' );
245 Sets the filename attribute in the "Content-Disposition" header. All
247 other header information is preserved when setting this attribute.
248 parts_set
250 $email->parts_set( \@new_parts );
251 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 parts_add
258 $email->parts_add( \@more_parts );
259 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 walk_parts
265 $email->walk_parts(sub {
266 my ($part) = @_;
267 return if $part->subparts; # multipart
268 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 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 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 Try to use either "header_str" or "header_raw" as appropriate.
288 header_str_set
290 $email->header_str_set($header_name => @value_strings);
291 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 Alternatively, values can be objects with "as_mime_string" method.
298 Same as in method "create".
299 header_str_pairs
301 my @pairs = $email->header_str_pairs;
302 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 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 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 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 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 In scalar context, this method returns the number of parts.
329 This is a stupid method. Don't use it.
331 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 In scalar context, this method returns the number of subparts.
338 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 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 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 body_raw
354 This returns the body of the object, but doesn't decode the transfer
355 encoding.
356 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 This method could be used to implement the decryption of content in
364 secure email, for example.
365 content_type
367 This is a shortcut for access to the content type header.
368 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 invent_filename
376 my $filename = Email::MIME->invent_filename($content_type);
377 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 debug_structure
383 my $description = $email->debug_structure;
384 This method returns a string that describes the structure of the MIME
386 entity. For example:
387 + multipart/alternative; boundary="=_NextPart_2"; charset="BIG-5"
389 + text/plain
390 + text/html
391
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
399 Email::Simple
400
402 This module was generously sponsored by Best Practical
403 (http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.
404
406 • Ricardo SIGNES <cpan@semiotic.systems>
407 • Casey West <casey@geeknest.com>
409 • Simon Cozens <simon@cpan.org>
411
413 • Alex Vandiver <alexmv@mit.edu>
414 • Anirvan Chatterjee <anirvan@users.noreply.github.com>
416 • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
418 • Brian Cassidy <bricas@cpan.org>
420 • Damian Lukowski <damian.lukowski@credativ.de>
422 • Dan Book <grinnz@gmail.com>
424 • David Steinbrunner <dsteinbrunner@pobox.com>
426 • Dotan Dimet <dotan@corky.net>
428 • dxdc <dan@element26.net>
430 • Eric Wong <e@80x24.org>
432 • Geraint Edwards <gedge-oss@yadn.org>
434 • ivulfson <9122139+ivulfson@users.noreply.github.com>
436 • Jesse Luehrs <doy@tozt.net>
438 • Kurt Anderson <kboth@drkurt.com>
440 • Lance A. Brown <lance@bearcircle.net>
442 • Matthew Horsfall <wolfsage@gmail.com>
444 • memememomo <memememomo@gmail.com>
446 • Michael McClimon <michael@mcclimon.org>
448 • Mishrakk <48946018+Mishrakk@users.noreply.github.com>
450 • Pali <pali@cpan.org>
452 • Ricardo Signes <rjbs@semiotic.systems>
454 • Shawn Sorichetti <ssoriche@coloredblocks.com>
456 • Tomohiro Hosaka <bokutin@bokut.in>
458
460 This software is copyright (c) 2004 by Simon Cozens and Casey West.
461 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.
464perl v5.36.0 2023-01-20 Email::MIME(3)