1MIME::Tools(3) User Contributed Perl Documentation MIME::Tools(3)
2
6 MIME-tools - modules for parsing (and creating!) MIME entities
7
9 Here's some pretty basic code for parsing a MIME message, and
10 outputting its decoded components to a given directory:
11 use MIME::Parser;
13 ### Create parser, and set some parsing options:
15 my $parser = new MIME::Parser;
16 $parser->output_under("$ENV{HOME}/mimemail");
17 ### Parse input:
19 $entity = $parser->parse(\*STDIN) or die "parse failed\n";
20 ### Take a look at the top-level entity (and any parts it has):
22 $entity->dump_skeleton;
23 Here's some code which composes and sends a MIME message containing
25 three parts: a text file, an attached GIF, and some more text:
26 use MIME::Entity;
28 ### Create the top-level, and set up the mail headers:
30 $top = MIME::Entity->build(Type =>"multipart/mixed",
31 From => "me\@myhost.com",
32 To => "you\@yourhost.com",
33 Subject => "Hello, nurse!");
34 ### Part #1: a simple text document:
36 $top->attach(Path=>"./testin/short.txt");
37 ### Part #2: a GIF file:
39 $top->attach(Path => "./docs/mime-sm.gif",
40 Type => "image/gif",
41 Encoding => "base64");
42 ### Part #3: some literal text:
44 $top->attach(Data=>$message);
45 ### Send it:
47 open MAIL, "| /usr/lib/sendmail -t -oi -oem" or die "open: $!";
48 $top->print(\*MAIL);
49 close MAIL;
50 For more examples, look at the scripts in the examples directory of the
52 MIME-tools distribution.
53
55 MIME-tools is a collection of Perl5 MIME:: modules for parsing,
56 decoding, and generating single- or multipart (even nested multipart)
57 MIME messages. (Yes, kids, that means you can send messages with
58 attached GIF files).
59
61 You will need the following installed on your system:
62 File::Path
64 File::Spec
65 IPC::Open2 (optional)
66 MIME::Base64
67 MIME::QuotedPrint
68 Net::SMTP
69 Mail::Internet, ... from the MailTools distribution.
70 See the Makefile.PL in your distribution for the most-comprehensive
72 list of prerequisite modules and their version numbers.
73
75 Overview of the classes
76 Here are the classes you'll generally be dealing with directly:
77 (START HERE) results() .-----------------.
79 \ .-------->| MIME:: |
80 .-----------. / | Parser::Results |
81 | MIME:: |--' `-----------------'
82 | Parser |--. .-----------------.
83 `-----------' \ filer() | MIME:: |
84 | parse() `-------->| Parser::Filer |
85 | gives you `-----------------'
86 | a... | output_path()
87 | | determines
88 | | path() of...
89 | head() .--------. |
90 | returns... | MIME:: | get() |
91 V .-------->| Head | etc... |
92 .--------./ `--------' |
93 .---> | MIME:: | |
94 `-----| Entity | .--------. |
95 parts() `--------'\ | MIME:: | /
96 returns `-------->| Body |<---------'
97 sub-entities bodyhandle() `--------'
98 (if any) returns... | open()
99 | returns...
100 |
101 V
102 .--------. read()
103 | IO:: | getline()
104 | Handle | print()
105 `--------' etc...
106 To illustrate, parsing works this way:
108 • The "parser" parses the MIME stream. A parser is an instance of
110 "MIME::Parser". You hand it an input stream (like a filehandle) to
111 parse a message from: if the parse is successful, the result is an
112 "entity".
113 • A parsed message is represented by an "entity". An entity is an
115 instance of "MIME::Entity" (a subclass of "Mail::Internet"). If
116 the message had "parts" (e.g., attachments), then those parts are
117 "entities" as well, contained inside the top-level entity. Each
118 entity has a "head" and a "body".
119 • The entity's "head" contains information about the message. A
121 "head" is an instance of "MIME::Head" (a subclass of
122 "Mail::Header"). It contains information from the message header:
123 content type, sender, subject line, etc.
124 • The entity's "body" knows where the message data is. You can ask
126 to "open" this data source for reading or writing, and you will get
127 back an "I/O handle".
128 • You can open() a "body" and get an "I/O handle" to read/write
130 message data. This handle is an object that is basically like an
131 IO::Handle... it can be any class, so long as it supports a small,
132 standard set of methods for reading from or writing to the
133 underlying data source.
134 A typical multipart message containing two parts -- a textual greeting
136 and an "attached" GIF file -- would be a tree of MIME::Entity objects,
137 each of which would have its own MIME::Head. Like this:
138 .--------.
140 | MIME:: | Content-type: multipart/mixed
141 | Entity | Subject: Happy Samhaine!
142 `--------'
143 |
144 `----.
145 parts |
146 | .--------.
147 |---| MIME:: | Content-type: text/plain; charset=us-ascii
148 | | Entity | Content-transfer-encoding: 7bit
149 | `--------'
150 | .--------.
151 |---| MIME:: | Content-type: image/gif
152 | Entity | Content-transfer-encoding: base64
153 `--------' Content-disposition: inline;
154 filename="hs.gif"
155 Parsing messages
157 You usually start by creating an instance of MIME::Parser and setting
158 up certain parsing parameters: what directory to save extracted files
159 to, how to name the files, etc.
160 You then give that instance a readable filehandle on which waits a MIME
162 message. If all goes well, you will get back a MIME::Entity object (a
163 subclass of Mail::Internet), which consists of...
164 • A MIME::Head (a subclass of Mail::Header) which holds the MIME
166 header data.
167 • A MIME::Body, which is a object that knows where the body data is.
169 You ask this object to "open" itself for reading, and it will hand
170 you back an "I/O handle" for reading the data: this could be of any
171 class, so long as it conforms to a subset of the IO::Handle
172 interface.
173 If the original message was a multipart document, the MIME::Entity
175 object will have a non-empty list of "parts", each of which is in turn
176 a MIME::Entity (which might also be a multipart entity, etc, etc...).
177 Internally, the parser (in MIME::Parser) asks for instances of
179 MIME::Decoder whenever it needs to decode an encoded file.
180 MIME::Decoder has a mapping from supported encodings (e.g., 'base64')
181 to classes whose instances can decode them. You can add to this
182 mapping to try out new/experiment encodings. You can also use
183 MIME::Decoder by itself.
184 Composing messages
186 All message composition is done via the MIME::Entity class. For
187 single-part messages, you can use the MIME::Entity/build constructor to
188 create MIME entities very easily.
189 For multipart messages, you can start by creating a top-level
191 "multipart" entity with MIME::Entity::build(), and then use the similar
192 MIME::Entity::attach() method to attach parts to that message. Please
193 note: what most people think of as "a text message with an attached GIF
194 file" is really a multipart message with 2 parts: the first being the
195 text message, and the second being the GIF file.
196 When building MIME a entity, you'll have to provide two very important
198 pieces of information: the content type and the content transfer
199 encoding. The type is usually easy, as it is directly determined by
200 the file format; e.g., an HTML file is "text/html". The encoding,
201 however, is trickier... for example, some HTML files are
202 "7bit"-compliant, but others might have very long lines and would need
203 to be sent "quoted-printable" for reliability.
204 See the section on encoding/decoding for more details, as well as "A
206 MIME PRIMER" below.
207 Sending email
209 Since MIME::Entity inherits directly from Mail::Internet, you can use
210 the normal Mail::Internet mechanisms to send email. For example,
211 $entity->smtpsend;
213 Encoding/decoding support
215 The MIME::Decoder class can be used to encode as well; this is done
216 when printing MIME entities. All the standard encodings are supported
217 (see "A MIME PRIMER" below for details):
218 Encoding: | Normally used when message contents are:
220 -------------------------------------------------------------------
221 7bit | 7-bit data with under 1000 chars/line, or multipart.
222 8bit | 8-bit data with under 1000 chars/line.
223 binary | 8-bit data with some long lines (or no line breaks).
224 quoted-printable | Text files with some 8-bit chars (e.g., Latin-1 text).
225 base64 | Binary files.
226 Which encoding you choose for a given document depends largely on (1)
228 what you know about the document's contents (text vs binary), and (2)
229 whether you need the resulting message to have a reliable encoding for
230 7-bit Internet email transport.
231 In general, only "quoted-printable" and "base64" guarantee reliable
233 transport of all data; the other three "no-encoding" encodings simply
234 pass the data through, and are only reliable if that data is 7bit ASCII
235 with under 1000 characters per line, and has no conflicts with the
236 multipart boundaries.
237 I've considered making it so that the content-type and encoding can be
239 automatically inferred from the file's path, but that seems to be
240 asking for trouble... or at least, for Mail::Cap...
241 Message-logging
243 MIME-tools is a large and complex toolkit which tries to deal with a
244 wide variety of external input. It's sometimes helpful to see what's
245 really going on behind the scenes. There are several kinds of messages
246 logged by the toolkit itself:
247 Debug messages
249 These are printed directly to the STDERR, with a prefix of
250 "MIME-tools: debug".
251 Debug message are only logged if you have turned "debugging" on in
253 the MIME::Tools configuration.
254 Warning messages
256 These are logged by the standard Perl warn() mechanism to indicate
257 an unusual situation. They all have a prefix of "MIME-tools:
258 warning".
259 Warning messages are only logged if $^W is set true and MIME::Tools
261 is not configured to be "quiet".
262 Error messages
264 These are logged by the standard Perl warn() mechanism to indicate
265 that something actually failed. They all have a prefix of
266 "MIME-tools: error".
267 Error messages are only logged if $^W is set true and MIME::Tools
269 is not configured to be "quiet".
270 Usage messages
272 Unlike "typical" warnings above, which warn about problems
273 processing data, usage-warnings are for alerting developers of
274 deprecated methods and suspicious invocations.
275 Usage messages are currently only logged if $^W is set true and
277 MIME::Tools is not configured to be "quiet".
278 When a MIME::Parser (or one of its internal helper classes) wants to
280 report a message, it generally does so by recording the message to the
281 MIME::Parser::Results object immediately before invoking the
282 appropriate function above. That means each parsing run has its own
283 trace-log which can be examined for problems.
284 Configuring the toolkit
286 If you want to tweak the way this toolkit works (for example, to turn
287 on debugging), use the routines in the MIME::Tools module.
288 debugging
290 Turn debugging on or off. Default is false (off).
291 MIME::Tools->debugging(1);
293 quiet
295 Turn the reporting of warning/error messages on or off. Default is
296 true, meaning that these message are silenced.
297 MIME::Tools->quiet(1);
299 version
301 Return the toolkit version.
302 print MIME::Tools->version, "\n";
304
306 Take a look at the examples
307 The MIME-Tools distribution comes with an "examples" directory. The
308 scripts in there are basically just tossed-together, but they'll give
309 you some ideas of how to use the parser.
310 Run with warnings enabled
312 Always run your Perl script with "-w". If you see a warning about a
313 deprecated method, change your code ASAP. This will ease upgrades
314 tremendously.
315 Avoid non-standard encodings
317 Don't try to MIME-encode using the non-standard MIME encodings. It's
318 just not a good practice if you want people to be able to read your
319 messages.
320 Plan for thrown exceptions
322 For example, if your mail-handling code absolutely must not die, then
323 perform mail parsing like this:
324 $entity = eval { $parser->parse(\*INPUT) };
326 Parsing is a complex process, and some components may throw exceptions
328 if seriously-bad things happen. Since "seriously-bad" is in the eye of
329 the beholder, you're better off catching possible exceptions instead of
330 asking me to propagate "undef" up the stack. Use of exceptions in
331 reusable modules is one of those religious issues we're never all going
332 to agree upon; thankfully, that's what "eval{}" is good for.
333 Check the parser results for warnings/errors
335 As of 5.3xx, the parser tries extremely hard to give you a
336 MIME::Entity. If there were any problems, it logs warnings/errors to
337 the underlying "results" object (see MIME::Parser::Results). Look at
338 that object after each parse. Print out the warnings and errors,
339 especially if messages don't parse the way you thought they would.
340 Don't plan on printing exactly what you parsed!
342 Parsing is a (slightly) lossy operation. Because of things like
343 ambiguities in base64-encoding, the following is not going to spit out
344 its input unchanged in all cases:
345 $entity = $parser->parse(\*STDIN);
347 $entity->print(\*STDOUT);
348 If you're using MIME::Tools to process email, remember to save the data
350 you parse if you want to send it on unchanged. This is vital for
351 things like PGP-signed email.
352 Understand how international characters are represented
354 The MIME standard allows for text strings in headers to contain
355 characters from any character set, by using special sequences which
356 look like this:
357 =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
359 To be consistent with the existing Mail::Field classes, MIME::Tools
361 does not automatically unencode these strings, since doing so would
362 lose the character-set information and interfere with the parsing of
363 fields (see "decode_headers" in MIME::Parser for a full explanation).
364 That means you should be prepared to deal with these encoded strings.
365 The most common question then is, how do I decode these encoded
367 strings? The answer depends on what you want to decode them to: ASCII,
368 Latin1, UTF-8, etc. Be aware that your "target" representation may not
369 support all possible character sets you might encounter; for example,
370 Latin1 (ISO-8859-1) has no way of representing Big5 (Chinese)
371 characters. A common practice is to represent "untranslateable"
372 characters as "?"s, or to ignore them completely.
373 To unencode the strings into some of the more-popular Western byte
375 representations (e.g., Latin1, Latin2, etc.), you can use the decoders
376 in MIME::WordDecoder (see MIME::WordDecoder). The simplest way is by
377 using "unmime()", a function wrapped around your "default" decoder, as
378 follows:
379 use MIME::WordDecoder;
381 ...
382 $subject = unmime $entity->head->get('subject');
383 One place this is done automatically is in extracting the recommended
385 filename for a part while parsing. That's why you should start by
386 setting up the best "default" decoder if the default target of Latin1
387 isn't to your liking.
388
390 Fuzzing of CRLF and newline on input
391 RFC 2045 dictates that MIME streams have lines terminated by CRLF
392 ("\r\n"). However, it is extremely likely that folks will want to
393 parse MIME streams where each line ends in the local newline character
394 "\n" instead.
395 An attempt has been made to allow the parser to handle both CRLF and
397 newline-terminated input.
398 Fuzzing of CRLF and newline when decoding
400 The "7bit" and "8bit" decoders will decode both a "\n" and a "\r\n"
401 end-of-line sequence into a "\n".
402 The "binary" decoder (default if no encoding specified) still outputs
404 stuff verbatim... so a MIME message with CRLFs and no explicit encoding
405 will be output as a text file that, on many systems, will have an
406 annoying ^M at the end of each line... but this is as it should be.
407 Fuzzing of CRLF and newline when encoding/composing
409 TODO FIXME All encoders currently output the end-of-line sequence as a
410 "\n", with the assumption that the local mail agent will perform the
411 conversion from newline to CRLF when sending the mail. However, there
412 probably should be an option to output CRLF as per RFC 2045
413 Inability to handle multipart boundaries with embedded newlines
415 Let's get something straight: this is an evil, EVIL practice. If your
416 mailer creates multipart boundary strings that contain newlines, give
417 it two weeks notice and find another one. If your mail robot receives
418 MIME mail like this, regard it as syntactically incorrect, which it is.
419 Ignoring non-header headers
421 People like to hand the parser raw messages straight from POP3 or from
422 a mailbox. There is often predictable non-header information in front
423 of the real headers; e.g., the initial "From" line in the following
424 message:
425 From - Wed Mar 22 02:13:18 2000
427 Return-Path: <eryq@zeegee.com>
428 Subject: Hello
429 The parser simply ignores such stuff quietly. Perhaps it shouldn't,
431 but most people seem to want that behavior.
432 Fuzzing of empty multipart preambles
434 Please note that there is currently an ambiguity in the way preambles
435 are parsed in. The following message fragments both are regarded as
436 having an empty preamble (where "\n" indicates a newline character):
437 Content-type: multipart/mixed; boundary="xyz"\n
439 Subject: This message (#1) has an empty preamble\n
440 \n
441 --xyz\n
442 ...
443 Content-type: multipart/mixed; boundary="xyz"\n
445 Subject: This message (#2) also has an empty preamble\n
446 \n
447 \n
448 --xyz\n
449 ...
450 In both cases, the first completely-empty line (after the "Subject")
452 marks the end of the header.
453 But we should clearly ignore the second empty line in message #2, since
455 it fills the role of "the newline which is only there to make sure that
456 the boundary is at the beginning of a line". Such newlines are never
457 part of the content preceding the boundary; thus, there is no preamble
458 "content" in message #2.
459 However, it seems clear that message #1 also has no preamble "content",
461 and is in fact merely a compact representation of an empty preamble.
462 Use of a temp file during parsing
464 Why not do everything in core? Although the amount of core available
465 on even a modest home system continues to grow, the size of attachments
466 continues to grow with it. I wanted to make sure that even users with
467 small systems could deal with decoding multi-megabyte sounds and movie
468 files. That means not being core-bound.
469 As of the released 5.3xx, MIME::Parser gets by with only one temp file
471 open per parser. This temp file provides a sort of infinite scratch
472 space for dealing with the current message part. It's fast and
473 lightweight, but you should know about it anyway.
474 Why do I assume that MIME objects are email objects?
476 Achim Bohnet once pointed out that MIME headers do nothing more than
477 store a collection of attributes, and thus could be represented as
478 objects which don't inherit from Mail::Header.
479 I agree in principle, but RFC 2045 says otherwise. RFC 2045 [MIME]
481 headers are a syntactic subset of RFC-822 [email] headers. Perhaps a
482 better name for these modules would have been RFC1521:: instead of
483 MIME::, but we're a little beyond that stage now.
484 When I originally wrote these modules for the CPAN, I agonized for a
486 long time about whether or not they really should subclass from
487 Mail::Internet (then at version 1.17). Thanks to Graham Barr, who
488 graciously evolved MailTools 1.06 to be more MIME-friendly, unification
489 was achieved at MIME-tools release 2.0. The benefits in reuse alone
490 have been substantial.
491
493 So you need to parse (or create) MIME, but you're not quite up on the
494 specifics? No problem...
495 Glossary
497 Here are some definitions adapted from RFC 1521 (predecessor of the
498 current RFC 204[56789] defining MIME) explaining the terminology we
499 use; each is accompanied by the equivalent in MIME:: module terms...
500 attachment
502 An "attachment" is common slang for any part of a multipart message
503 -- except, perhaps, for the first part, which normally carries a
504 user message describing the attachments that follow (e.g.: "Hey
505 dude, here's that GIF file I promised you.").
506 In our system, an attachment is just a MIME::Entity under the top-
508 level entity, probably one of its parts.
509 body
511 The "body" of an entity is that portion of the entity which follows
512 the header and which contains the real message content. For
513 example, if your MIME message has a GIF file attachment, then the
514 body of that attachment is the base64-encoded GIF file itself.
515 A body is represented by an instance of MIME::Body. You get the
517 body of an entity by sending it a bodyhandle() message.
518 body part
520 One of the parts of the body of a multipart /entity. A body part
521 has a /header and a /body, so it makes sense to speak about the
522 body of a body part.
523 Since a body part is just a kind of entity, it's represented by an
525 instance of MIME::Entity.
526 entity
528 An "entity" means either a /message or a /body part. All entities
529 have a /header and a /body.
530 An entity is represented by an instance of MIME::Entity. There are
532 instance methods for recovering the header (a MIME::Head) and the
533 body (a MIME::Body).
534 header
536 This is the top portion of the MIME message, which contains the
537 "Content-type", "Content-transfer-encoding", etc. Every MIME
538 entity has a header, represented by an instance of MIME::Head. You
539 get the header of an entity by sending it a head() message.
540 message
542 A "message" generally means the complete (or "top-level") message
543 being transferred on a network.
544 There currently is no explicit package for "messages"; under
546 MIME::, messages are streams of data which may be read in from
547 files or filehandles. You can think of the MIME::Entity returned
548 by the MIME::Parser as representing the full message.
549 Content types
551 This indicates what kind of data is in the MIME message, usually as
552 majortype/minortype. The standard major types are shown below. A
553 more-comprehensive listing may be found in RFC-2046.
554 application
556 Data which does not fit in any of the other categories,
557 particularly data to be processed by some type of application
558 program. "application/octet-stream", "application/gzip",
559 "application/postscript"...
560 audio
562 Audio data. "audio/basic"...
563 image
565 Graphics data. "image/gif", "image/jpeg"...
566 message
568 A message, usually another mail or MIME message.
569 "message/rfc822"...
570 multipart
572 A message containing other messages. "multipart/mixed",
573 "multipart/alternative"...
574 text
576 Textual data, meant for humans to read. "text/plain",
577 "text/html"...
578 video
580 Video or video+audio data. "video/mpeg"...
581 Content transfer encodings
583 This is how the message body is packaged up for safe transit. There
584 are the 5 major MIME encodings. A more-comprehensive listing may be
585 found in RFC-2045.
586 7bit
588 No encoding is done at all. This label simply asserts that no
589 8-bit characters are present, and that lines do not exceed 1000
590 characters in length (including the CRLF).
591 8bit
593 No encoding is done at all. This label simply asserts that the
594 message might contain 8-bit characters, and that lines do not
595 exceed 1000 characters in length (including the CRLF).
596 binary
598 No encoding is done at all. This label simply asserts that the
599 message might contain 8-bit characters, and that lines may exceed
600 1000 characters in length. Such messages are the least likely to
601 get through mail gateways.
602 base64
604 A standard encoding, which maps arbitrary binary data to the 7bit
605 domain. Like "uuencode", but very well-defined. This is how you
606 should send essentially binary information (tar files, GIFs, JPEGs,
607 etc.).
608 quoted-printable
610 A standard encoding, which maps arbitrary line-oriented data to the
611 7bit domain. Useful for encoding messages which are textual in
612 nature, yet which contain non-ASCII characters (e.g., Latin-1,
613 Latin-2, or any other 8-bit alphabet).
614
616 MIME::Parser, MIME::Head, MIME::Body, MIME::Entity, MIME::Decoder,
617 Mail::Header, Mail::Internet
618 At the time of this writing, the MIME-tools homepage was
620 http://www.mimedefang.org/static/mime-tools.php. Check there for
621 updates and support.
622 The MIME format is documented in RFCs 1521-1522, and more recently in
624 RFCs 2045-2049.
625 The MIME header format is an outgrowth of the mail header format
627 documented in RFC 822.
628
630 Please file support requests via rt.cpan.org.
631
633 Released as MIME-parser (1.0): 28 April 1996. Released as MIME-tools
634 (2.0): Halloween 1996. Released as MIME-tools (4.0): Christmas 1997.
635 Released as MIME-tools (5.0): Mother's Day 2000.
636 See ChangeLog file for full details.
638
640 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
641 Dianne Skoll (dianne@skoll.ca)
642 Copyright (c) 1998, 1999 by ZeeGee Software Inc (www.zeegee.com).
644 Copyright (c) 2004 by Roaring Penguin Software Inc Copyright (c) 2022
645 by Dianne Skoll
646 This program is free software; you can redistribute it and/or modify it
648 under the same terms as Perl itself.
649 See the COPYING file in the distribution for details.
651
653 This kit would not have been possible but for the direct contributions
654 of the following:
655 Gisle Aas The MIME encoding/decoding modules.
657 Laurent Amon Bug reports and suggestions.
658 Graham Barr The new MailTools.
659 Achim Bohnet Numerous good suggestions, including the I/O model.
660 Kent Boortz Initial code for RFC-1522-decoding of MIME headers.
661 Andreas Koenig Numerous good ideas, tons of beta testing,
662 and help with CPAN-friendly packaging.
663 Igor Starovoitov Bug reports and suggestions.
664 Jason L Tibbitts III Bug reports, suggestions, patches.
665 Not to mention the Accidental Beta Test Team, whose bug reports (and
667 comments) have been invaluable in improving the whole:
668 Phil Abercrombie
670 Mike Blazer
671 Brandon Browning
672 Kurt Freytag
673 Steve Kilbane
674 Jake Morrison
675 Rolf Nelson
676 Joel Noble
677 Michael W. Normandin
678 Tim Pierce
679 Andrew Pimlott
680 Dragomir R. Radev
681 Nickolay Saukh
682 Russell Sutherland
683 Larry Virden
684 Zyx
685 Please forgive me if I've accidentally left you out. Better yet, email
687 me, and I'll put you in.
688
690 This program is free software; you can redistribute it and/or modify it
691 under the same terms as Perl itself.
692 See the COPYING file for more details.
694perl v5.36.0 2022-07-22 MIME::Tools(3)