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