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