1MIME::Lite(3) User Contributed Perl Documentation MIME::Lite(3)
2
6 MIME::Lite - low-calorie MIME generator
7
9 use MIME::Lite;
10 Create a single-part message:
12 ### Create a new single-part message, to send a GIF file:
14 $msg = MIME::Lite->new(
15 From =>'me@myhost.com',
16 To =>'you@yourhost.com',
17 Cc =>'some@other.com, some@more.com',
18 Subject =>'Helloooooo, nurse!',
19 Type =>'image/gif',
20 Encoding =>'base64',
21 Path =>'hellonurse.gif'
22 );
23 Create a multipart message (i.e., one with attachments):
25 ### Create a new multipart message:
27 $msg = MIME::Lite->new(
28 From =>'me@myhost.com',
29 To =>'you@yourhost.com',
30 Cc =>'some@other.com, some@more.com',
31 Subject =>'A message with 2 parts...',
32 Type =>'multipart/mixed'
33 );
34 ### Add parts (each "attach" has same arguments as "new"):
36 $msg->attach(Type =>'TEXT',
37 Data =>"Here's the GIF file you wanted"
38 );
39 $msg->attach(Type =>'image/gif',
40 Path =>'aaa000123.gif',
41 Filename =>'logo.gif',
42 Disposition => 'attachment'
43 );
44 Output a message:
46 ### Format as a string:
48 $str = $msg->as_string;
49 ### Print to a filehandle (say, a "sendmail" stream):
51 $msg->print(\*SENDMAIL);
52 Send a message:
54 ### Send in the "best" way (the default is to use "sendmail"):
56 $msg->send;
57
59 In the never-ending quest for great taste with fewer calories, we
60 proudly present: MIME::Lite.
61 MIME::Lite is intended as a simple, standalone module for generating
63 (not parsing!) MIME messages... specifically, it allows you to output a
64 simple, decent single- or multi-part message with text or binary
65 attachments. It does not require that you have the Mail:: or MIME::
66 modules installed.
67 You can specify each message part as either the literal data itself (in
69 a scalar or array), or as a string which can be given to open() to get
70 a readable filehandle (e.g., "<filename" or "somecommand⎪").
71 You don't need to worry about encoding your message data: this module
73 will do that for you. It handles the 5 standard MIME encodings.
74 If you need more sophisticated behavior, please get the MIME-tools
76 package instead. I will be more likely to add stuff to that toolkit
77 over this one.
78
80 Create a simple message containing just text
81 $msg = MIME::Lite->new(
83 From =>'me@myhost.com',
84 To =>'you@yourhost.com',
85 Cc =>'some@other.com, some@more.com',
86 Subject =>'Helloooooo, nurse!',
87 Data =>"How's it goin', eh?"
88 );
89 Create a simple message containing just an image
91 $msg = MIME::Lite->new(
93 From =>'me@myhost.com',
94 To =>'you@yourhost.com',
95 Cc =>'some@other.com, some@more.com',
96 Subject =>'Helloooooo, nurse!',
97 Type =>'image/gif',
98 Encoding =>'base64',
99 Path =>'hellonurse.gif'
100 );
101 Create a multipart message
103 ### Create the multipart "container":
105 $msg = MIME::Lite->new(
106 From =>'me@myhost.com',
107 To =>'you@yourhost.com',
108 Cc =>'some@other.com, some@more.com',
109 Subject =>'A message with 2 parts...',
110 Type =>'multipart/mixed'
111 );
112 ### Add the text message part:
114 ### (Note that "attach" has same arguments as "new"):
115 $msg->attach(Type =>'TEXT',
116 Data =>"Here's the GIF file you wanted"
117 );
118 ### Add the image part:
120 $msg->attach(Type =>'image/gif',
121 Path =>'aaa000123.gif',
122 Filename =>'logo.gif',
123 Disposition => 'attachment'
124 );
125 Attach a GIF to a text message
127 This will create a multipart message exactly as above, but using the
129 "attach to singlepart" hack:
130 ### Start with a simple text message:
132 $msg = MIME::Lite->new(
133 From =>'me@myhost.com',
134 To =>'you@yourhost.com',
135 Cc =>'some@other.com, some@more.com',
136 Subject =>'A message with 2 parts...',
137 Type =>'TEXT',
138 Data =>"Here's the GIF file you wanted"
139 );
140 ### Attach a part... the make the message a multipart automatically:
142 $msg->attach(Type =>'image/gif',
143 Path =>'aaa000123.gif',
144 Filename =>'logo.gif'
145 );
146 Attach a pre-prepared part to a message
148 ### Create a standalone part:
150 $part = MIME::Lite->new(
151 Type =>'text/html',
152 Data =>'<H1>Hello</H1>',
153 );
154 $part->attr('content-type.charset' => 'UTF8');
155 $part->add('X-Comment' => 'A message for you');
156 ### Attach it to any message:
158 $msg->attach($part);
159 Print a message to a filehandle
161 ### Write it to a filehandle:
163 $msg->print(\*STDOUT);
164 ### Write just the header:
166 $msg->print_header(\*STDOUT);
167 ### Write just the encoded body:
169 $msg->print_body(\*STDOUT);
170 Print a message into a string
172 ### Get entire message as a string:
174 $str = $msg->as_string;
175 ### Get just the header:
177 $str = $msg->header_as_string;
178 ### Get just the encoded body:
180 $str = $msg->body_as_string;
181 Send a message
183 ### Send in the "best" way (the default is to use "sendmail"):
185 $msg->send;
186 Send an HTML document... with images included!
188 $msg = MIME::Lite->new(
190 To =>'you@yourhost.com',
191 Subject =>'HTML with in-line images!',
192 Type =>'multipart/related'
193 );
194 $msg->attach(Type => 'text/html',
195 Data => qq{ <body>
196 Here's <i>my</i> image:
197 <img src="cid:myimage.gif">
198 </body> }
199 );
200 $msg->attach(Type => 'image/gif',
201 Id => 'myimage.gif',
202 Path => '/path/to/somefile.gif',
203 );
204 $msg->send();
205 Change how messages are sent
207 ### Do something like this in your 'main':
209 if ($I_DONT_HAVE_SENDMAIL) {
210 MIME::Lite->send('smtp', "smtp.myisp.net", Timeout=>60);
211 }
212 ### Now this will do the right thing:
214 $msg->send; ### will now use Net::SMTP as shown above
215
217 Global configuration
218 To alter the way the entire module behaves, you have the following
220 methods/options:
221 MIME::Lite->field_order()
223 When used as a classmethod, this changes the default order in which
224 headers are output for all messages. However, please consider
225 using the instance method variant instead, so you won't stomp on
226 other message senders in the same application.
227 MIME::Lite->quiet()
229 This classmethod can be used to suppress/unsuppress all warnings
230 coming from this module.
231 MIME::Lite->send()
233 When used as a classmethod, this can be used to specify a different
234 default mechanism for sending message. The initial default is:
235 MIME::Lite->send("sendmail", "/usr/lib/sendmail -t -oi -oem");
237 However, you should consider the similar but smarter and taint-safe
239 variant:
240 MIME::Lite->send("sendmail");
242 Or, for non-Unix users:
244 MIME::Lite->send("smtp");
246 $MIME::Lite::AUTO_CC
248 If true, automatically send to the Cc/Bcc addresses for
249 send_by_smtp(). Default is true.
250 $MIME::Lite::AUTO_CONTENT_TYPE
252 If true, try to automatically choose the content type from the file
253 name in "new()"/"build()". In other words, setting this true
254 changes the default "Type" from "TEXT" to "AUTO".
255 Default is false, since we must maintain backwards-compatibility
257 with prior behavior. Please consider keeping it false, and just
258 using Type 'AUTO' when you build() or attach().
259 $MIME::Lite::AUTO_ENCODE
261 If true, automatically choose the encoding from the content type.
262 Default is true.
263 $MIME::Lite::AUTO_VERIFY
265 If true, check paths to attachments right before printing, raising
266 an exception if any path is unreadable. Default is true.
267 $MIME::Lite::PARANOID
269 If true, we won't attempt to use MIME::Base64, MIME::QuotedPrint,
270 or MIME::Types, even if they're available. Default is false.
271 Please consider keeping it false, and trusting these other packages
272 to do the right thing.
273 Construction
275 new [PARAMHASH]
277 Class method, constructor. Create a new message object.
278 If any arguments are given, they are passed into "build()"; other‐
280 wise, just the empty object is created.
281 attach PART
283 attach PARAMHASH...
284 Instance method. Add a new part to this message, and return the
285 new part.
286 If you supply a single PART argument, it will be regarded as a
288 MIME::Lite object to be attached. Otherwise, this method assumes
289 that you are giving in the pairs of a PARAMHASH which will be sent
290 into "new()" to create the new part.
291 One of the possibly-quite-useful hacks thrown into this is the
293 "attach-to-singlepart" hack: if you attempt to attach a part (let's
294 call it "part 1") to a message that doesn't have a content-type of
295 "multipart" or "message", the following happens:
296 * A new part (call it "part 0") is made.
298 * The MIME attributes and data (but not the other headers) are
300 cut from the "self" message, and pasted into "part 0".
301 * The "self" is turned into a "multipart/mixed" message.
303 * The new "part 0" is added to the "self", and then "part 1" is
305 added.
306 One of the nice side-effects is that you can create a text message
308 and then add zero or more attachments to it, much in the same way
309 that a user agent like Netscape allows you to do.
310 build [PARAMHASH]
312 Class/instance method, initializer. Create (or initialize) a MIME
313 message object. Normally, you'll use the following keys in
314 PARAMHASH:
315 * Data, FH, or Path (either one of these, or none if multipart)
317 * Type (e.g., "image/jpeg")
318 * From, To, and Subject (if this is the "top level" of a message)
319 The PARAMHASH can contain the following keys:
321 (fieldname)
323 Any field you want placed in the message header, taken from the
324 standard list of header fields (you don't need to worry about
325 case):
326 Approved Encrypted Received Sender
328 Bcc From References Subject
329 Cc Keywords Reply-To To
330 Comments Message-ID Resent-* X-*
331 Content-* MIME-Version Return-Path
332 Date Organization
333 To give experienced users some veto power, these fields will be
335 set after the ones I set... so be careful: don't set any MIME
336 fields (like "Content-type") unless you know what you're doing!
337 To specify a fieldname that's not in the above list, even one
339 that's identical to an option below, just give it with a trail‐
340 ing ":", like "My-field:". When in doubt, that always signals
341 a mail field (and it sort of looks like one too).
342 Data
344 Alternative to "Path" or "FH". The actual message data. This
345 may be a scalar or a ref to an array of strings; if the latter,
346 the message consists of a simple concatenation of all the
347 strings in the array.
348 Datestamp
350 Optional. If given true (or omitted), we force the creation of
351 a "Date:" field stamped with the current date/time if this is a
352 top-level message. You may want this if using send_by_smtp().
353 If you don't want this to be done, either provide your own Date
354 or explicitly set this to false.
355 Disposition
357 Optional. The content disposition, "inline" or "attachment".
358 The default is "inline".
359 Encoding
361 Optional. The content transfer encoding that should be used to
362 encode your data:
363 Use encoding: ⎪ If your message contains:
365 ------------------------------------------------------------
366 7bit ⎪ Only 7-bit text, all lines <1000 characters
367 8bit ⎪ 8-bit text, all lines <1000 characters
368 quoted-printable ⎪ 8-bit text or long lines (more reliable than "8bit")
369 base64 ⎪ Largely non-textual data: a GIF, a tar file, etc.
370 The default is taken from the Type; generally it is "binary"
372 (no encoding) for text/*, message/*, and multipart/*, and
373 "base64" for everything else. A value of "binary" is generally
374 not suitable for sending anything but ASCII text files with
375 lines under 1000 characters, so consider using one of the other
376 values instead.
377 In the case of "7bit"/"8bit", long lines are automatically
379 chopped to legal length; in the case of "7bit", all 8-bit char‐
380 acters are automatically removed. This may not be what you
381 want, so pick your encoding well! For more info, see "A MIME
382 PRIMER".
383 FH Alternative to "Data" or "Path". Filehandle containing the
385 data, opened for reading. See "ReadNow" also.
386 Filename
388 Optional. The name of the attachment. You can use this to
389 supply a recommended filename for the end-user who is saving
390 the attachment to disk. You only need this if the filename at
391 the end of the "Path" is inadequate, or if you're using "Data"
392 instead of "Path". You should not put path information in here
393 (e.g., no "/" or "\" or ":" characters should be used).
394 Id Optional. Same as setting "content-id".
396 Length
398 Optional. Set the content length explicitly. Normally, this
399 header is automatically computed, but only under certain cir‐
400 cumstances (see "Limitations").
401 Path
403 Alternative to "Data" or "FH". Path to a file containing the
404 data... actually, it can be any open()able expression. If it
405 looks like a path, the last element will automatically be
406 treated as the filename. See "ReadNow" also.
407 ReadNow
409 Optional, for use with "Path". If true, will open the path and
410 slurp the contents into core now. This is useful if the Path
411 points to a command and you don't want to run the command over
412 and over if outputting the message several times. Fatal excep‐
413 tion raised if the open fails.
414 Top Optional. If defined, indicates whether or not this is a
416 "top-level" MIME message. The parts of a multipart message are
417 not top-level. Default is true.
418 Type
420 Optional. The MIME content type, or one of these special val‐
421 ues (case-sensitive):
422 "TEXT" means "text/plain"
424 "BINARY" means "application/octet-stream"
425 "AUTO" means attempt to guess from the filename, falling back
426 to 'application/octet-stream'. This is good if you have
427 MIME::Types on your system and you have no idea what
428 file might be used for the attachment.
429 The default is "TEXT", but it will be "AUTO" if you set
431 $AUTO_CONTENT_TYPE to true (sorry, but you have to enable it
432 explicitly, since we don't want to break code which depends on
433 the old behavior).
434 A picture being worth 1000 words (which is of course 2000 bytes, so
436 it's probably more of an "icon" than a "picture", but I
437 digress...), here are some examples:
438 $msg = MIME::Lite->build(
440 From => 'yelling@inter.com',
441 To => 'stocking@fish.net',
442 Subject => "Hi there!",
443 Type => 'TEXT',
444 Encoding => '7bit',
445 Data => "Just a quick note to say hi!");
446 $msg = MIME::Lite->build(
448 From => 'dorothy@emerald-city.oz',
449 To => 'gesundheit@edu.edu.edu',
450 Subject => "A gif for U"
451 Type => 'image/gif',
452 Path => "/home/httpd/logo.gif");
453 $msg = MIME::Lite->build(
455 From => 'laughing@all.of.us',
456 To => 'scarlett@fiddle.dee.de',
457 Subject => "A gzipp'ed tar file",
458 Type => 'x-gzip',
459 Path => "gzip < /usr/inc/somefile.tar ⎪",
460 ReadNow => 1,
461 Filename => "somefile.tgz");
462 To show you what's really going on, that last example could also
464 have been written:
465 $msg = new MIME::Lite;
467 $msg->build(Type => 'x-gzip',
468 Path => "gzip < /usr/inc/somefile.tar ⎪",
469 ReadNow => 1,
470 Filename => "somefile.tgz");
471 $msg->add(From => "laughing@all.of.us");
472 $msg->add(To => "scarlett@fiddle.dee.de");
473 $msg->add(Subject => "A gzipp'ed tar file");
474 Setting/getting headers and attributes
476 add TAG,VALUE
478 Instance method. Add field TAG with the given VALUE to the end of
479 the header. The TAG will be converted to all-lowercase, and the
480 VALUE will be made "safe" (returns will be given a trailing space).
481 Beware: any MIME fields you "add" will override any MIME attributes
483 I have when it comes time to output those fields. Normally, you
484 will use this method to add non-MIME fields:
485 $msg->add("Subject" => "Hi there!");
487 Giving VALUE as an arrayref will cause all those values to be
489 added. This is only useful for special multiple-valued fields like
490 "Received":
491 $msg->add("Received" => ["here", "there", "everywhere"]
493 Giving VALUE as the empty string adds an invisible placeholder to
495 the header, which can be used to suppress the output of the "Con‐
496 tent-*" fields or the special "MIME-Version" field. When sup‐
497 pressing fields, you should use replace() instead of add():
498 $msg->replace("Content-disposition" => "");
500 Note: add() is probably going to be more efficient than
502 "replace()", so you're better off using it for most applications if
503 you are certain that you don't need to delete() the field first.
504 Note: the name comes from Mail::Header.
506 attr ATTR,[VALUE]
508 Instance method. Set MIME attribute ATTR to the string VALUE.
509 ATTR is converted to all-lowercase. This method is normally used
510 to set/get MIME attributes:
511 $msg->attr("content-type" => "text/html");
513 $msg->attr("content-type.charset" => "US-ASCII");
514 $msg->attr("content-type.name" => "homepage.html");
515 This would cause the final output to look something like this:
517 Content-type: text/html; charset=US-ASCII; name="homepage.html"
519 Note that the special empty sub-field tag indicates the anonymous
521 first sub-field.
522 Giving VALUE as undefined will cause the contents of the named sub‐
524 field to be deleted.
525 Supplying no VALUE argument just returns the attribute's value:
527 $type = $msg->attr("content-type"); ### returns "text/html"
529 $name = $msg->attr("content-type.name"); ### returns "homepage.html"
530 delete TAG
532 Instance method. Delete field TAG with the given VALUE to the end
533 of the header. The TAG will be converted to all-lowercase.
534 $msg->delete("Subject");
536 Note: the name comes from Mail::Header.
538 field_order FIELD,...FIELD
540 Class/instance method. Change the order in which header fields are
541 output for this object:
542 $msg->field_order('from', 'to', 'content-type', 'subject');
544 When used as a class method, changes the default settings for all
546 objects:
547 MIME::Lite->field_order('from', 'to', 'content-type', 'subject');
549 Case does not matter: all field names will be coerced to lowercase.
551 In either case, supply the empty array to restore the default
552 ordering.
553 fields
555 Instance method. Return the full header for the object, as a ref
556 to an array of "[TAG, VALUE]" pairs, where each TAG is all-lower‐
557 case. Note that any fields the user has explicitly set will over‐
558 ride the corresponding MIME fields that we would otherwise gener‐
559 ate. So, don't say...
560 $msg->set("Content-type" => "text/html; charset=US-ASCII");
562 unless you want the above value to override the "Content-type" MIME
564 field that we would normally generate.
565 Note: I called this "fields" because the header() method of
567 Mail::Header returns something different, but similar enough to be
568 confusing.
569 You can change the order of the fields: see "field_order". You
571 really shouldn't need to do this, but some people have to deal with
572 broken mailers.
573 filename [FILENAME]
575 Instance method. Set the filename which this data will be reported
576 as. This actually sets both "standard" attributes.
577 With no argument, returns the filename as dictated by the con‐
579 tent-disposition.
580 get TAG,[INDEX]
582 Instance method. Get the contents of field TAG, which might have
583 been set with set() or replace(). Returns the text of the field.
584 $ml->get('Subject', 0);
586 If the optional 0-based INDEX is given, then we return the INDEX'th
588 occurence of field TAG. Otherwise, we look at the context: In a
589 scalar context, only the first (0th) occurence of the field is
590 returned; in an array context, all occurences are returned.
591 Warning: this should only be used with non-MIME fields. Behavior
593 with MIME fields is TBD, and will raise an exception for now.
594 get_length
596 Instance method. Recompute the content length for the message if
597 the process is trivial, setting the "content-length" attribute as a
598 side-effect:
599 $msg->get_length;
601 Returns the length, or undefined if not set.
603 Note: the content length can be difficult to compute, since it
605 involves assembling the entire encoded body and taking the length
606 of it (which, in the case of multipart messages, means freezing all
607 the sub-parts, etc.).
608 This method only sets the content length to a defined value if the
610 message is a singlepart with "binary" encoding, and the body is
611 available either in-core or as a simple file. Otherwise, the con‐
612 tent length is set to the undefined value.
613 Since content-length is not a standard MIME field anyway (that's
615 right, kids: it's not in the MIME RFCs, it's an HTTP thing), this
616 seems pretty fair.
617 parts
619 Instance method. Return the parts of this entity, and this entity
620 only. Returns empty array if this entity has no parts.
621 This is not recursive! Parts can have sub-parts; use parts_DFS()
623 to get everything.
624 parts_DFS
626 Instance method. Return the list of all MIME::Lite objects
627 included in the entity, starting with the entity itself, in depth-
628 first-search order. If this object has no parts, it alone will be
629 returned.
630 preamble [TEXT]
632 Instance method. Get/set the preamble string, assuming that this
633 object has subparts. Set it to undef for the default string.
634 replace TAG,VALUE
636 Instance method. Delete all occurences of fields named TAG, and
637 add a new field with the given VALUE. TAG is converted to all-low‐
638 ercase.
639 Beware the special MIME fields (MIME-version, Content-*): if you
641 "replace" a MIME field, the replacement text will override the
642 actual MIME attributes when it comes time to output that field. So
643 normally you use attr() to change MIME fields and add()/replace()
644 to change non-MIME fields:
645 $msg->replace("Subject" => "Hi there!");
647 Giving VALUE as the empty string will effectively prevent that
649 field from being output. This is the correct way to suppress the
650 special MIME fields:
651 $msg->replace("Content-disposition" => "");
653 Giving VALUE as undefined will just cause all explicit values for
655 TAG to be deleted, without having any new values added.
656 Note: the name of this method comes from Mail::Header.
658 scrub
660 Instance method. This is Alpha code. If you use it, please let me
661 know how it goes. Recursively goes through the "parts" tree of
662 this message and tries to find MIME attributes that can be removed.
663 With an array argument, removes exactly those attributes; e.g.:
664 $msg->scrub(['content-disposition', 'content-length']);
666 Is the same as recursively doing:
668 $msg->replace('Content-disposition' => '');
670 $msg->replace('Content-length' => '');
671 Setting/getting message data
673 binmode [OVERRIDE]
675 Instance method. With no argument, returns whether or not it
676 thinks that the data (as given by the "Path" argument of "build()")
677 should be read using binmode() (for example, when "read_now()" is
678 invoked).
679 The default behavior is that any content type other than "text/*"
681 or "message/*" is binmode'd; this should in general work fine.
682 With a defined argument, this method sets an explicit "override"
684 value. An undefined argument unsets the override. The new current
685 value is returned.
686 data [DATA]
688 Instance method. Get/set the literal DATA of the message. The
689 DATA may be either a scalar, or a reference to an array of scalars
690 (which will simply be joined).
691 Warning: setting the data causes the "content-length" attribute to
693 be recomputed (possibly to nothing).
694 fh [FILEHANDLE]
696 Instance method. Get/set the FILEHANDLE which contains the message
697 data.
698 Takes a filehandle as an input and stores it in the object. This
700 routine is similar to path(); one important difference is that no
701 attempt is made to set the content length.
702 path [PATH]
704 Instance method. Get/set the PATH to the message data.
705 Warning: setting the path recomputes any existing "content-length"
707 field, and re-sets the "filename" (to the last element of the path
708 if it looks like a simple path, and to nothing if not).
709 resetfh [FILEHANDLE]
711 Instance method. Set the current position of the filehandle back
712 to the beginning. Only applies if you used "FH" in build() or
713 attach() for this message.
714 Returns false if unable to reset the filehandle (since not all
716 filehandles are seekable).
717 read_now
719 Instance method. Forces data from the path/filehandle (as speci‐
720 fied by "build()") to be read into core immediately, just as though
721 you had given it literally with the "Data" keyword.
722 Note that the in-core data will always be used if available.
724 Be aware that everything is slurped into a giant scalar: you may
726 not want to use this if sending tar files! The benefit of not
727 reading in the data is that very large files can be handled by this
728 module if left on disk until the message is output via "print()" or
729 "print_body()".
730 sign PARAMHASH
732 Instance method. Sign the message. This forces the message to be
733 read into core, after which the signature is appended to it.
734 Data
736 As in "build()": the literal signature data. Can be either a
737 scalar or a ref to an array of scalars.
738 Path
740 As in "build()": the path to the file.
741 If no arguments are given, the default is:
743 Path => "$ENV{HOME}/.signature"
745 The content-length is recomputed.
747 verify_data
749 Instance method. Verify that all "paths" to attached data exist,
750 recursively. It might be a good idea for you to do this before a
751 print(), to prevent accidental partial output if a file might be
752 missing. Raises exception if any path is not readable.
753 Output
755 print [OUTHANDLE]
757 Instance method. Print the message to the given output handle, or
758 to the currently-selected filehandle if none was given.
759 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
761 any object that responds to a print() message.
762 print_body [OUTHANDLE]
764 Instance method. Print the body of a message to the given output
765 handle, or to the currently-selected filehandle if none was given.
766 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
768 any object that responds to a print() message.
769 Fatal exception raised if unable to open any of the input files, or
771 if a part contains no data, or if an unsupported encoding is
772 encountered.
773 print_header [OUTHANDLE]
775 Instance method. Print the header of the message to the given out‐
776 put handle, or to the currently-selected filehandle if none was
777 given.
778 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
780 any object that responds to a print() message.
781 as_string
783 Instance method. Return the entire message as a string, with a
784 header and an encoded body.
785 body_as_string
787 Instance method. Return the encoded body as a string. This is the
788 portion after the header and the blank line.
789 Note: actually prepares the body by "printing" to a scalar. Proof
791 that you can hand the "print*()" methods any blessed object that
792 responds to a "print()" message.
793 header_as_string
795 Instance method. Return the header as a string.
796 Sending
798 send
800 send HOW, HOWARGS...
801 Class/instance method. This is the principal method for sending
802 mail, and for configuring how mail will be sent.
803 As a class method with a HOW argument and optional HOWARGS, it sets
805 the default sending mechanism that the no-argument instance method
806 will use. The HOW is a facility name (see below), and the HOWARGS
807 is interpreted by the facilty. The class method returns the previ‐
808 ous HOW and HOWARGS as an array.
809 MIME::Lite->send('sendmail', "d:\\programs\\sendmail.exe");
811 ...
812 $msg = MIME::Lite->new(...);
813 $msg->send;
814 As an instance method with arguments (a HOW argument and optional
816 HOWARGS), sends the message in the requested manner; e.g.:
817 $msg->send('sendmail', "d:\\programs\\sendmail.exe");
819 As an instance method with no arguments, sends the message by the
821 default mechanism set up by the class method. Returns whatever the
822 mail-handling routine returns: this should be true on success,
823 false/exception on error:
824 $msg = MIME::Lite->new(From=>...);
826 $msg->send ⎪⎪ die "you DON'T have mail!";
827 On Unix systems (at least), the default setting is equivalent to:
829 MIME::Lite->send("sendmail", "/usr/lib/sendmail -t -oi -oem");
831 There are three facilities:
833 "sendmail", ARGS...
835 Send a message by piping it into the "sendmail" command. Uses
836 the send_by_sendmail() method, giving it the ARGS. This usage
837 implements (and deprecates) the "sendmail()" method.
838 "smtp", [HOSTNAME]
840 Send a message by SMTP, using optional HOSTNAME as SMTP-sending
841 host. Uses the send_by_smtp() method.
842 "sub", \&SUBREF, ARGS...
844 Sends a message MSG by invoking the subroutine SUBREF of your
845 choosing, with MSG as the first argument, and ARGS following.
846 For example: let's say you're on an OS which lacks the usual Unix
848 "sendmail" facility, but you've installed something a lot like it,
849 and you need to configure your Perl script to use this "send‐
850 mail.exe" program. Do this following in your script's setup:
851 MIME::Lite->send('sendmail', "d:\\programs\\sendmail.exe");
853 Then, whenever you need to send a message $msg, just say:
855 $msg->send;
857 That's it. Now, if you ever move your script to a Unix box, all
859 you need to do is change that line in the setup and you're done.
860 All of your $msg->send invocations will work as expected.
861 send_by_sendmail SENDMAILCMD
863 send_by_sendmail PARAM=>VALUE, ...
864 Instance method. Send message via an external "sendmail" program
865 (this will probably only work out-of-the-box on Unix systems).
866 Returns true on success, false or exception on error.
868 You can specify the program and all its arguments by giving a sin‐
870 gle string, SENDMAILCMD. Nothing fancy is done; the message is
871 simply piped in.
872 However, if your needs are a little more advanced, you can specify
874 zero or more of the following PARAM/VALUE pairs; a Unix-style,
875 taint-safe "sendmail" command will be constructed for you:
876 Sendmail
878 Full path to the program to use. Default is "/usr/lib/send‐
879 mail".
880 BaseArgs
882 Ref to the basic array of arguments we start with. Default is
883 "["-t", "-oi", "-oem"]".
884 SetSender
886 Unless this is explicitly given as false, we attempt to auto‐
887 matically set the "-f" argument to the first address that can
888 be extracted from the "From:" field of the message (if there is
889 one).
890 What is the -f, and why do we use it? Suppose we did not use
892 "-f", and you gave an explicit "From:" field in your message:
893 in this case, the sendmail "envelope" would indicate the real
894 user your process was running under, as a way of preventing
895 mail forgery. Using the "-f" switch causes the sender to be
896 set in the envelope as well.
897 So when would I NOT want to use it? If sendmail doesn't regard
899 you as a "trusted" user, it will permit the "-f" but also add
900 an "X-Authentication-Warning" header to the message to indicate
901 a forged envelope. To avoid this, you can either (1) have Set‐
902 Sender be false, or (2) make yourself a trusted user by adding
903 a "T" configuration
904 command to your sendmail.cf file
905 (e.g.: "Teryq" if the script is running as user "eryq").
906 FromSender
908 If defined, this is identical to setting SetSender to true,
909 except that instead of looking at the "From:" field we use the
910 address given by this option. Thus:
911 FromSender => 'me@myhost.com'
913 send_by_smtp ARGS...
915 Instance method. Send message via SMTP, using Net::SMTP. The
916 optional ARGS are sent into Net::SMTP::new(): usually, these are
917 MAILHOST, OPTION=>VALUE, ...
919 Note that the list of recipients is taken from the "To", "Cc" and
921 "Bcc" fields.
922 Returns true on success, false or exception on error.
924 sendmail COMMAND...
926 Class method, DEPRECATED. Declare the sender to be "sendmail", and
927 set up the "sendmail" command. You should use send() instead.
928 Miscellaneous
930 quiet ONOFF
932 Class method. Suppress/unsuppress all warnings coming from this
933 module.
934 MIME::Lite->quiet(1); ### I know what I'm doing
936 I recommend that you include that comment as well. And while you
938 type it, say it out loud: if it doesn't feel right, then maybe you
939 should reconsider the whole line. ";-)"
940
942 How do I prevent "Content" headers from showing up in my mail reader?
943 Apparently, some people are using mail readers which display the MIME
945 headers like "Content-disposition", and they want MIME::Lite not to
946 generate them "because they look ugly".
947 Sigh.
949 Y'know, kids, those headers aren't just there for cosmetic purposes.
951 They help ensure that the message is understood correctly by mail read‐
952 ers. But okay, you asked for it, you got it... here's how you can
953 suppress the standard MIME headers. Before you send the message, do
954 this:
955 $msg->scrub;
957 You can scrub() any part of a multipart message independently; just be
959 aware that it works recursively. Before you scrub, note the rules that
960 I follow:
961 Content-type
963 You can safely scrub the "content-type" attribute if, and only if,
964 the part is of type "text/plain" with charset "us-ascii".
965 Content-transfer-encoding
967 You can safely scrub the "content-transfer-encoding" attribute if,
968 and only if, the part uses "7bit", "8bit", or "binary" encoding.
969 You are far better off doing this if your lines are under 1000
970 characters. Generally, that means you can scrub it for plain text,
971 and you can not scrub this for images, etc.
972 Content-disposition
974 You can safely scrub the "content-disposition" attribute if you
975 trust the mail reader to do the right thing when it decides whether
976 to show an attachment inline or as a link. Be aware that scrubbing
977 both the content-disposition and the content-type means that there
978 is no way to "recommend" a filename for the attachment!
979 Note: there are reports of brain-dead MUAs out there that do the
981 wrong thing if you provide the content-disposition. If your
982 attachments keep showing up inline or vice-versa, try scrubbing
983 this attribute.
984 Content-length
986 You can always scrub "content-length" safely.
987 How do I give my attachment a [different] recommended filename?
989 By using the Filename option (which is different from Path!):
991 $msg->attach(Type => "image/gif",
993 Path => "/here/is/the/real/file.GIF",
994 Filename => "logo.gif");
995 You should not put path information in the Filename.
997 Benign limitations
999 This is "lite", after all...
1001 · There's no parsing. Get MIME-tools if you need to parse MIME mes‐
1003 sages.
1004 · MIME::Lite messages are currently not interchangeable with either
1006 Mail::Internet or MIME::Entity objects. This is a completely sepa‐
1007 rate module.
1008 · A content-length field is only inserted if the encoding is binary,
1010 the message is a singlepart, and all the document data is available
1011 at "build()" time by virtue of residing in a simple path, or
1012 in-core. Since content-length is not a standard MIME field anyway
1013 (that's right, kids: it's not in the MIME RFCs, it's an HTTP
1014 thing), this seems pretty fair.
1015 · MIME::Lite alone cannot help you lose weight. You must supplement
1017 your use of MIME::Lite with a healthy diet and exercise.
1018 Cheap and easy mailing
1020 I thought putting in a default "sendmail" invocation wasn't too bad an
1022 idea, since a lot of Perlers are on UNIX systems. The out-of-the-box
1023 configuration is:
1024 MIME::Lite->send('sendmail', "/usr/lib/sendmail -t -oi -oem");
1026 By the way, these arguments to sendmail are:
1028 -t Scan message for To:, Cc:, Bcc:, etc.
1030 -oi Do NOT treat a single "." on a line as a message terminator.
1032 As in, "-oi vey, it truncated my message... why?!"
1033 -oem On error, mail back the message (I assume to the
1035 appropriate address, given in the header).
1036 When mail returns, circle is complete. Jai Guru Deva -oem.
1037 Note that these are the same arguments you get if you configure to use
1039 the smarter, taint-safe mailing:
1040 MIME::Lite->send('sendmail');
1042 If you get "X-Authentication-Warning" headers from this, you can forgo
1044 diddling with the envelope by instead specifying:
1045 MIME::Lite->send('sendmail', SetSender=>0);
1047 And, if you're not on a Unix system, or if you'd just rather send mail
1049 some other way, there's always:
1050 MIME::Lite->send('smtp', "smtp.myisp.net");
1052 Or you can set up your own subroutine to call. In any case, check out
1054 the send() method.
1055
1057 Good-vs-bad email addresses with send_by_smtp()
1058 If using send_by_smtp(), be aware that you are forcing MIME::Lite to
1060 extract email addresses out of a possible list provided in the "To:",
1061 "Cc:", and "Bcc:" fields. This is tricky stuff, and as such only the
1062 following sorts of addresses will work reliably:
1063 username
1065 full.name@some.host.com
1066 "Name, Full" <full.name@some.host.com>
1067 This last form is discouraged because SMTP must be able to get at the
1069 name or name@domain portion.
1070 Disclaimer: MIME::Lite was never intended to be a Mail User Agent, so
1072 please don't expect a full implementation of RFC-822. Restrict your‐
1073 self to the common forms of Internet addresses described herein, and
1074 you should be fine. If this is not feasible, then consider using
1075 MIME::Lite to prepare your message only, and using Net::SMTP explicitly
1076 to send your message.
1077 Formatting of headers delayed until print()
1079 This class treats a MIME header in the most abstract sense, as being a
1081 collection of high-level attributes. The actual RFC-822-style header
1082 fields are not constructed until it's time to actually print the darn
1083 thing.
1084 Encoding of data delayed until print()
1086 When you specify message bodies (in build() or attach()) -- whether by
1088 FH, Data, or Path -- be warned that we don't attempt to open files,
1089 read filehandles, or encode the data until print() is invoked.
1090 In the past, this created some confusion for users of sendmail who gave
1092 the wrong path to an attachment body, since enough of the print() would
1093 succeed to get the initial part of the message out. Nowadays,
1094 $AUTO_VERIFY is used to spot-check the Paths given before the mail
1095 facility is employed. A whisker slower, but tons safer.
1096 Note that if you give a message body via FH, and try to print() a mes‐
1098 sage twice, the second print() will not do the right thing unless you
1099 explicitly rewind the filehandle.
1100 You can get past these difficulties by using the ReadNow option, pro‐
1102 vided that you have enough memory to handle your messages.
1103 MIME attributes are separate from header fields!
1105 Important: the MIME attributes are stored and manipulated separately
1107 from the message header fields; when it comes time to print the header
1108 out, any explicitly-given header fields override the ones that would be
1109 created from the MIME attributes. That means that this:
1110 ### DANGER ### DANGER ### DANGER ### DANGER ### DANGER ###
1112 $msg->add("Content-type", "text/html; charset=US-ASCII");
1113 will set the exact "Content-type" field in the header I write, regard‐
1115 less of what the actual MIME attributes are.
1116 This feature is for experienced users only, as an escape hatch in case
1118 the code that normally formats MIME header fields isn't doing what you
1119 need. And, like any escape hatch, it's got an alarm on it: MIME::Lite
1120 will warn you if you attempt to "set()" or "replace()" any MIME header
1121 field. Use "attr()" instead.
1122 Beware of lines consisting of a single dot
1124 Julian Haight noted that MIME::Lite allows you to compose messages with
1126 lines in the body consisting of a single ".". This is true: it should
1127 be completely harmless so long as "sendmail" is used with the -oi
1128 option (see "Cheap and easy mailing").
1129 However, I don't know if using Net::SMTP to transfer such a message is
1131 equally safe. Feedback is welcomed.
1132 My perspective: I don't want to magically diddle with a user's message
1134 unless absolutely positively necessary. Some users may want to send
1135 files with "." alone on a line; my well-meaning tinkering could seri‐
1136 ously harm them.
1137 Infinite loops may mean tainted data!
1139 Stefan Sautter noticed a bug in 2.106 where a m//gc match was failing
1141 due to tainted data, leading to an infinite loop inside MIME::Lite.
1142 I am attempting to correct for this, but be advised that my fix will
1144 silently untaint the data (given the context in which the problem
1145 occurs, this should be benign: I've labelled the source code with
1146 UNTAINT comments for the curious).
1147 So: don't depend on taint-checking to save you from outputting tainted
1149 data in a message.
1150 Don't tweak the global configuration
1152 Global configuration variables are bad, and should go away. Until they
1154 do, please follow the hints with each setting on how not to change it.
1155
1157 Content types
1158 The "Type" parameter of "build()" is a content type. This is the
1160 actual type of data you are sending. Generally this is a string of the
1161 form "majortype/minortype".
1162 Here are the major MIME types. A more-comprehensive listing may be
1164 found in RFC-2046.
1165 application
1167 Data which does not fit in any of the other categories, particu‐
1168 larly data to be processed by some type of application program.
1169 "application/octet-stream", "application/gzip", "application/post‐
1170 script"...
1171 audio
1173 Audio data. "audio/basic"...
1174 image
1176 Graphics data. "image/gif", "image/jpeg"...
1177 message
1179 A message, usually another mail or MIME message. "mes‐
1180 sage/rfc822"...
1181 multipart
1183 A message containing other messages. "multipart/mixed", "multi‐
1184 part/alternative"...
1185 text
1187 Textual data, meant for humans to read. "text/plain",
1188 "text/html"...
1189 video
1191 Video or video+audio data. "video/mpeg"...
1192 Content transfer encodings
1194 The "Encoding" parameter of "build()". This is how the message body is
1196 packaged up for safe transit.
1197 Here are the 5 major MIME encodings. A more-comprehensive listing may
1199 be found in RFC-2045.
1200 7bit
1202 Basically, no real encoding is done. However, this label guaran‐
1203 tees that no 8-bit characters are present, and that lines do not
1204 exceed 1000 characters in length.
1205 8bit
1207 Basically, no real encoding is done. The message might contain
1208 8-bit characters, but this encoding guarantees that lines do not
1209 exceed 1000 characters in length.
1210 binary
1212 No encoding is done at all. Message might contain 8-bit charac‐
1213 ters, and lines might be longer than 1000 characters long.
1214 The most liberal, and the least likely to get through mail gate‐
1216 ways. Use sparingly, or (better yet) not at all.
1217 base64
1219 Like "uuencode", but very well-defined. This is how you should
1220 send essentially binary information (tar files, GIFs, JPEGs, etc.).
1221 quoted-printable
1223 Useful for encoding messages which are textual in nature, yet which
1224 contain non-ASCII characters (e.g., Latin-1, Latin-2, or any other
1225 8-bit alphabet).
1226
1228 MIME::Lite works nicely with other certain other modules if they are
1229 present. Good to have installed is the latest MIME::Types,
1230 Mail::Address, MIME::Base64, MIME::QuotedPrint.
1231 If they aren't present then some functionality won't work, and other
1233 features wont be as efficient or up to date as they could be. Neverthe‐
1234 less they are optional extras.
1235
1237 MIME::Lite comes with a number of extra files in the distribution bun‐
1238 dle. This includes examples, and utility modules that you can use to
1239 get yourself started with the module.
1240 The ./examples directory contains a number of snippets in prepared
1242 form, generally they are documented, but they should be easy to under‐
1243 stand.
1244 The ./contrib directory contains a companion/tool modules that come
1246 bundled with MIME::Lite, they dont get installed by default. Please
1247 review the POD they come with.
1248
1250 The whole reason that version 3.0 was released was to ensure that
1251 MIME::Lite is up to date and patched. If you find an issue please
1252 report it.
1253 As far as I know MIME::Lite doesnt currently have any serious bugs, but
1255 my usage is hardly comprehensive.
1256 Having said that there are a number of open issues for me, mostly
1258 caused by the progress in the community as whole since Eryq last
1259 released. The tests are based around an interesting but non standard
1260 test framework. I'd like to change it over to using Test::More.
1261 Should tests fail please review the ./testout directory, and in any bug
1263 reports please include the output of the relevent file. This is the
1264 only redeeming feature of not using Test::More that I can see.
1265 Bug fixes / Patches / Contribution are welcome, however I probably
1267 won't apply them unless they also have an associated test. This means
1268 that if I dont have the time to write the test the patch wont get
1269 applied, so please, include tests for any patches you provide.
1270
1272 Version: 3.01 (Maintenance release and a new caretaker!)
1273
1275 Moved to ./changes.pod
1276
1278 Copyright (c) 1997 by Eryq.
1279 Copyright (c) 1998 by ZeeGee Software Inc.
1280 Copyright (c) 2003 Yves Orton. demerphq (at) hotmail.com.
1281 All rights reserved. This program is free software; you can redis‐
1283 tribute it and/or modify it under the same terms as Perl itself.
1284 This software comes with NO WARRANTY of any kind. See the COPYING file
1286 in the distribution for details.
1287
1289 For some reason, the US FDA says that this is now required by law on
1290 any products that bear the name "Lite"...
1291 Version 3.0 is now new and improved! The distribution is now 30%
1293 smaller!
1294 MIME::Lite ⎪
1296 ------------------------------------------------------------
1297 Serving size: ⎪ 1 module
1298 Servings per container: ⎪ 1
1299 Calories: ⎪ 0
1300 Fat: ⎪ 0g
1301 Saturated Fat: ⎪ 0g
1302 Warning: for consumption by hardware only! May produce indigestion in
1304 humans if taken internally.
1305
1307 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc.
1308 (http://www.zeegee.com).
1309 Go to http://www.zeegee.com for the latest downloads and on-line docu‐
1311 mentation for this module. Enjoy.
1312 Patches And Maintenance by Yves Orton demerphq@hotmail.com and many
1314 others. Consult ./changes.pod
1315perl v5.8.8 2003-04-24 MIME::Lite(3)