1MIME::Lite(3) User Contributed Perl Documentation MIME::Lite(3)
2
6 MIME::Lite - low-calorie MIME generator
7
9 Create and send using the default send method for your OS a single-part
10 message:
11 use MIME::Lite;
13 ### 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 $msg->send; # send via default
24 Create a multipart message (i.e., one with attachments) and send it
26 SMTP
27 ### Create a new multipart message:
29 $msg = MIME::Lite->new(
30 From => 'me@myhost.com',
31 To => 'you@yourhost.com',
32 Cc => 'some@other.com, some@more.com',
33 Subject => 'A message with 2 parts...',
34 Type => 'multipart/mixed'
35 );
36 ### Add parts (each "attach" has same arguments as "new"):
38 $msg->attach(
39 Type => 'TEXT',
40 Data => "Here's the GIF file you wanted"
41 );
42 $msg->attach(
43 Type => 'image/gif',
44 Path => 'aaa000123.gif',
45 Filename => 'logo.gif',
46 Disposition => 'attachment'
47 );
48 ### use Net:SMTP to do the sending
49 $msg->send('smtp','some.host', Debug=>1 );
50 Output a message:
52 ### Format as a string:
54 $str = $msg->as_string;
55 ### Print to a filehandle (say, a "sendmail" stream):
57 $msg->print(\*SENDMAIL);
58 Send a message:
60 ### Send in the "best" way (the default is to use "sendmail"):
62 $msg->send;
63 ### Send a specific way:
64 $msg->send('type',@args);
65 Specify default send method:
67 MIME::Lite->send('smtp','some.host',Debug=>0);
69 with authentication
71 MIME::Lite->send('smtp','some.host',
73 AuthUser=>$user, AuthPass=>$pass);
74
76 In the never-ending quest for great taste with fewer calories, we
77 proudly present: MIME::Lite.
78 MIME::Lite is intended as a simple, standalone module for generating
80 (not parsing!) MIME messages... specifically, it allows you to output a
81 simple, decent single- or multi-part message with text or binary
82 attachments. It does not require that you have the Mail:: or MIME::
83 modules installed, but will work with them if they are.
84 You can specify each message part as either the literal data itself (in
86 a scalar or array), or as a string which can be given to open() to get
87 a readable filehandle (e.g., "<filename" or "somecommand|").
88 You don't need to worry about encoding your message data: this module
90 will do that for you. It handles the 5 standard MIME encodings.
91
93 Create a simple message containing just text
94 $msg = MIME::Lite->new(
95 From =>'me@myhost.com',
96 To =>'you@yourhost.com',
97 Cc =>'some@other.com, some@more.com',
98 Subject =>'Helloooooo, nurse!',
99 Data =>"How's it goin', eh?"
100 );
101 Create a simple message containing just an image
103 $msg = MIME::Lite->new(
104 From =>'me@myhost.com',
105 To =>'you@yourhost.com',
106 Cc =>'some@other.com, some@more.com',
107 Subject =>'Helloooooo, nurse!',
108 Type =>'image/gif',
109 Encoding =>'base64',
110 Path =>'hellonurse.gif'
111 );
112 Create a multipart message
114 ### Create the multipart "container":
115 $msg = MIME::Lite->new(
116 From =>'me@myhost.com',
117 To =>'you@yourhost.com',
118 Cc =>'some@other.com, some@more.com',
119 Subject =>'A message with 2 parts...',
120 Type =>'multipart/mixed'
121 );
122 ### Add the text message part:
124 ### (Note that "attach" has same arguments as "new"):
125 $msg->attach(
126 Type =>'TEXT',
127 Data =>"Here's the GIF file you wanted"
128 );
129 ### Add the image part:
131 $msg->attach(
132 Type =>'image/gif',
133 Path =>'aaa000123.gif',
134 Filename =>'logo.gif',
135 Disposition => 'attachment'
136 );
137 Attach a GIF to a text message
139 This will create a multipart message exactly as above, but using the
140 "attach to singlepart" hack:
141 ### Start with a simple text message:
143 $msg = MIME::Lite->new(
144 From =>'me@myhost.com',
145 To =>'you@yourhost.com',
146 Cc =>'some@other.com, some@more.com',
147 Subject =>'A message with 2 parts...',
148 Type =>'TEXT',
149 Data =>"Here's the GIF file you wanted"
150 );
151 ### Attach a part... the make the message a multipart automatically:
153 $msg->attach(
154 Type =>'image/gif',
155 Path =>'aaa000123.gif',
156 Filename =>'logo.gif'
157 );
158 Attach a pre-prepared part to a message
160 ### Create a standalone part:
161 $part = MIME::Lite->new(
162 Type =>'text/html',
163 Data =>'<H1>Hello</H1>',
164 );
165 $part->attr('content-type.charset' => 'UTF-8');
166 $part->add('X-Comment' => 'A message for you');
167 ### Attach it to any message:
169 $msg->attach($part);
170 Print a message to a filehandle
172 ### Write it to a filehandle:
173 $msg->print(\*STDOUT);
174 ### Write just the header:
176 $msg->print_header(\*STDOUT);
177 ### Write just the encoded body:
179 $msg->print_body(\*STDOUT);
180 Print a message into a string
182 ### Get entire message as a string:
183 $str = $msg->as_string;
184 ### Get just the header:
186 $str = $msg->header_as_string;
187 ### Get just the encoded body:
189 $str = $msg->body_as_string;
190 Send a message
192 ### Send in the "best" way (the default is to use "sendmail"):
193 $msg->send;
194 Send an HTML document... with images included!
196 $msg = MIME::Lite->new(
197 To =>'you@yourhost.com',
198 Subject =>'HTML with in-line images!',
199 Type =>'multipart/related'
200 );
201 $msg->attach(
202 Type => 'text/html',
203 Data => qq{
204 <body>
205 Here's <i>my</i> image:
206 <img src="cid:myimage.gif">
207 </body>
208 },
209 );
210 $msg->attach(
211 Type => 'image/gif',
212 Id => 'myimage.gif',
213 Path => '/path/to/somefile.gif',
214 );
215 $msg->send();
216 Change how messages are sent
218 ### Do something like this in your 'main':
219 if ($I_DONT_HAVE_SENDMAIL) {
220 MIME::Lite->send('smtp', $host, Timeout=>60
221 AuthUser=>$user, AuthPass=>$pass);
222 }
223 ### Now this will do the right thing:
225 $msg->send; ### will now use Net::SMTP as shown above
226
228 Global configuration
229 To alter the way the entire module behaves, you have the following
230 methods/options:
231 MIME::Lite->field_order()
233 When used as a classmethod, this changes the default order in which
234 headers are output for all messages. However, please consider
235 using the instance method variant instead, so you won't stomp on
236 other message senders in the same application.
237 MIME::Lite->quiet()
239 This classmethod can be used to suppress/unsuppress all warnings
240 coming from this module.
241 MIME::Lite->send()
243 When used as a classmethod, this can be used to specify a different
244 default mechanism for sending message. The initial default is:
245 MIME::Lite->send("sendmail", "/usr/lib/sendmail -t -oi -oem");
247 However, you should consider the similar but smarter and taint-safe
249 variant:
250 MIME::Lite->send("sendmail");
252 Or, for non-Unix users:
254 MIME::Lite->send("smtp");
256 $MIME::Lite::AUTO_CC
258 If true, automatically send to the Cc/Bcc addresses for
259 send_by_smtp(). Default is true.
260 $MIME::Lite::AUTO_CONTENT_TYPE
262 If true, try to automatically choose the content type from the file
263 name in "new()"/"build()". In other words, setting this true
264 changes the default "Type" from "TEXT" to "AUTO".
265 Default is false, since we must maintain backwards-compatibility
267 with prior behavior. Please consider keeping it false, and just
268 using Type 'AUTO' when you build() or attach().
269 $MIME::Lite::AUTO_ENCODE
271 If true, automatically choose the encoding from the content type.
272 Default is true.
273 $MIME::Lite::AUTO_VERIFY
275 If true, check paths to attachments right before printing, raising
276 an exception if any path is unreadable. Default is true.
277 $MIME::Lite::PARANOID
279 If true, we won't attempt to use MIME::Base64, MIME::QuotedPrint,
280 or MIME::Types, even if they're available. Default is false.
281 Please consider keeping it false, and trusting these other packages
282 to do the right thing.
283 Construction
285 new [PARAMHASH]
286 Class method, constructor. Create a new message object.
287 If any arguments are given, they are passed into "build()";
289 otherwise, just the empty object is created.
290 attach PART
292 attach PARAMHASH...
293 Instance method. Add a new part to this message, and return the
294 new part.
295 If you supply a single PART argument, it will be regarded as a
297 MIME::Lite object to be attached. Otherwise, this method assumes
298 that you are giving in the pairs of a PARAMHASH which will be sent
299 into "new()" to create the new part.
300 One of the possibly-quite-useful hacks thrown into this is the
302 "attach-to-singlepart" hack: if you attempt to attach a part (let's
303 call it "part 1") to a message that doesn't have a content-type of
304 "multipart" or "message", the following happens:
305 · A new part (call it "part 0") is made.
307 · The MIME attributes and data (but not the other headers) are
309 cut from the "self" message, and pasted into "part 0".
310 · The "self" is turned into a "multipart/mixed" message.
312 · The new "part 0" is added to the "self", and then "part 1" is
314 added.
315 One of the nice side-effects is that you can create a text message
317 and then add zero or more attachments to it, much in the same way
318 that a user agent like Netscape allows you to do.
319 build [PARAMHASH]
321 Class/instance method, initializer. Create (or initialize) a MIME
322 message object. Normally, you'll use the following keys in
323 PARAMHASH:
324 * Data, FH, or Path (either one of these, or none if multipart)
326 * Type (e.g., "image/jpeg")
327 * From, To, and Subject (if this is the "top level" of a message)
328 The PARAMHASH can contain the following keys:
330 (fieldname)
332 Any field you want placed in the message header, taken from the
333 standard list of header fields (you don't need to worry about
334 case):
335 Approved Encrypted Received Sender
337 Bcc From References Subject
338 Cc Keywords Reply-To To
339 Comments Message-ID Resent-* X-*
340 Content-* MIME-Version Return-Path
341 Date Organization
342 To give experienced users some veto power, these fields will be
344 set after the ones I set... so be careful: don't set any MIME
345 fields (like "Content-type") unless you know what you're doing!
346 To specify a fieldname that's not in the above list, even one
348 that's identical to an option below, just give it with a
349 trailing ":", like "My-field:". When in doubt, that always
350 signals a mail field (and it sort of looks like one too).
351 Data
353 Alternative to "Path" or "FH". The actual message data. This
354 may be a scalar or a ref to an array of strings; if the latter,
355 the message consists of a simple concatenation of all the
356 strings in the array.
357 Datestamp
359 Optional. If given true (or omitted), we force the creation of
360 a "Date:" field stamped with the current date/time if this is a
361 top-level message. You may want this if using send_by_smtp().
362 If you don't want this to be done, either provide your own Date
363 or explicitly set this to false.
364 Disposition
366 Optional. The content disposition, "inline" or "attachment".
367 The default is "inline".
368 Encoding
370 Optional. The content transfer encoding that should be used to
371 encode your data:
372 Use encoding: | If your message contains:
374 ------------------------------------------------------------
375 7bit | Only 7-bit text, all lines <1000 characters
376 8bit | 8-bit text, all lines <1000 characters
377 quoted-printable | 8-bit text or long lines (more reliable than "8bit")
378 base64 | Largely non-textual data: a GIF, a tar file, etc.
379 The default is taken from the Type; generally it is "binary"
381 (no encoding) for text/*, message/*, and multipart/*, and
382 "base64" for everything else. A value of "binary" is generally
383 not suitable for sending anything but ASCII text files with
384 lines under 1000 characters, so consider using one of the other
385 values instead.
386 In the case of "7bit"/"8bit", long lines are automatically
388 chopped to legal length; in the case of "7bit", all 8-bit
389 characters are automatically removed. This may not be what you
390 want, so pick your encoding well! For more info, see "A MIME
391 PRIMER".
392 FH Alternative to "Data" or "Path". Filehandle containing the
394 data, opened for reading. See "ReadNow" also.
395 Filename
397 Optional. The name of the attachment. You can use this to
398 supply a recommended filename for the end-user who is saving
399 the attachment to disk. You only need this if the filename at
400 the end of the "Path" is inadequate, or if you're using "Data"
401 instead of "Path". You should not put path information in here
402 (e.g., no "/" or "\" or ":" characters should be used).
403 Id Optional. Same as setting "content-id".
405 Length
407 Optional. Set the content length explicitly. Normally, this
408 header is automatically computed, but only under certain
409 circumstances (see "Limitations").
410 Path
412 Alternative to "Data" or "FH". Path to a file containing the
413 data... actually, it can be any open()able expression. If it
414 looks like a path, the last element will automatically be
415 treated as the filename. See "ReadNow" also.
416 ReadNow
418 Optional, for use with "Path". If true, will open the path and
419 slurp the contents into core now. This is useful if the Path
420 points to a command and you don't want to run the command over
421 and over if outputting the message several times. Fatal
422 exception raised if the open fails.
423 Top Optional. If defined, indicates whether or not this is a "top-
425 level" MIME message. The parts of a multipart message are not
426 top-level. Default is true.
427 Type
429 Optional. The MIME content type, or one of these special
430 values (case-sensitive):
431 "TEXT" means "text/plain"
433 "BINARY" means "application/octet-stream"
434 "AUTO" means attempt to guess from the filename, falling back
435 to 'application/octet-stream'. This is good if you have
436 MIME::Types on your system and you have no idea what
437 file might be used for the attachment.
438 The default is "TEXT", but it will be "AUTO" if you set
440 $AUTO_CONTENT_TYPE to true (sorry, but you have to enable it
441 explicitly, since we don't want to break code which depends on
442 the old behavior).
443 A picture being worth 1000 words (which is of course 2000 bytes, so
445 it's probably more of an "icon" than a "picture", but I
446 digress...), here are some examples:
447 $msg = MIME::Lite->build(
449 From => 'yelling@inter.com',
450 To => 'stocking@fish.net',
451 Subject => "Hi there!",
452 Type => 'TEXT',
453 Encoding => '7bit',
454 Data => "Just a quick note to say hi!"
455 );
456 $msg = MIME::Lite->build(
458 From => 'dorothy@emerald-city.oz',
459 To => 'gesundheit@edu.edu.edu',
460 Subject => "A gif for U"
461 Type => 'image/gif',
462 Path => "/home/httpd/logo.gif"
463 );
464 $msg = MIME::Lite->build(
466 From => 'laughing@all.of.us',
467 To => 'scarlett@fiddle.dee.de',
468 Subject => "A gzipp'ed tar file",
469 Type => 'x-gzip',
470 Path => "gzip < /usr/inc/somefile.tar |",
471 ReadNow => 1,
472 Filename => "somefile.tgz"
473 );
474 To show you what's really going on, that last example could also
476 have been written:
477 $msg = new MIME::Lite;
479 $msg->build(
480 Type => 'x-gzip',
481 Path => "gzip < /usr/inc/somefile.tar |",
482 ReadNow => 1,
483 Filename => "somefile.tgz"
484 );
485 $msg->add(From => "laughing@all.of.us");
486 $msg->add(To => "scarlett@fiddle.dee.de");
487 $msg->add(Subject => "A gzipp'ed tar file");
488 Setting/getting headers and attributes
490 add TAG,VALUE
491 Instance method. Add field TAG with the given VALUE to the end of
492 the header. The TAG will be converted to all-lowercase, and the
493 VALUE will be made "safe" (returns will be given a trailing space).
494 Beware: any MIME fields you "add" will override any MIME attributes
496 I have when it comes time to output those fields. Normally, you
497 will use this method to add non-MIME fields:
498 $msg->add("Subject" => "Hi there!");
500 Giving VALUE as an arrayref will cause all those values to be
502 added. This is only useful for special multiple-valued fields like
503 "Received":
504 $msg->add("Received" => ["here", "there", "everywhere"]
506 Giving VALUE as the empty string adds an invisible placeholder to
508 the header, which can be used to suppress the output of the
509 "Content-*" fields or the special "MIME-Version" field. When
510 suppressing fields, you should use replace() instead of add():
511 $msg->replace("Content-disposition" => "");
513 Note: add() is probably going to be more efficient than
515 "replace()", so you're better off using it for most applications if
516 you are certain that you don't need to delete() the field first.
517 Note: the name comes from Mail::Header.
519 attr ATTR,[VALUE]
521 Instance method. Set MIME attribute ATTR to the string VALUE.
522 ATTR is converted to all-lowercase. This method is normally used
523 to set/get MIME attributes:
524 $msg->attr("content-type" => "text/html");
526 $msg->attr("content-type.charset" => "US-ASCII");
527 $msg->attr("content-type.name" => "homepage.html");
528 This would cause the final output to look something like this:
530 Content-type: text/html; charset=US-ASCII; name="homepage.html"
532 Note that the special empty sub-field tag indicates the anonymous
534 first sub-field.
535 Giving VALUE as undefined will cause the contents of the named
537 subfield to be deleted.
538 Supplying no VALUE argument just returns the attribute's value:
540 $type = $msg->attr("content-type"); ### returns "text/html"
542 $name = $msg->attr("content-type.name"); ### returns "homepage.html"
543 delete TAG
545 Instance method. Delete field TAG with the given VALUE to the end
546 of the header. The TAG will be converted to all-lowercase.
547 $msg->delete("Subject");
549 Note: the name comes from Mail::Header.
551 field_order FIELD,...FIELD
553 Class/instance method. Change the order in which header fields are
554 output for this object:
555 $msg->field_order('from', 'to', 'content-type', 'subject');
557 When used as a class method, changes the default settings for all
559 objects:
560 MIME::Lite->field_order('from', 'to', 'content-type', 'subject');
562 Case does not matter: all field names will be coerced to lowercase.
564 In either case, supply the empty array to restore the default
565 ordering.
566 fields
568 Instance method. Return the full header for the object, as a ref
569 to an array of "[TAG, VALUE]" pairs, where each TAG is all-
570 lowercase. Note that any fields the user has explicitly set will
571 override the corresponding MIME fields that we would otherwise
572 generate. So, don't say...
573 $msg->set("Content-type" => "text/html; charset=US-ASCII");
575 unless you want the above value to override the "Content-type" MIME
577 field that we would normally generate.
578 Note: I called this "fields" because the header() method of
580 Mail::Header returns something different, but similar enough to be
581 confusing.
582 You can change the order of the fields: see "field_order". You
584 really shouldn't need to do this, but some people have to deal with
585 broken mailers.
586 filename [FILENAME]
588 Instance method. Set the filename which this data will be reported
589 as. This actually sets both "standard" attributes.
590 With no argument, returns the filename as dictated by the content-
592 disposition.
593 get TAG,[INDEX]
595 Instance method. Get the contents of field TAG, which might have
596 been set with set() or replace(). Returns the text of the field.
597 $ml->get('Subject', 0);
599 If the optional 0-based INDEX is given, then we return the INDEX'th
601 occurence of field TAG. Otherwise, we look at the context: In a
602 scalar context, only the first (0th) occurence of the field is
603 returned; in an array context, all occurences are returned.
604 Warning: this should only be used with non-MIME fields. Behavior
606 with MIME fields is TBD, and will raise an exception for now.
607 get_length
609 Instance method. Recompute the content length for the message if
610 the process is trivial, setting the "content-length" attribute as a
611 side-effect:
612 $msg->get_length;
614 Returns the length, or undefined if not set.
616 Note: the content length can be difficult to compute, since it
618 involves assembling the entire encoded body and taking the length
619 of it (which, in the case of multipart messages, means freezing all
620 the sub-parts, etc.).
621 This method only sets the content length to a defined value if the
623 message is a singlepart with "binary" encoding, and the body is
624 available either in-core or as a simple file. Otherwise, the
625 content length is set to the undefined value.
626 Since content-length is not a standard MIME field anyway (that's
628 right, kids: it's not in the MIME RFCs, it's an HTTP thing), this
629 seems pretty fair.
630 parts
632 Instance method. Return the parts of this entity, and this entity
633 only. Returns empty array if this entity has no parts.
634 This is not recursive! Parts can have sub-parts; use parts_DFS()
636 to get everything.
637 parts_DFS
639 Instance method. Return the list of all MIME::Lite objects
640 included in the entity, starting with the entity itself, in depth-
641 first-search order. If this object has no parts, it alone will be
642 returned.
643 preamble [TEXT]
645 Instance method. Get/set the preamble string, assuming that this
646 object has subparts. Set it to undef for the default string.
647 replace TAG,VALUE
649 Instance method. Delete all occurences of fields named TAG, and
650 add a new field with the given VALUE. TAG is converted to all-
651 lowercase.
652 Beware the special MIME fields (MIME-version, Content-*): if you
654 "replace" a MIME field, the replacement text will override the
655 actual MIME attributes when it comes time to output that field. So
656 normally you use attr() to change MIME fields and add()/replace()
657 to change non-MIME fields:
658 $msg->replace("Subject" => "Hi there!");
660 Giving VALUE as the empty string will effectively prevent that
662 field from being output. This is the correct way to suppress the
663 special MIME fields:
664 $msg->replace("Content-disposition" => "");
666 Giving VALUE as undefined will just cause all explicit values for
668 TAG to be deleted, without having any new values added.
669 Note: the name of this method comes from Mail::Header.
671 scrub
673 Instance method. This is Alpha code. If you use it, please let me
674 know how it goes. Recursively goes through the "parts" tree of
675 this message and tries to find MIME attributes that can be removed.
676 With an array argument, removes exactly those attributes; e.g.:
677 $msg->scrub(['content-disposition', 'content-length']);
679 Is the same as recursively doing:
681 $msg->replace('Content-disposition' => '');
683 $msg->replace('Content-length' => '');
684 Setting/getting message data
686 binmode [OVERRIDE]
687 Instance method. With no argument, returns whether or not it
688 thinks that the data (as given by the "Path" argument of "build()")
689 should be read using binmode() (for example, when "read_now()" is
690 invoked).
691 The default behavior is that any content type other than "text/*"
693 or "message/*" is binmode'd; this should in general work fine.
694 With a defined argument, this method sets an explicit "override"
696 value. An undefined argument unsets the override. The new current
697 value is returned.
698 data [DATA]
700 Instance method. Get/set the literal DATA of the message. The
701 DATA may be either a scalar, or a reference to an array of scalars
702 (which will simply be joined).
703 Warning: setting the data causes the "content-length" attribute to
705 be recomputed (possibly to nothing).
706 fh [FILEHANDLE]
708 Instance method. Get/set the FILEHANDLE which contains the message
709 data.
710 Takes a filehandle as an input and stores it in the object. This
712 routine is similar to path(); one important difference is that no
713 attempt is made to set the content length.
714 path [PATH]
716 Instance method. Get/set the PATH to the message data.
717 Warning: setting the path recomputes any existing "content-length"
719 field, and re-sets the "filename" (to the last element of the path
720 if it looks like a simple path, and to nothing if not).
721 resetfh [FILEHANDLE]
723 Instance method. Set the current position of the filehandle back
724 to the beginning. Only applies if you used "FH" in build() or
725 attach() for this message.
726 Returns false if unable to reset the filehandle (since not all
728 filehandles are seekable).
729 read_now
731 Instance method. Forces data from the path/filehandle (as
732 specified by "build()") to be read into core immediately, just as
733 though you had given it literally with the "Data" keyword.
734 Note that the in-core data will always be used if available.
736 Be aware that everything is slurped into a giant scalar: you may
738 not want to use this if sending tar files! The benefit of not
739 reading in the data is that very large files can be handled by this
740 module if left on disk until the message is output via "print()" or
741 "print_body()".
742 sign PARAMHASH
744 Instance method. Sign the message. This forces the message to be
745 read into core, after which the signature is appended to it.
746 Data
748 As in "build()": the literal signature data. Can be either a
749 scalar or a ref to an array of scalars.
750 Path
752 As in "build()": the path to the file.
753 If no arguments are given, the default is:
755 Path => "$ENV{HOME}/.signature"
757 The content-length is recomputed.
759 verify_data
761 Instance method. Verify that all "paths" to attached data exist,
762 recursively. It might be a good idea for you to do this before a
763 print(), to prevent accidental partial output if a file might be
764 missing. Raises exception if any path is not readable.
765 Output
767 print [OUTHANDLE]
768 Instance method. Print the message to the given output handle, or
769 to the currently-selected filehandle if none was given.
770 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
772 any object that responds to a print() message.
773 print_body [OUTHANDLE] [IS_SMTP]
775 Instance method. Print the body of a message to the given output
776 handle, or to the currently-selected filehandle if none was given.
777 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
779 any object that responds to a print() message.
780 Fatal exception raised if unable to open any of the input files, or
782 if a part contains no data, or if an unsupported encoding is
783 encountered.
784 IS_SMPT is a special option to handle SMTP mails a little more
786 intelligently than other send mechanisms may require. Specifically
787 this ensures that the last byte sent is NOT '\n' (octal \012) if
788 the last two bytes are not '\r\n' (\015\012) as this will cause
789 some SMTP servers to hang.
790 print_header [OUTHANDLE]
792 Instance method. Print the header of the message to the given
793 output handle, or to the currently-selected filehandle if none was
794 given.
795 All OUTHANDLE has to be is a filehandle (possibly a glob ref), or
797 any object that responds to a print() message.
798 as_string
800 Instance method. Return the entire message as a string, with a
801 header and an encoded body.
802 body_as_string
804 Instance method. Return the encoded body as a string. This is the
805 portion after the header and the blank line.
806 Note: actually prepares the body by "printing" to a scalar. Proof
808 that you can hand the "print*()" methods any blessed object that
809 responds to a "print()" message.
810 header_as_string
812 Instance method. Return the header as a string.
813 Sending
815 send
816 send HOW, HOWARGS...
817 Class/instance method. This is the principal method for sending
818 mail, and for configuring how mail will be sent.
819 As a class method with a HOW argument and optional HOWARGS, it sets
821 the default sending mechanism that the no-argument instance method
822 will use. The HOW is a facility name (see below), and the HOWARGS
823 is interpreted by the facilty. The class method returns the
824 previous HOW and HOWARGS as an array.
825 MIME::Lite->send('sendmail', "d:\\programs\\sendmail.exe");
827 ...
828 $msg = MIME::Lite->new(...);
829 $msg->send;
830 As an instance method with arguments (a HOW argument and optional
832 HOWARGS), sends the message in the requested manner; e.g.:
833 $msg->send('sendmail', "d:\\programs\\sendmail.exe");
835 As an instance method with no arguments, sends the message by the
837 default mechanism set up by the class method. Returns whatever the
838 mail-handling routine returns: this should be true on success,
839 false/exception on error:
840 $msg = MIME::Lite->new(From=>...);
842 $msg->send || die "you DON'T have mail!";
843 On Unix systems (or rather non-Win32 systems), the default setting
845 is equivalent to:
846 MIME::Lite->send("sendmail", "/usr/lib/sendmail -t -oi -oem");
848 On Win32 systems the default setting is equivalent to:
850 MIME::Lite->send("smtp");
852 The assumption is that on Win32 your site/lib/Net/libnet.cfg file
854 will be preconfigured to use the appropriate SMTP server. See below
855 for configuring for authentication.
856 There are three facilities:
858 "sendmail", ARGS...
860 Send a message by piping it into the "sendmail" command. Uses
861 the send_by_sendmail() method, giving it the ARGS. This usage
862 implements (and deprecates) the "sendmail()" method.
863 "smtp", [HOSTNAME, [NAMEDPARMS] ]
865 Send a message by SMTP, using optional HOSTNAME as SMTP-sending
866 host. Uses the send_by_smtp() method. Any additional arguments
867 passed in will also be passed through to send_by_smtp. This is
868 useful for things like mail servers requiring authentication
869 where you can say something like the following
870 MIME::List->send('smtp', $host, AuthUser=>$user, AuthPass=>$pass);
872 which will configure things so future uses of
874 $msg->send();
876 do the right thing.
878 "sub", \&SUBREF, ARGS...
880 Sends a message MSG by invoking the subroutine SUBREF of your
881 choosing, with MSG as the first argument, and ARGS following.
882 For example: let's say you're on an OS which lacks the usual Unix
884 "sendmail" facility, but you've installed something a lot like it,
885 and you need to configure your Perl script to use this
886 "sendmail.exe" program. Do this following in your script's setup:
887 MIME::Lite->send('sendmail', "d:\\programs\\sendmail.exe");
889 Then, whenever you need to send a message $msg, just say:
891 $msg->send;
893 That's it. Now, if you ever move your script to a Unix box, all
895 you need to do is change that line in the setup and you're done.
896 All of your $msg->send invocations will work as expected.
897 After sending, the method last_send_successful() can be used to
899 determine if the send was succesful or not.
900 send_by_sendmail SENDMAILCMD
902 send_by_sendmail PARAM=>VALUE, ARRAY, HASH...
903 Instance method. Send message via an external "sendmail" program
904 (this will probably only work out-of-the-box on Unix systems).
905 Returns true on success, false or exception on error.
907 You can specify the program and all its arguments by giving a
909 single string, SENDMAILCMD. Nothing fancy is done; the message is
910 simply piped in.
911 However, if your needs are a little more advanced, you can specify
913 zero or more of the following PARAM/VALUE pairs (or a reference to
914 hash or array of such arguments as well as any combination
915 thereof); a Unix-style, taint-safe "sendmail" command will be
916 constructed for you:
917 Sendmail
919 Full path to the program to use. Default is
920 "/usr/lib/sendmail".
921 BaseArgs
923 Ref to the basic array of arguments we start with. Default is
924 "["-t", "-oi", "-oem"]".
925 SetSender
927 Unless this is explicitly given as false, we attempt to
928 automatically set the "-f" argument to the first address that
929 can be extracted from the "From:" field of the message (if
930 there is one).
931 What is the -f, and why do we use it? Suppose we did not use
933 "-f", and you gave an explicit "From:" field in your message:
934 in this case, the sendmail "envelope" would indicate the real
935 user your process was running under, as a way of preventing
936 mail forgery. Using the "-f" switch causes the sender to be
937 set in the envelope as well.
938 So when would I NOT want to use it? If sendmail doesn't regard
940 you as a "trusted" user, it will permit the "-f" but also add
941 an "X-Authentication-Warning" header to the message to indicate
942 a forged envelope. To avoid this, you can either (1) have
943 SetSender be false, or (2) make yourself a trusted user by
944 adding a "T" configuration
945 command to your sendmail.cf file
946 (e.g.: "Teryq" if the script is running as user "eryq").
947 FromSender
949 If defined, this is identical to setting SetSender to true,
950 except that instead of looking at the "From:" field we use the
951 address given by this option. Thus:
952 FromSender => 'me@myhost.com'
954 After sending, the method last_send_successful() can be used to
956 determine if the send was succesful or not.
957 send_by_smtp HOST, ARGS...
959 send_by_smtp REF, HOST, ARGS
960 Instance method. Send message via SMTP, using Net::SMTP.
961 HOST is the name of SMTP server to connect to, or undef to have
963 Net::SMTP use the defaults in Libnet.cfg.
964 ARGS are a list of key value pairs which may be selected from the
966 list below. Many of these are just passed through to specific
967 Net::SMTP commands and you should review that module for details.
968 Please see Good-vs-bad email addresses with send_by_smtp()
970 Hello
972 LocalAddr
973 LocalPort
974 Timeout
975 Port
976 ExactAddresses
977 Debug
978 See Net::SMTP::new() for details.
979 Size
981 Return
982 Bits
983 Transaction
984 Envelope
985 See Net::SMTP::mail() for details.
986 SkipBad
988 If true doesnt throw an error when multiple email addresses are
989 provided and some are not valid. See Net::SMTP::recipient() for
990 details.
991 AuthUser
993 Authenticate with Net::SMTP::auth() using this username.
994 AuthPass
996 Authenticate with Net::SMTP::auth() using this password.
997 NoAuth
999 Normally if AuthUser and AuthPass are defined MIME::Lite will
1000 attempt to use them with the Net::SMTP::auth() command to
1001 authenticate the connection, however if this value is true then
1002 no authentication occurs.
1003 To Sets the addresses to send to. Can be a string or a reference
1005 to an array of strings. Normally this is extracted from the To:
1006 (and Cc: and Bcc: fields if $AUTO_CC is true).
1007 This value overrides that.
1009 From
1011 Sets the email address to send from. Normally this value is
1012 extracted from the Return-Path: or From: field of the mail
1013 itself (in that order).
1014 This value overides that.
1016 Returns: True on success, croaks with an error message on failure.
1018 After sending, the method last_send_successful() can be used to
1020 determine if the send was succesful or not.
1021 send_by_testfile FILENAME
1023 Instance method. Print message to a file (namely FILENAME), which
1024 will default to mailer.testfile If file exists, message will be
1025 appended.
1026 last_send_successful
1028 This method will return TRUE if the last send() or send_by_XXX()
1029 method call was successful. It will return defined but false if it
1030 was not successful, and undefined if the object had not been used
1031 to send yet.
1032 sendmail COMMAND...
1034 Class method, DEPRECATED. Declare the sender to be "sendmail", and
1035 set up the "sendmail" command. You should use send() instead.
1036 Miscellaneous
1038 quiet ONOFF
1039 Class method. Suppress/unsuppress all warnings coming from this
1040 module.
1041 MIME::Lite->quiet(1); ### I know what I'm doing
1043 I recommend that you include that comment as well. And while you
1045 type it, say it out loud: if it doesn't feel right, then maybe you
1046 should reconsider the whole line. ";-)"
1047
1049 How do I prevent "Content" headers from showing up in my mail reader?
1050 Apparently, some people are using mail readers which display the MIME
1051 headers like "Content-disposition", and they want MIME::Lite not to
1052 generate them "because they look ugly".
1053 Sigh.
1055 Y'know, kids, those headers aren't just there for cosmetic purposes.
1057 They help ensure that the message is understood correctly by mail
1058 readers. But okay, you asked for it, you got it... here's how you can
1059 suppress the standard MIME headers. Before you send the message, do
1060 this:
1061 $msg->scrub;
1063 You can scrub() any part of a multipart message independently; just be
1065 aware that it works recursively. Before you scrub, note the rules that
1066 I follow:
1067 Content-type
1069 You can safely scrub the "content-type" attribute if, and only if,
1070 the part is of type "text/plain" with charset "us-ascii".
1071 Content-transfer-encoding
1073 You can safely scrub the "content-transfer-encoding" attribute if,
1074 and only if, the part uses "7bit", "8bit", or "binary" encoding.
1075 You are far better off doing this if your lines are under 1000
1076 characters. Generally, that means you can scrub it for plain text,
1077 and you can not scrub this for images, etc.
1078 Content-disposition
1080 You can safely scrub the "content-disposition" attribute if you
1081 trust the mail reader to do the right thing when it decides whether
1082 to show an attachment inline or as a link. Be aware that scrubbing
1083 both the content-disposition and the content-type means that there
1084 is no way to "recommend" a filename for the attachment!
1085 Note: there are reports of brain-dead MUAs out there that do the
1087 wrong thing if you provide the content-disposition. If your
1088 attachments keep showing up inline or vice-versa, try scrubbing
1089 this attribute.
1090 Content-length
1092 You can always scrub "content-length" safely.
1093 How do I give my attachment a [different] recommended filename?
1095 By using the Filename option (which is different from Path!):
1096 $msg->attach(Type => "image/gif",
1098 Path => "/here/is/the/real/file.GIF",
1099 Filename => "logo.gif");
1100 You should not put path information in the Filename.
1102 Benign limitations
1104 This is "lite", after all...
1105 · There's no parsing. Get MIME-tools if you need to parse MIME
1107 messages.
1108 · MIME::Lite messages are currently not interchangeable with either
1110 Mail::Internet or MIME::Entity objects. This is a completely
1111 separate module.
1112 · A content-length field is only inserted if the encoding is binary,
1114 the message is a singlepart, and all the document data is available
1115 at "build()" time by virtue of residing in a simple path, or in-
1116 core. Since content-length is not a standard MIME field anyway
1117 (that's right, kids: it's not in the MIME RFCs, it's an HTTP
1118 thing), this seems pretty fair.
1119 · MIME::Lite alone cannot help you lose weight. You must supplement
1121 your use of MIME::Lite with a healthy diet and exercise.
1122 Cheap and easy mailing
1124 I thought putting in a default "sendmail" invocation wasn't too bad an
1125 idea, since a lot of Perlers are on UNIX systems. (As of version 3.02
1126 this is default only on Non-Win32 boxen. On Win32 boxen the default is
1127 to use SMTP and the defaults specified in the site/lib/Net/libnet.cfg)
1128 The out-of-the-box configuration is:
1130 MIME::Lite->send('sendmail', "/usr/lib/sendmail -t -oi -oem");
1132 By the way, these arguments to sendmail are:
1134 -t Scan message for To:, Cc:, Bcc:, etc.
1136 -oi Do NOT treat a single "." on a line as a message terminator.
1138 As in, "-oi vey, it truncated my message... why?!"
1139 -oem On error, mail back the message (I assume to the
1141 appropriate address, given in the header).
1142 When mail returns, circle is complete. Jai Guru Deva -oem.
1143 Note that these are the same arguments you get if you configure to use
1145 the smarter, taint-safe mailing:
1146 MIME::Lite->send('sendmail');
1148 If you get "X-Authentication-Warning" headers from this, you can forgo
1150 diddling with the envelope by instead specifying:
1151 MIME::Lite->send('sendmail', SetSender=>0);
1153 And, if you're not on a Unix system, or if you'd just rather send mail
1155 some other way, there's always SMTP, which these days probably requires
1156 authentication so you probably need to say
1157 MIME::Lite->send('smtp', "smtp.myisp.net",
1159 AuthUser=>"YourName",AuthPass=>"YourPass" );
1160 Or you can set up your own subroutine to call. In any case, check out
1162 the send() method.
1163
1165 Good-vs-bad email addresses with send_by_smtp()
1166 If using send_by_smtp(), be aware that unless you explicitly provide
1167 the email addresses to send to and from you will be forcing MIME::Lite
1168 to extract email addresses out of a possible list provided in the
1169 "To:", "Cc:", and "Bcc:" fields. This is tricky stuff, and as such
1170 only the following sorts of addresses will work reliably:
1171 username
1173 full.name@some.host.com
1174 "Name, Full" <full.name@some.host.com>
1175 Disclaimer: MIME::Lite was never intended to be a Mail User Agent, so
1177 please don't expect a full implementation of RFC-822. Restrict
1178 yourself to the common forms of Internet addresses described herein,
1179 and you should be fine. If this is not feasible, then consider using
1180 MIME::Lite to prepare your message only, and using Net::SMTP explicitly
1181 to send your message.
1182 Note: As of MIME::Lite v3.02 the mail name extraction routines have
1184 been beefed up considerably. Furthermore if Mail::Address if provided
1185 then name extraction is done using that. Accordingly the above advice
1186 is now less true than it once was. Funky email names should work
1187 properly now. However the disclaimer remains. Patches welcome. :-)
1188 Formatting of headers delayed until print()
1190 This class treats a MIME header in the most abstract sense, as being a
1191 collection of high-level attributes. The actual RFC-822-style header
1192 fields are not constructed until it's time to actually print the darn
1193 thing.
1194 Encoding of data delayed until print()
1196 When you specify message bodies (in build() or attach()) -- whether by
1197 FH, Data, or Path -- be warned that we don't attempt to open files,
1198 read filehandles, or encode the data until print() is invoked.
1199 In the past, this created some confusion for users of sendmail who gave
1201 the wrong path to an attachment body, since enough of the print() would
1202 succeed to get the initial part of the message out. Nowadays,
1203 $AUTO_VERIFY is used to spot-check the Paths given before the mail
1204 facility is employed. A whisker slower, but tons safer.
1205 Note that if you give a message body via FH, and try to print() a
1207 message twice, the second print() will not do the right thing unless
1208 you explicitly rewind the filehandle.
1209 You can get past these difficulties by using the ReadNow option,
1211 provided that you have enough memory to handle your messages.
1212 MIME attributes are separate from header fields!
1214 Important: the MIME attributes are stored and manipulated separately
1215 from the message header fields; when it comes time to print the header
1216 out, any explicitly-given header fields override the ones that would be
1217 created from the MIME attributes. That means that this:
1218 ### DANGER ### DANGER ### DANGER ### DANGER ### DANGER ###
1220 $msg->add("Content-type", "text/html; charset=US-ASCII");
1221 will set the exact "Content-type" field in the header I write,
1223 regardless of what the actual MIME attributes are.
1224 This feature is for experienced users only, as an escape hatch in case
1226 the code that normally formats MIME header fields isn't doing what you
1227 need. And, like any escape hatch, it's got an alarm on it: MIME::Lite
1228 will warn you if you attempt to "set()" or "replace()" any MIME header
1229 field. Use "attr()" instead.
1230 Beware of lines consisting of a single dot
1232 Julian Haight noted that MIME::Lite allows you to compose messages with
1233 lines in the body consisting of a single ".". This is true: it should
1234 be completely harmless so long as "sendmail" is used with the -oi
1235 option (see "Cheap and easy mailing").
1236 However, I don't know if using Net::SMTP to transfer such a message is
1238 equally safe. Feedback is welcomed.
1239 My perspective: I don't want to magically diddle with a user's message
1241 unless absolutely positively necessary. Some users may want to send
1242 files with "." alone on a line; my well-meaning tinkering could
1243 seriously harm them.
1244 Infinite loops may mean tainted data!
1246 Stefan Sautter noticed a bug in 2.106 where a m//gc match was failing
1247 due to tainted data, leading to an infinite loop inside MIME::Lite.
1248 I am attempting to correct for this, but be advised that my fix will
1250 silently untaint the data (given the context in which the problem
1251 occurs, this should be benign: I've labelled the source code with
1252 UNTAINT comments for the curious).
1253 So: don't depend on taint-checking to save you from outputting tainted
1255 data in a message.
1256 Don't tweak the global configuration
1258 Global configuration variables are bad, and should go away. Until they
1259 do, please follow the hints with each setting on how not to change it.
1260
1262 Content types
1263 The "Type" parameter of "build()" is a content type. This is the
1264 actual type of data you are sending. Generally this is a string of the
1265 form "majortype/minortype".
1266 Here are the major MIME types. A more-comprehensive listing may be
1268 found in RFC-2046.
1269 application
1271 Data which does not fit in any of the other categories,
1272 particularly data to be processed by some type of application
1273 program. "application/octet-stream", "application/gzip",
1274 "application/postscript"...
1275 audio
1277 Audio data. "audio/basic"...
1278 image
1280 Graphics data. "image/gif", "image/jpeg"...
1281 message
1283 A message, usually another mail or MIME message.
1284 "message/rfc822"...
1285 multipart
1287 A message containing other messages. "multipart/mixed",
1288 "multipart/alternative"...
1289 text
1291 Textual data, meant for humans to read. "text/plain",
1292 "text/html"...
1293 video
1295 Video or video+audio data. "video/mpeg"...
1296 Content transfer encodings
1298 The "Encoding" parameter of "build()". This is how the message body is
1299 packaged up for safe transit.
1300 Here are the 5 major MIME encodings. A more-comprehensive listing may
1302 be found in RFC-2045.
1303 7bit
1305 Basically, no real encoding is done. However, this label
1306 guarantees that no 8-bit characters are present, and that lines do
1307 not exceed 1000 characters in length.
1308 8bit
1310 Basically, no real encoding is done. The message might contain
1311 8-bit characters, but this encoding guarantees that lines do not
1312 exceed 1000 characters in length.
1313 binary
1315 No encoding is done at all. Message might contain 8-bit
1316 characters, and lines might be longer than 1000 characters long.
1317 The most liberal, and the least likely to get through mail
1319 gateways. Use sparingly, or (better yet) not at all.
1320 base64
1322 Like "uuencode", but very well-defined. This is how you should
1323 send essentially binary information (tar files, GIFs, JPEGs, etc.).
1324 quoted-printable
1326 Useful for encoding messages which are textual in nature, yet which
1327 contain non-ASCII characters (e.g., Latin-1, Latin-2, or any other
1328 8-bit alphabet).
1329
1331 MIME::Lite works nicely with other certain other modules if they are
1332 present. Good to have installed is the latest MIME::Types,
1333 Mail::Address, MIME::Base64, MIME::QuotedPrint.
1334 If they aren't present then some functionality won't work, and other
1336 features wont be as efficient or up to date as they could be.
1337 Nevertheless they are optional extras.
1338
1340 MIME::Lite comes with a number of extra files in the distribution
1341 bundle. This includes examples, and utility modules that you can use
1342 to get yourself started with the module.
1343 The ./examples directory contains a number of snippets in prepared
1345 form, generally they are documented, but they should be easy to
1346 understand.
1347 The ./contrib directory contains a companion/tool modules that come
1349 bundled with MIME::Lite, they dont get installed by default. Please
1350 review the POD they come with.
1351
1353 The whole reason that version 3.0 was released was to ensure that
1354 MIME::Lite is up to date and patched. If you find an issue please
1355 report it.
1356 As far as I know MIME::Lite doesnt currently have any serious bugs, but
1358 my usage is hardly comprehensive.
1359 Having said that there are a number of open issues for me, mostly
1361 caused by the progress in the community as whole since Eryq last
1362 released. The tests are based around an interesting but non standard
1363 test framework. I'd like to change it over to using Test::More.
1364 Should tests fail please review the ./testout directory, and in any bug
1366 reports please include the output of the relevent file. This is the
1367 only redeeming feature of not using Test::More that I can see.
1368 Bug fixes / Patches / Contribution are welcome, however I probably
1370 won't apply them unless they also have an associated test. This means
1371 that if I dont have the time to write the test the patch wont get
1372 applied, so please, include tests for any patches you provide.
1373
1375 Version: 3.027
1376
1378 Moved to ./changes.pod
1379 NOTE: Users of the "advanced features" of 3.01_0x smtp sending should
1381 take care: These features have been REMOVED as they never really fit
1382 the purpose of the module. Redundant SMTP delivery is a task that
1383 should be handled by another module.
1384
1386 Copyright (c) 1997 by Eryq.
1387 Copyright (c) 1998 by ZeeGee Software Inc.
1388 Copyright (c) 2003,2005 Yves Orton. (demerphq)
1389 All rights reserved. This program is free software; you can
1391 redistribute it and/or modify it under the same terms as Perl itself.
1392 This software comes with NO WARRANTY of any kind. See the COPYING file
1394 in the distribution for details.
1395
1397 For some reason, the US FDA says that this is now required by law on
1398 any products that bear the name "Lite"...
1399 Version 3.0 is now new and improved! The distribution is now 30%
1401 smaller!
1402 MIME::Lite |
1404 ------------------------------------------------------------
1405 Serving size: | 1 module
1406 Servings per container: | 1
1407 Calories: | 0
1408 Fat: | 0g
1409 Saturated Fat: | 0g
1410 Warning: for consumption by hardware only! May produce indigestion in
1412 humans if taken internally.
1413
1415 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc.
1416 (http://www.zeegee.com).
1417 Go to http://www.cpan.org for the latest downloads and on-line
1419 documentation for this module. Enjoy.
1420 Patches And Maintenance by Yves Orton and many others. Consult
1422 ./changes.pod
1423perl v5.12.0 2009-10-10 MIME::Lite(3)