.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIME::Lite 3pm"
.TH MIME::Lite 3pm "2014-06-11" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MIME::Lite \- low\-calorie MIME generator
.SH "WAIT!"
.IX Header "WAIT!"
MIME::Lite is not recommended by its current maintainer.  There are a number of
alternatives, like Email::MIME or MIME::Entity and Email::Sender, which you
should probably use instead.  MIME::Lite continues to accrue weird bug reports,
and it is not receiving a large amount of refactoring due to the availability
of better alternatives.  Please consider using something else.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Create and send using the default send method for your \s-1OS\s0 a single-part message:
.PP
.Vb 12
\&    use MIME::Lite;
\&    ### Create a new single\-part message, to send a GIF file:
\&    $msg = MIME::Lite\->new(
\&        From     => \*(Aqme@myhost.com\*(Aq,
\&        To       => \*(Aqyou@yourhost.com\*(Aq,
\&        Cc       => \*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject  => \*(AqHelloooooo, nurse!\*(Aq,
\&        Type     => \*(Aqimage/gif\*(Aq,
\&        Encoding => \*(Aqbase64\*(Aq,
\&        Path     => \*(Aqhellonurse.gif\*(Aq
\&    );
\&    $msg\->send; # send via default
.Ve
.PP
Create a multipart message (i.e., one with attachments) and send it \s-1SMTP\s0
.PP
.Vb 8
\&    ### Create a new multipart message:
\&    $msg = MIME::Lite\->new(
\&        From    => \*(Aqme@myhost.com\*(Aq,
\&        To      => \*(Aqyou@yourhost.com\*(Aq,
\&        Cc      => \*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject => \*(AqA message with 2 parts...\*(Aq,
\&        Type    => \*(Aqmultipart/mixed\*(Aq
\&    );
\&
\&    ### Add parts (each "attach" has same arguments as "new"):
\&    $msg\->attach(
\&        Type     => \*(AqTEXT\*(Aq,
\&        Data     => "Here\*(Aqs the GIF file you wanted"
\&    );
\&    $msg\->attach(
\&        Type     => \*(Aqimage/gif\*(Aq,
\&        Path     => \*(Aqaaa000123.gif\*(Aq,
\&        Filename => \*(Aqlogo.gif\*(Aq,
\&        Disposition => \*(Aqattachment\*(Aq
\&    );
\&    ### use Net:SMTP to do the sending
\&    $msg\->send(\*(Aqsmtp\*(Aq,\*(Aqsome.host\*(Aq, Debug=>1 );
.Ve
.PP
Output a message:
.PP
.Vb 2
\&    ### Format as a string:
\&    $str = $msg\->as_string;
\&
\&    ### Print to a filehandle (say, a "sendmail" stream):
\&    $msg\->print(\e*SENDMAIL);
.Ve
.PP
Send a message:
.PP
.Vb 4
\&    ### Send in the "best" way (the default is to use "sendmail"):
\&    $msg\->send;
\&    ### Send a specific way:
\&    $msg\->send(\*(Aqtype\*(Aq,@args);
.Ve
.PP
Specify default send method:
.PP
.Vb 1
\&    MIME::Lite\->send(\*(Aqsmtp\*(Aq,\*(Aqsome.host\*(Aq,Debug=>0);
.Ve
.PP
with authentication
.PP
.Vb 1
\&    MIME::Lite\->send(\*(Aqsmtp\*(Aq,\*(Aqsome.host\*(Aq, AuthUser=>$user, AuthPass=>$pass);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In the never-ending quest for great taste with fewer calories,
we proudly present: \fIMIME::Lite\fR.
.PP
MIME::Lite is intended as a simple, standalone module for generating
(not parsing!) \s-1MIME\s0 messages... specifically, it allows you to
output a simple, decent single\- or multi-part message with text or binary
attachments.  It does not require that you have the Mail:: or \s-1MIME::\s0
modules installed, but will work with them if they are.
.PP
You can specify each message part as either the literal data itself (in
a scalar or array), or as a string which can be given to \fIopen()\fR to get
a readable filehandle (e.g., \*(L"<filename\*(R" or \*(L"somecommand|\*(R").
.PP
You don't need to worry about encoding your message data:
this module will do that for you.  It handles the 5 standard \s-1MIME\s0 encodings.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Create a simple message containing just text"
.IX Subsection "Create a simple message containing just text"
.Vb 7
\&    $msg = MIME::Lite\->new(
\&        From     =>\*(Aqme@myhost.com\*(Aq,
\&        To       =>\*(Aqyou@yourhost.com\*(Aq,
\&        Cc       =>\*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject  =>\*(AqHelloooooo, nurse!\*(Aq,
\&        Data     =>"How\*(Aqs it goin\*(Aq, eh?"
\&    );
.Ve
.SS "Create a simple message containing just an image"
.IX Subsection "Create a simple message containing just an image"
.Vb 9
\&    $msg = MIME::Lite\->new(
\&        From     =>\*(Aqme@myhost.com\*(Aq,
\&        To       =>\*(Aqyou@yourhost.com\*(Aq,
\&        Cc       =>\*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject  =>\*(AqHelloooooo, nurse!\*(Aq,
\&        Type     =>\*(Aqimage/gif\*(Aq,
\&        Encoding =>\*(Aqbase64\*(Aq,
\&        Path     =>\*(Aqhellonurse.gif\*(Aq
\&    );
.Ve
.SS "Create a multipart message"
.IX Subsection "Create a multipart message"
.Vb 8
\&    ### Create the multipart "container":
\&    $msg = MIME::Lite\->new(
\&        From    =>\*(Aqme@myhost.com\*(Aq,
\&        To      =>\*(Aqyou@yourhost.com\*(Aq,
\&        Cc      =>\*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject =>\*(AqA message with 2 parts...\*(Aq,
\&        Type    =>\*(Aqmultipart/mixed\*(Aq
\&    );
\&
\&    ### Add the text message part:
\&    ### (Note that "attach" has same arguments as "new"):
\&    $msg\->attach(
\&        Type     =>\*(AqTEXT\*(Aq,
\&        Data     =>"Here\*(Aqs the GIF file you wanted"
\&    );
\&
\&    ### Add the image part:
\&    $msg\->attach(
\&        Type        =>\*(Aqimage/gif\*(Aq,
\&        Path        =>\*(Aqaaa000123.gif\*(Aq,
\&        Filename    =>\*(Aqlogo.gif\*(Aq,
\&        Disposition => \*(Aqattachment\*(Aq
\&    );
.Ve
.SS "Attach a \s-1GIF\s0 to a text message"
.IX Subsection "Attach a GIF to a text message"
This will create a multipart message exactly as above, but using the
\&\*(L"attach to singlepart\*(R" hack:
.PP
.Vb 9
\&    ### Start with a simple text message:
\&    $msg = MIME::Lite\->new(
\&        From    =>\*(Aqme@myhost.com\*(Aq,
\&        To      =>\*(Aqyou@yourhost.com\*(Aq,
\&        Cc      =>\*(Aqsome@other.com, some@more.com\*(Aq,
\&        Subject =>\*(AqA message with 2 parts...\*(Aq,
\&        Type    =>\*(AqTEXT\*(Aq,
\&        Data    =>"Here\*(Aqs the GIF file you wanted"
\&    );
\&
\&    ### Attach a part... the make the message a multipart automatically:
\&    $msg\->attach(
\&        Type     =>\*(Aqimage/gif\*(Aq,
\&        Path     =>\*(Aqaaa000123.gif\*(Aq,
\&        Filename =>\*(Aqlogo.gif\*(Aq
\&    );
.Ve
.SS "Attach a pre-prepared part to a message"
.IX Subsection "Attach a pre-prepared part to a message"
.Vb 8
\&    ### Create a standalone part:
\&    $part = MIME::Lite\->new(
\&        Top      => 0,
\&        Type     =>\*(Aqtext/html\*(Aq,
\&        Data     =>\*(Aq<H1>Hello</H1>\*(Aq,
\&    );
\&    $part\->attr(\*(Aqcontent\-type.charset\*(Aq => \*(AqUTF\-8\*(Aq);
\&    $part\->add(\*(AqX\-Comment\*(Aq => \*(AqA message for you\*(Aq);
\&
\&    ### Attach it to any message:
\&    $msg\->attach($part);
.Ve
.SS "Print a message to a filehandle"
.IX Subsection "Print a message to a filehandle"
.Vb 2
\&    ### Write it to a filehandle:
\&    $msg\->print(\e*STDOUT);
\&
\&    ### Write just the header:
\&    $msg\->print_header(\e*STDOUT);
\&
\&    ### Write just the encoded body:
\&    $msg\->print_body(\e*STDOUT);
.Ve
.SS "Print a message into a string"
.IX Subsection "Print a message into a string"
.Vb 2
\&    ### Get entire message as a string:
\&    $str = $msg\->as_string;
\&
\&    ### Get just the header:
\&    $str = $msg\->header_as_string;
\&
\&    ### Get just the encoded body:
\&    $str = $msg\->body_as_string;
.Ve
.SS "Send a message"
.IX Subsection "Send a message"
.Vb 2
\&    ### Send in the "best" way (the default is to use "sendmail"):
\&    $msg\->send;
.Ve
.SS "Send an \s-1HTML\s0 document... with images included!"
.IX Subsection "Send an HTML document... with images included!"
.Vb 10
\&    $msg = MIME::Lite\->new(
\&         To      =>\*(Aqyou@yourhost.com\*(Aq,
\&         Subject =>\*(AqHTML with in\-line images!\*(Aq,
\&         Type    =>\*(Aqmultipart/related\*(Aq
\&    );
\&    $msg\->attach(
\&        Type => \*(Aqtext/html\*(Aq,
\&        Data => qq{
\&            <body>
\&                Here\*(Aqs <i>my</i> image:
\&                <img src="cid:myimage.gif">
\&            </body>
\&        },
\&    );
\&    $msg\->attach(
\&        Type => \*(Aqimage/gif\*(Aq,
\&        Id   => \*(Aqmyimage.gif\*(Aq,
\&        Path => \*(Aq/path/to/somefile.gif\*(Aq,
\&    );
\&    $msg\->send();
.Ve
.SS "Change how messages are sent"
.IX Subsection "Change how messages are sent"
.Vb 5
\&    ### Do something like this in your \*(Aqmain\*(Aq:
\&    if ($I_DONT_HAVE_SENDMAIL) {
\&       MIME::Lite\->send(\*(Aqsmtp\*(Aq, $host, Timeout=>60,
\&           AuthUser=>$user, AuthPass=>$pass);
\&    }
\&
\&    ### Now this will do the right thing:
\&    $msg\->send;         ### will now use Net::SMTP as shown above
.Ve
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "Global configuration"
.IX Subsection "Global configuration"
To alter the way the entire module behaves, you have the following
methods/options:
.IP "MIME::Lite\->\fIfield_order()\fR" 4
.IX Item "MIME::Lite->field_order()"
When used as a classmethod, this changes the default
order in which headers are output for \fIall\fR messages.
However, please consider using the instance method variant instead,
so you won't stomp on other message senders in the same application.
.IP "MIME::Lite\->\fIquiet()\fR" 4
.IX Item "MIME::Lite->quiet()"
This classmethod can be used to suppress/unsuppress
all warnings coming from this module.
.IP "MIME::Lite\->\fIsend()\fR" 4
.IX Item "MIME::Lite->send()"
When used as a classmethod, this can be used to specify
a different default mechanism for sending message.
The initial default is:
.Sp
.Vb 1
\&    MIME::Lite\->send("sendmail", "/usr/lib/sendmail \-t \-oi \-oem");
.Ve
.Sp
However, you should consider the similar but smarter and taint-safe variant:
.Sp
.Vb 1
\&    MIME::Lite\->send("sendmail");
.Ve
.Sp
Or, for non-Unix users:
.Sp
.Vb 1
\&    MIME::Lite\->send("smtp");
.Ve
.ie n .IP "$MIME::Lite::AUTO_CC" 4
.el .IP "\f(CW$MIME::Lite::AUTO_CC\fR" 4
.IX Item "$MIME::Lite::AUTO_CC"
If true, automatically send to the Cc/Bcc addresses for \fIsend_by_smtp()\fR.
Default is \fBtrue\fR.
.ie n .IP "$MIME::Lite::AUTO_CONTENT_TYPE" 4
.el .IP "\f(CW$MIME::Lite::AUTO_CONTENT_TYPE\fR" 4
.IX Item "$MIME::Lite::AUTO_CONTENT_TYPE"
If true, try to automatically choose the content type from the file name
in \f(CW\*(C`new()\*(C'\fR/\f(CW\*(C`build()\*(C'\fR.  In other words, setting this true changes the
default \f(CW\*(C`Type\*(C'\fR from \f(CW"TEXT"\fR to \f(CW"AUTO"\fR.
.Sp
Default is \fBfalse\fR, since we must maintain backwards-compatibility
with prior behavior.  \fBPlease\fR consider keeping it false,
and just using Type '\s-1AUTO\s0' when you \fIbuild()\fR or \fIattach()\fR.
.ie n .IP "$MIME::Lite::AUTO_ENCODE" 4
.el .IP "\f(CW$MIME::Lite::AUTO_ENCODE\fR" 4
.IX Item "$MIME::Lite::AUTO_ENCODE"
If true, automatically choose the encoding from the content type.
Default is \fBtrue\fR.
.ie n .IP "$MIME::Lite::AUTO_VERIFY" 4
.el .IP "\f(CW$MIME::Lite::AUTO_VERIFY\fR" 4
.IX Item "$MIME::Lite::AUTO_VERIFY"
If true, check paths to attachments right before printing, raising an exception
if any path is unreadable.
Default is \fBtrue\fR.
.ie n .IP "$MIME::Lite::PARANOID" 4
.el .IP "\f(CW$MIME::Lite::PARANOID\fR" 4
.IX Item "$MIME::Lite::PARANOID"
If true, we won't attempt to use MIME::Base64, MIME::QuotedPrint,
or MIME::Types, even if they're available.
Default is \fBfalse\fR.  Please consider keeping it false,
and trusting these other packages to do the right thing.
.SS "Construction"
.IX Subsection "Construction"
.IP "new [\s-1PARAMHASH\s0]" 4
.IX Item "new [PARAMHASH]"
\&\fIClass method, constructor.\fR
Create a new message object.
.Sp
If any arguments are given, they are passed into \f(CW\*(C`build()\*(C'\fR; otherwise,
just the empty object is created.
.IP "attach \s-1PART\s0" 4
.IX Item "attach PART"
.PD 0
.IP "attach \s-1PARAMHASH...\s0" 4
.IX Item "attach PARAMHASH..."
.PD
\&\fIInstance method.\fR
Add a new part to this message, and return the new part.
.Sp
If you supply a single \s-1PART\s0 argument, it will be regarded
as a MIME::Lite object to be attached.  Otherwise, this
method assumes that you are giving in the pairs of a \s-1PARAMHASH\s0
which will be sent into \f(CW\*(C`new()\*(C'\fR to create the new part.
.Sp
One of the possibly-quite-useful hacks thrown into this is the
\&\*(L"attach-to-singlepart\*(R" hack: if you attempt to attach a part (let's
call it \*(L"part 1\*(R") to a message that doesn't have a content-type
of \*(L"multipart\*(R" or \*(L"message\*(R", the following happens:
.RS 4
.IP "\(bu" 4
A new part (call it \*(L"part 0\*(R") is made.
.IP "\(bu" 4
The \s-1MIME\s0 attributes and data (but \fInot\fR the other headers)
are cut from the \*(L"self\*(R" message, and pasted into \*(L"part 0\*(R".
.IP "\(bu" 4
The \*(L"self\*(R" is turned into a \*(L"multipart/mixed\*(R" message.
.IP "\(bu" 4
The new \*(L"part 0\*(R" is added to the \*(L"self\*(R", and \fIthen\fR \*(L"part 1\*(R" is added.
.RE
.RS 4
.Sp
One of the nice side-effects is that you can create a text message
and then add zero or more attachments to it, much in the same way
that a user agent like Netscape allows you to do.
.RE
.IP "build [\s-1PARAMHASH\s0]" 4
.IX Item "build [PARAMHASH]"
\&\fIClass/instance method, initializer.\fR
Create (or initialize) a \s-1MIME\s0 message object.
Normally, you'll use the following keys in \s-1PARAMHASH:\s0
.Sp
.Vb 3
\&   * Data, FH, or Path      (either one of these, or none if multipart)
\&   * Type                   (e.g., "image/jpeg")
\&   * From, To, and Subject  (if this is the "top level" of a message)
.Ve
.Sp
The \s-1PARAMHASH\s0 can contain the following keys:
.RS 4
.IP "(fieldname)" 4
.IX Item "(fieldname)"
Any field you want placed in the message header, taken from the
standard list of header fields (you don't need to worry about case):
.Sp
.Vb 6
\&    Approved      Encrypted     Received      Sender
\&    Bcc           From          References    Subject
\&    Cc            Keywords      Reply\-To      To
\&    Comments      Message\-ID    Resent\-*      X\-*
\&    Content\-*     MIME\-Version  Return\-Path
\&    Date                        Organization
.Ve
.Sp
To give experienced users some veto power, these fields will be set
\&\fIafter\fR the ones I set... so be careful: \fIdon't set any \s-1MIME\s0 fields\fR
(like \f(CW\*(C`Content\-type\*(C'\fR) unless you know what you're doing!
.Sp
To specify a fieldname that's \fInot\fR in the above list, even one that's
identical to an option below, just give it with a trailing \f(CW":"\fR,
like \f(CW"My\-field:"\fR.  When in doubt, that \fIalways\fR signals a mail
field (and it sort of looks like one too).
.IP "Data" 4
.IX Item "Data"
\&\fIAlternative to \*(L"Path\*(R" or \*(L"\s-1FH\*(R".\s0\fR
The actual message data.  This may be a scalar or a ref to an array of
strings; if the latter, the message consists of a simple concatenation
of all the strings in the array.
.IP "Datestamp" 4
.IX Item "Datestamp"
\&\fIOptional.\fR
If given true (or omitted), we force the creation of a \f(CW\*(C`Date:\*(C'\fR field
stamped with the current date/time if this is a top-level message.
You may want this if using \fIsend_by_smtp()\fR.
If you don't want this to be done, either provide your own Date
or explicitly set this to false.
.IP "Disposition" 4
.IX Item "Disposition"
\&\fIOptional.\fR
The content disposition, \f(CW"inline"\fR or \f(CW"attachment"\fR.
The default is \f(CW"inline"\fR.
.IP "Encoding" 4
.IX Item "Encoding"
\&\fIOptional.\fR
The content transfer encoding that should be used to encode your data:
.Sp
.Vb 6
\&   Use encoding:     | If your message contains:
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&   7bit              | Only 7\-bit text, all lines <1000 characters
\&   8bit              | 8\-bit text, all lines <1000 characters
\&   quoted\-printable  | 8\-bit text or long lines (more reliable than "8bit")
\&   base64            | Largely non\-textual data: a GIF, a tar file, etc.
.Ve
.Sp
The default is taken from the Type; generally it is \*(L"binary\*(R" (no
encoding) for text/*, message/*, and multipart/*, and \*(L"base64\*(R" for
everything else.  A value of \f(CW"binary"\fR is generally \fInot\fR suitable
for sending anything but \s-1ASCII\s0 text files with lines under 1000
characters, so consider using one of the other values instead.
.Sp
In the case of \*(L"7bit\*(R"/\*(L"8bit\*(R", long lines are automatically chopped to
legal length; in the case of \*(L"7bit\*(R", all 8\-bit characters are
automatically \fIremoved\fR.  This may not be what you want, so pick your
encoding well!  For more info, see \*(L"A \s-1MIME PRIMER\*(R"\s0.
.IP "\s-1FH\s0" 4
.IX Item "FH"
\&\fIAlternative to \*(L"Data\*(R" or \*(L"Path\*(R".\fR
Filehandle containing the data, opened for reading.
See \*(L"ReadNow\*(R" also.
.IP "Filename" 4
.IX Item "Filename"
\&\fIOptional.\fR
The name of the attachment.  You can use this to supply a
recommended filename for the end-user who is saving the attachment
to disk.  You only need this if the filename at the end of the
\&\*(L"Path\*(R" is inadequate, or if you're using \*(L"Data\*(R" instead of \*(L"Path\*(R".
You should \fInot\fR put path information in here (e.g., no \*(L"/\*(R"
or \*(L"\e\*(R" or \*(L":\*(R" characters should be used).
.IP "Id" 4
.IX Item "Id"
\&\fIOptional.\fR
Same as setting \*(L"content-id\*(R".
.IP "Length" 4
.IX Item "Length"
\&\fIOptional.\fR
Set the content length explicitly.  Normally, this header is automatically
computed, but only under certain circumstances (see \*(L"Benign limitations\*(R").
.IP "Path" 4
.IX Item "Path"
\&\fIAlternative to \*(L"Data\*(R" or \*(L"\s-1FH\*(R".\s0\fR
Path to a file containing the data... actually, it can be any \fIopen()\fRable
expression.  If it looks like a path, the last element will automatically
be treated as the filename.
See \*(L"ReadNow\*(R" also.
.IP "ReadNow" 4
.IX Item "ReadNow"
\&\fIOptional, for use with \*(L"Path\*(R".\fR
If true, will open the path and slurp the contents into core now.
This is useful if the Path points to a command and you don't want
to run the command over and over if outputting the message several
times.  \fBFatal exception\fR raised if the open fails.
.IP "Top" 4
.IX Item "Top"
\&\fIOptional.\fR
If defined, indicates whether or not this is a \*(L"top-level\*(R" \s-1MIME\s0 message.
The parts of a multipart message are \fInot\fR top-level.
Default is true.
.IP "Type" 4
.IX Item "Type"
\&\fIOptional.\fR
The \s-1MIME\s0 content type, or one of these special values (case-sensitive):
.Sp
.Vb 6
\&     "TEXT"   means "text/plain"
\&     "BINARY" means "application/octet\-stream"
\&     "AUTO"   means attempt to guess from the filename, falling back
\&              to \*(Aqapplication/octet\-stream\*(Aq.  This is good if you have
\&              MIME::Types on your system and you have no idea what
\&              file might be used for the attachment.
.Ve
.Sp
The default is \f(CW"TEXT"\fR, but it will be \f(CW"AUTO"\fR if you set
\&\f(CW$AUTO_CONTENT_TYPE\fR to true (sorry, but you have to enable
it explicitly, since we don't want to break code which depends
on the old behavior).
.RE
.RS 4
.Sp
A picture being worth 1000 words (which
is of course 2000 bytes, so it's probably more of an \*(L"icon\*(R" than a \*(L"picture\*(R",
but I digress...), here are some examples:
.Sp
.Vb 8
\&    $msg = MIME::Lite\->build(
\&        From     => \*(Aqyelling@inter.com\*(Aq,
\&        To       => \*(Aqstocking@fish.net\*(Aq,
\&        Subject  => "Hi there!",
\&        Type     => \*(AqTEXT\*(Aq,
\&        Encoding => \*(Aq7bit\*(Aq,
\&        Data     => "Just a quick note to say hi!"
\&    );
\&
\&    $msg = MIME::Lite\->build(
\&        From     => \*(Aqdorothy@emerald\-city.oz\*(Aq,
\&        To       => \*(Aqgesundheit@edu.edu.edu\*(Aq,
\&        Subject  => "A gif for U"
\&        Type     => \*(Aqimage/gif\*(Aq,
\&        Path     => "/home/httpd/logo.gif"
\&    );
\&
\&    $msg = MIME::Lite\->build(
\&        From     => \*(Aqlaughing@all.of.us\*(Aq,
\&        To       => \*(Aqscarlett@fiddle.dee.de\*(Aq,
\&        Subject  => "A gzipp\*(Aqed tar file",
\&        Type     => \*(Aqx\-gzip\*(Aq,
\&        Path     => "gzip < /usr/inc/somefile.tar |",
\&        ReadNow  => 1,
\&        Filename => "somefile.tgz"
\&    );
.Ve
.Sp
To show you what's really going on, that last example could also
have been written:
.Sp
.Vb 10
\&    $msg = new MIME::Lite;
\&    $msg\->build(
\&        Type     => \*(Aqx\-gzip\*(Aq,
\&        Path     => "gzip < /usr/inc/somefile.tar |",
\&        ReadNow  => 1,
\&        Filename => "somefile.tgz"
\&    );
\&    $msg\->add(From    => "laughing@all.of.us");
\&    $msg\->add(To      => "scarlett@fiddle.dee.de");
\&    $msg\->add(Subject => "A gzipp\*(Aqed tar file");
.Ve
.RE
.SS "Setting/getting headers and attributes"
.IX Subsection "Setting/getting headers and attributes"
.IP "add \s-1TAG,VALUE\s0" 4
.IX Item "add TAG,VALUE"
\&\fIInstance method.\fR
Add field \s-1TAG\s0 with the given \s-1VALUE\s0 to the end of the header.
The \s-1TAG\s0 will be converted to all-lowercase, and the \s-1VALUE\s0
will be made \*(L"safe\*(R" (returns will be given a trailing space).
.Sp
\&\fBBeware:\fR any \s-1MIME\s0 fields you \*(L"add\*(R" will override any \s-1MIME\s0
attributes I have when it comes time to output those fields.
Normally, you will use this method to add \fInon-MIME\fR fields:
.Sp
.Vb 1
\&    $msg\->add("Subject" => "Hi there!");
.Ve
.Sp
Giving \s-1VALUE\s0 as an arrayref will cause all those values to be added.
This is only useful for special multiple-valued fields like \*(L"Received\*(R":
.Sp
.Vb 1
\&    $msg\->add("Received" => ["here", "there", "everywhere"]
.Ve
.Sp
Giving \s-1VALUE\s0 as the empty string adds an invisible placeholder
to the header, which can be used to suppress the output of
the \*(L"Content\-*\*(R" fields or the special  \*(L"MIME-Version\*(R" field.
When suppressing fields, you should use \fIreplace()\fR instead of \fIadd()\fR:
.Sp
.Vb 1
\&    $msg\->replace("Content\-disposition" => "");
.Ve
.Sp
\&\fINote:\fR \fIadd()\fR is probably going to be more efficient than \f(CW\*(C`replace()\*(C'\fR,
so you're better off using it for most applications if you are
certain that you don't need to \fIdelete()\fR the field first.
.Sp
\&\fINote:\fR the name comes from Mail::Header.
.IP "attr \s-1ATTR\s0,[\s-1VALUE\s0]" 4
.IX Item "attr ATTR,[VALUE]"
\&\fIInstance method.\fR
Set \s-1MIME\s0 attribute \s-1ATTR\s0 to the string \s-1VALUE.
ATTR\s0 is converted to all-lowercase.
This method is normally used to set/get \s-1MIME\s0 attributes:
.Sp
.Vb 3
\&    $msg\->attr("content\-type"         => "text/html");
\&    $msg\->attr("content\-type.charset" => "US\-ASCII");
\&    $msg\->attr("content\-type.name"    => "homepage.html");
.Ve
.Sp
This would cause the final output to look something like this:
.Sp
.Vb 1
\&    Content\-type: text/html; charset=US\-ASCII; name="homepage.html"
.Ve
.Sp
Note that the special empty sub-field tag indicates the anonymous
first sub-field.
.Sp
Giving \s-1VALUE\s0 as undefined will cause the contents of the named
subfield to be deleted.
.Sp
Supplying no \s-1VALUE\s0 argument just returns the attribute's value:
.Sp
.Vb 2
\&    $type = $msg\->attr("content\-type");        ### returns "text/html"
\&    $name = $msg\->attr("content\-type.name");   ### returns "homepage.html"
.Ve
.IP "delete \s-1TAG\s0" 4
.IX Item "delete TAG"
\&\fIInstance method.\fR
Delete field \s-1TAG\s0 with the given \s-1VALUE\s0 to the end of the header.
The \s-1TAG\s0 will be converted to all-lowercase.
.Sp
.Vb 1
\&    $msg\->delete("Subject");
.Ve
.Sp
\&\fINote:\fR the name comes from Mail::Header.
.IP "field_order \s-1FIELD,...FIELD\s0" 4
.IX Item "field_order FIELD,...FIELD"
\&\fIClass/instance method.\fR
Change the order in which header fields are output for this object:
.Sp
.Vb 1
\&    $msg\->field_order(\*(Aqfrom\*(Aq, \*(Aqto\*(Aq, \*(Aqcontent\-type\*(Aq, \*(Aqsubject\*(Aq);
.Ve
.Sp
When used as a class method, changes the default settings for
all objects:
.Sp
.Vb 1
\&    MIME::Lite\->field_order(\*(Aqfrom\*(Aq, \*(Aqto\*(Aq, \*(Aqcontent\-type\*(Aq, \*(Aqsubject\*(Aq);
.Ve
.Sp
Case does not matter: all field names will be coerced to lowercase.
In either case, supply the empty array to restore the default ordering.
.IP "fields" 4
.IX Item "fields"
\&\fIInstance method.\fR
Return the full header for the object, as a ref to an array
of \f(CW\*(C`[TAG, VALUE]\*(C'\fR pairs, where each \s-1TAG\s0 is all-lowercase.
Note that any fields the user has explicitly set will override the
corresponding \s-1MIME\s0 fields that we would otherwise generate.
So, don't say...
.Sp
.Vb 1
\&    $msg\->set("Content\-type" => "text/html; charset=US\-ASCII");
.Ve
.Sp
unless you want the above value to override the \*(L"Content-type\*(R"
\&\s-1MIME\s0 field that we would normally generate.
.Sp
\&\fINote:\fR I called this \*(L"fields\*(R" because the \fIheader()\fR method of
Mail::Header returns something different, but similar enough to
be confusing.
.Sp
You can change the order of the fields: see \*(L"field_order\*(R".
You really shouldn't need to do this, but some people have to
deal with broken mailers.
.IP "filename [\s-1FILENAME\s0]" 4
.IX Item "filename [FILENAME]"
\&\fIInstance method.\fR
Set the filename which this data will be reported as.
This actually sets both \*(L"standard\*(R" attributes.
.Sp
With no argument, returns the filename as dictated by the
content-disposition.
.IP "get \s-1TAG\s0,[\s-1INDEX\s0]" 4
.IX Item "get TAG,[INDEX]"
\&\fIInstance method.\fR
Get the contents of field \s-1TAG,\s0 which might have been set
with \fIset()\fR or \fIreplace()\fR.  Returns the text of the field.
.Sp
.Vb 1
\&    $ml\->get(\*(AqSubject\*(Aq, 0);
.Ve
.Sp
If the optional 0\-based \s-1INDEX\s0 is given, then we return the \s-1INDEX\s0'th
occurrence of field \s-1TAG. \s0 Otherwise, we look at the context:
In a scalar context, only the first (0th) occurrence of the
field is returned; in an array context, \fIall\fR occurrences are returned.
.Sp
\&\fIWarning:\fR this should only be used with non-MIME fields.
Behavior with \s-1MIME\s0 fields is \s-1TBD,\s0 and will raise an exception for now.
.IP "get_length" 4
.IX Item "get_length"
\&\fIInstance method.\fR
Recompute the content length for the message \fIif the process is trivial\fR,
setting the \*(L"content-length\*(R" attribute as a side-effect:
.Sp
.Vb 1
\&    $msg\->get_length;
.Ve
.Sp
Returns the length, or undefined if not set.
.Sp
\&\fINote:\fR the content length can be difficult to compute, since it
involves assembling the entire encoded body and taking the length
of it (which, in the case of multipart messages, means freezing
all the sub-parts, etc.).
.Sp
This method only sets the content length to a defined value if the
message is a singlepart with \f(CW"binary"\fR encoding, \fIand\fR the body is
available either in-core or as a simple file.  Otherwise, the content
length is set to the undefined value.
.Sp
Since content-length is not a standard \s-1MIME\s0 field anyway (that's right, kids:
it's not in the \s-1MIME\s0 RFCs, it's an \s-1HTTP\s0 thing), this seems pretty fair.
.IP "parts" 4
.IX Item "parts"
\&\fIInstance method.\fR
Return the parts of this entity, and this entity only.
Returns empty array if this entity has no parts.
.Sp
This is \fBnot\fR recursive!  Parts can have sub-parts; use
\&\fIparts_DFS()\fR to get everything.
.IP "parts_DFS" 4
.IX Item "parts_DFS"
\&\fIInstance method.\fR
Return the list of all MIME::Lite objects included in the entity,
starting with the entity itself, in depth-first-search order.
If this object has no parts, it alone will be returned.
.IP "preamble [\s-1TEXT\s0]" 4
.IX Item "preamble [TEXT]"
\&\fIInstance method.\fR
Get/set the preamble string, assuming that this object has subparts.
Set it to undef for the default string.
.IP "replace \s-1TAG,VALUE\s0" 4
.IX Item "replace TAG,VALUE"
\&\fIInstance method.\fR
Delete all occurrences of fields named \s-1TAG,\s0 and add a new
field with the given \s-1VALUE.  TAG\s0 is converted to all-lowercase.
.Sp
\&\fBBeware\fR the special \s-1MIME\s0 fields (MIME-version, Content\-*):
if you \*(L"replace\*(R" a \s-1MIME\s0 field, the replacement text will override
the \fIactual\fR \s-1MIME\s0 attributes when it comes time to output that field.
So normally you use \fIattr()\fR to change \s-1MIME\s0 fields and \fIadd()\fR/\fIreplace()\fR to
change \fInon-MIME\fR fields:
.Sp
.Vb 1
\&    $msg\->replace("Subject" => "Hi there!");
.Ve
.Sp
Giving \s-1VALUE\s0 as the \fIempty string\fR will effectively \fIprevent\fR that
field from being output.  This is the correct way to suppress
the special \s-1MIME\s0 fields:
.Sp
.Vb 1
\&    $msg\->replace("Content\-disposition" => "");
.Ve
.Sp
Giving \s-1VALUE\s0 as \fIundefined\fR will just cause all explicit values
for \s-1TAG\s0 to be deleted, without having any new values added.
.Sp
\&\fINote:\fR the name of this method  comes from Mail::Header.
.IP "scrub" 4
.IX Item "scrub"
\&\fIInstance method.\fR
\&\fBThis is Alpha code.  If you use it, please let me know how it goes.\fR
Recursively goes through the \*(L"parts\*(R" tree of this message and tries
to find \s-1MIME\s0 attributes that can be removed.
With an array argument, removes exactly those attributes; e.g.:
.Sp
.Vb 1
\&    $msg\->scrub([\*(Aqcontent\-disposition\*(Aq, \*(Aqcontent\-length\*(Aq]);
.Ve
.Sp
Is the same as recursively doing:
.Sp
.Vb 2
\&    $msg\->replace(\*(AqContent\-disposition\*(Aq => \*(Aq\*(Aq);
\&    $msg\->replace(\*(AqContent\-length\*(Aq      => \*(Aq\*(Aq);
.Ve
.SS "Setting/getting message data"
.IX Subsection "Setting/getting message data"
.IP "binmode [\s-1OVERRIDE\s0]" 4
.IX Item "binmode [OVERRIDE]"
\&\fIInstance method.\fR
With no argument, returns whether or not it thinks that the data
(as given by the \*(L"Path\*(R" argument of \f(CW\*(C`build()\*(C'\fR) should be read using
\&\fIbinmode()\fR (for example, when \f(CW\*(C`read_now()\*(C'\fR is invoked).
.Sp
The default behavior is that any content type other than
\&\f(CW\*(C`text/*\*(C'\fR or \f(CW\*(C`message/*\*(C'\fR is binmode'd; this should in general work fine.
.Sp
With a defined argument, this method sets an explicit \*(L"override\*(R"
value.  An undefined argument unsets the override.
The new current value is returned.
.IP "data [\s-1DATA\s0]" 4
.IX Item "data [DATA]"
\&\fIInstance method.\fR
Get/set the literal \s-1DATA\s0 of the message.  The \s-1DATA\s0 may be
either a scalar, or a reference to an array of scalars (which
will simply be joined).
.Sp
\&\fIWarning:\fR setting the data causes the \*(L"content-length\*(R" attribute
to be recomputed (possibly to nothing).
.IP "fh [\s-1FILEHANDLE\s0]" 4
.IX Item "fh [FILEHANDLE]"
\&\fIInstance method.\fR
Get/set the \s-1FILEHANDLE\s0 which contains the message data.
.Sp
Takes a filehandle as an input and stores it in the object.
This routine is similar to \fIpath()\fR; one important difference is that
no attempt is made to set the content length.
.IP "path [\s-1PATH\s0]" 4
.IX Item "path [PATH]"
\&\fIInstance method.\fR
Get/set the \s-1PATH\s0 to the message data.
.Sp
\&\fIWarning:\fR setting the path recomputes any existing \*(L"content-length\*(R" field,
and re-sets the \*(L"filename\*(R" (to the last element of the path if it
looks like a simple path, and to nothing if not).
.IP "resetfh [\s-1FILEHANDLE\s0]" 4
.IX Item "resetfh [FILEHANDLE]"
\&\fIInstance method.\fR
Set the current position of the filehandle back to the beginning.
Only applies if you used \*(L"\s-1FH\*(R"\s0 in \fIbuild()\fR or \fIattach()\fR for this message.
.Sp
Returns false if unable to reset the filehandle (since not all filehandles
are seekable).
.IP "read_now" 4
.IX Item "read_now"
\&\fIInstance method.\fR
Forces data from the path/filehandle (as specified by \f(CW\*(C`build()\*(C'\fR)
to be read into core immediately, just as though you had given it
literally with the \f(CW\*(C`Data\*(C'\fR keyword.
.Sp
Note that the in-core data will always be used if available.
.Sp
Be aware that everything is slurped into a giant scalar: you may not want
to use this if sending tar files!  The benefit of \fInot\fR reading in the data
is that very large files can be handled by this module if left on disk
until the message is output via \f(CW\*(C`print()\*(C'\fR or \f(CW\*(C`print_body()\*(C'\fR.
.IP "sign \s-1PARAMHASH\s0" 4
.IX Item "sign PARAMHASH"
\&\fIInstance method.\fR
Sign the message.  This forces the message to be read into core,
after which the signature is appended to it.
.RS 4
.IP "Data" 4
.IX Item "Data"
As in \f(CW\*(C`build()\*(C'\fR: the literal signature data.
Can be either a scalar or a ref to an array of scalars.
.IP "Path" 4
.IX Item "Path"
As in \f(CW\*(C`build()\*(C'\fR: the path to the file.
.RE
.RS 4
.Sp
If no arguments are given, the default is:
.Sp
.Vb 1
\&    Path => "$ENV{HOME}/.signature"
.Ve
.Sp
The content-length is recomputed.
.RE
.IP "verify_data" 4
.IX Item "verify_data"
\&\fIInstance method.\fR
Verify that all \*(L"paths\*(R" to attached data exist, recursively.
It might be a good idea for you to do this before a \fIprint()\fR, to
prevent accidental partial output if a file might be missing.
Raises exception if any path is not readable.
.SS "Output"
.IX Subsection "Output"
.IP "print [\s-1OUTHANDLE\s0]" 4
.IX Item "print [OUTHANDLE]"
\&\fIInstance method.\fR
Print the message to the given output handle, or to the currently-selected
filehandle if none was given.
.Sp
All \s-1OUTHANDLE\s0 has to be is a filehandle (possibly a glob ref), or
any object that responds to a \fIprint()\fR message.
.IP "print_body [\s-1OUTHANDLE\s0] [\s-1IS_SMTP\s0]" 4
.IX Item "print_body [OUTHANDLE] [IS_SMTP]"
\&\fIInstance method.\fR
Print the body of a message to the given output handle, or to
the currently-selected filehandle if none was given.
.Sp
All \s-1OUTHANDLE\s0 has to be is a filehandle (possibly a glob ref), or
any object that responds to a \fIprint()\fR message.
.Sp
\&\fBFatal exception\fR raised if unable to open any of the input files,
or if a part contains no data, or if an unsupported encoding is
encountered.
.Sp
\&\s-1IS_SMPT\s0 is a special option to handle \s-1SMTP\s0 mails a little more
intelligently than other send mechanisms may require. Specifically this
ensures that the last byte sent is \s-1NOT \s0'\en' (octal \e012) if the last two
bytes are not '\er\en' (\e015\e012) as this will cause some \s-1SMTP\s0 servers to
hang.
.IP "print_header [\s-1OUTHANDLE\s0]" 4
.IX Item "print_header [OUTHANDLE]"
\&\fIInstance method.\fR
Print the header of the message to the given output handle,
or to the currently-selected filehandle if none was given.
.Sp
All \s-1OUTHANDLE\s0 has to be is a filehandle (possibly a glob ref), or
any object that responds to a \fIprint()\fR message.
.IP "as_string" 4
.IX Item "as_string"
\&\fIInstance method.\fR
Return the entire message as a string, with a header and an encoded body.
.IP "body_as_string" 4
.IX Item "body_as_string"
\&\fIInstance method.\fR
Return the encoded body as a string.
This is the portion after the header and the blank line.
.Sp
\&\fINote:\fR actually prepares the body by \*(L"printing\*(R" to a scalar.
Proof that you can hand the \f(CW\*(C`print*()\*(C'\fR methods any blessed object
that responds to a \f(CW\*(C`print()\*(C'\fR message.
.IP "header_as_string" 4
.IX Item "header_as_string"
\&\fIInstance method.\fR
Return the header as a string.
.SS "Sending"
.IX Subsection "Sending"
.IP "send" 4
.IX Item "send"
.PD 0
.IP "send \s-1HOW, HOWARGS...\s0" 4
.IX Item "send HOW, HOWARGS..."
.PD
\&\fIClass/instance method.\fR
This is the principal method for sending mail, and for configuring
how mail will be sent.
.Sp
\&\fIAs a class method\fR with a \s-1HOW\s0 argument and optional \s-1HOWARGS,\s0 it sets
the default sending mechanism that the no-argument instance method
will use.  The \s-1HOW\s0 is a facility name (\fBsee below\fR),
and the \s-1HOWARGS\s0 is interpreted by the facility.
The class method returns the previous \s-1HOW\s0 and \s-1HOWARGS\s0 as an array.
.Sp
.Vb 4
\&    MIME::Lite\->send(\*(Aqsendmail\*(Aq, "d:\e\eprograms\e\esendmail.exe");
\&    ...
\&    $msg = MIME::Lite\->new(...);
\&    $msg\->send;
.Ve
.Sp
\&\fIAs an instance method with arguments\fR
(a \s-1HOW\s0 argument and optional \s-1HOWARGS\s0), sends the message in the
requested manner; e.g.:
.Sp
.Vb 1
\&    $msg\->send(\*(Aqsendmail\*(Aq, "d:\e\eprograms\e\esendmail.exe");
.Ve
.Sp
\&\fIAs an instance method with no arguments,\fR sends the
message by the default mechanism set up by the class method.
Returns whatever the mail-handling routine returns: this
should be true on success, false/exception on error:
.Sp
.Vb 2
\&    $msg = MIME::Lite\->new(From=>...);
\&    $msg\->send || die "you DON\*(AqT have mail!";
.Ve
.Sp
On Unix systems (or rather non\-Win32 systems), the default
setting is equivalent to:
.Sp
.Vb 1
\&    MIME::Lite\->send("sendmail", "/usr/lib/sendmail \-t \-oi \-oem");
.Ve
.Sp
On Win32 systems the default setting is equivalent to:
.Sp
.Vb 1
\&    MIME::Lite\->send("smtp");
.Ve
.Sp
The assumption is that on Win32 your site/lib/Net/libnet.cfg
file will be preconfigured to use the appropriate \s-1SMTP\s0
server. See below for configuring for authentication.
.Sp
There are three facilities:
.RS 4
.ie n .IP """sendmail"", \s-1ARGS...\s0" 4
.el .IP "``sendmail'', \s-1ARGS...\s0" 4
.IX Item "sendmail, ARGS..."
Send a message by piping it into the \*(L"sendmail\*(R" command.
Uses the \fIsend_by_sendmail()\fR method, giving it the \s-1ARGS.\s0
This usage implements (and deprecates) the \f(CW\*(C`sendmail()\*(C'\fR method.
.ie n .IP """smtp"", [\s-1HOSTNAME,\s0 [\s-1NAMEDPARMS\s0] ]" 4
.el .IP "``smtp'', [\s-1HOSTNAME,\s0 [\s-1NAMEDPARMS\s0] ]" 4
.IX Item "smtp, [HOSTNAME, [NAMEDPARMS] ]"
Send a message by \s-1SMTP,\s0 using optional \s-1HOSTNAME\s0 as SMTP-sending host.
Net::SMTP will be required.  Uses the \fIsend_by_smtp()\fR
method. Any additional arguments passed in will also be passed through to
send_by_smtp.  This is useful for things like mail servers requiring
authentication where you can say something like the following
.Sp
.Vb 1
\&  MIME::Lite\->send(\*(Aqsmtp\*(Aq, $host, AuthUser=>$user, AuthPass=>$pass);
.Ve
.Sp
which will configure things so future uses of
.Sp
.Vb 1
\&  $msg\->send();
.Ve
.Sp
do the right thing.
.ie n .IP """sub"", \e&SUBREF, \s-1ARGS...\s0" 4
.el .IP "``sub'', \e&SUBREF, \s-1ARGS...\s0" 4
.IX Item "sub, &SUBREF, ARGS..."
Sends a message \s-1MSG\s0 by invoking the subroutine \s-1SUBREF\s0 of your choosing,
with \s-1MSG\s0 as the first argument, and \s-1ARGS\s0 following.
.RE
.RS 4
.Sp
\&\fIFor example:\fR let's say you're on an \s-1OS\s0 which lacks the usual Unix
\&\*(L"sendmail\*(R" facility, but you've installed something a lot like it, and
you need to configure your Perl script to use this \*(L"sendmail.exe\*(R" program.
Do this following in your script's setup:
.Sp
.Vb 1
\&    MIME::Lite\->send(\*(Aqsendmail\*(Aq, "d:\e\eprograms\e\esendmail.exe");
.Ve
.Sp
Then, whenever you need to send a message \f(CW$msg\fR, just say:
.Sp
.Vb 1
\&    $msg\->send;
.Ve
.Sp
That's it.  Now, if you ever move your script to a Unix box, all you
need to do is change that line in the setup and you're done.
All of your \f(CW$msg\fR\->send invocations will work as expected.
.Sp
After sending, the method \fIlast_send_successful()\fR can be used to determine
if the send was successful or not.
.RE
.IP "send_by_sendmail \s-1SENDMAILCMD\s0" 4
.IX Item "send_by_sendmail SENDMAILCMD"
.PD 0
.IP "send_by_sendmail PARAM=>\s-1VALUE, ARRAY, HASH...\s0" 4
.IX Item "send_by_sendmail PARAM=>VALUE, ARRAY, HASH..."
.PD
\&\fIInstance method.\fR
Send message via an external \*(L"sendmail\*(R" program
(this will probably only work out-of-the-box on Unix systems).
.Sp
Returns true on success, false or exception on error.
.Sp
You can specify the program and all its arguments by giving a single
string, \s-1SENDMAILCMD. \s0 Nothing fancy is done; the message is simply
piped in.
.Sp
However, if your needs are a little more advanced, you can specify
zero or more of the following \s-1PARAM/VALUE\s0 pairs (or a reference to hash
or array of such arguments as well as any combination thereof); a
Unix-style, taint-safe \*(L"sendmail\*(R" command will be constructed for you:
.RS 4
.IP "Sendmail" 4
.IX Item "Sendmail"
Full path to the program to use.
Default is \*(L"/usr/lib/sendmail\*(R".
.IP "BaseArgs" 4
.IX Item "BaseArgs"
Ref to the basic array of arguments we start with.
Default is \f(CW\*(C`["\-t", "\-oi", "\-oem"]\*(C'\fR.
.IP "SetSender" 4
.IX Item "SetSender"
Unless this is \fIexplicitly\fR given as false, we attempt to automatically
set the \f(CW\*(C`\-f\*(C'\fR argument to the first address that can be extracted from
the \*(L"From:\*(R" field of the message (if there is one).
.Sp
\&\fIWhat is the \-f, and why do we use it?\fR
Suppose we did \fInot\fR use \f(CW\*(C`\-f\*(C'\fR, and you gave an explicit \*(L"From:\*(R"
field in your message: in this case, the sendmail \*(L"envelope\*(R" would
indicate the \fIreal\fR user your process was running under, as a way
of preventing mail forgery.  Using the \f(CW\*(C`\-f\*(C'\fR switch causes the sender
to be set in the envelope as well.
.Sp
\&\fISo when would I \s-1NOT\s0 want to use it?\fR
If sendmail doesn't regard you as a \*(L"trusted\*(R" user, it will permit
the \f(CW\*(C`\-f\*(C'\fR but also add an \*(L"X\-Authentication-Warning\*(R" header to the message
to indicate a forged envelope.  To avoid this, you can either
(1) have SetSender be false, or
(2) make yourself a trusted user by adding a \f(CW\*(C`T\*(C'\fR configuration
    command to your \fIsendmail.cf\fR file
    (e.g.: \f(CW\*(C`Teryq\*(C'\fR if the script is running as user \*(L"eryq\*(R").
.IP "FromSender" 4
.IX Item "FromSender"
If defined, this is identical to setting SetSender to true,
except that instead of looking at the \*(L"From:\*(R" field we use
the address given by this option.
Thus:
.Sp
.Vb 1
\&    FromSender => \*(Aqme@myhost.com\*(Aq
.Ve
.RE
.RS 4
.Sp
After sending, the method \fIlast_send_successful()\fR can be used to determine
if the send was successful or not.
.RE
.IP "send_by_smtp \s-1HOST, ARGS...\s0" 4
.IX Item "send_by_smtp HOST, ARGS..."
.PD 0
.IP "send_by_smtp \s-1REF, HOST, ARGS\s0" 4
.IX Item "send_by_smtp REF, HOST, ARGS"
.PD
\&\fIInstance method.\fR
Send message via \s-1SMTP,\s0 using Net::SMTP \*(-- which will be required for this
feature.
.Sp
\&\s-1HOST\s0 is the name of \s-1SMTP\s0 server to connect to, or undef to have
Net::SMTP use the defaults in Libnet.cfg.
.Sp
\&\s-1ARGS\s0 are a list of key value pairs which may be selected from the list
below. Many of these are just passed through to specific
Net::SMTP commands and you should review that module for
details.
.Sp
Please see Good-vs-bad email addresses with \fIsend_by_smtp()\fR
.RS 4
.IP "Hello" 4
.IX Item "Hello"
.PD 0
.IP "LocalAddr" 4
.IX Item "LocalAddr"
.IP "LocalPort" 4
.IX Item "LocalPort"
.IP "Timeout" 4
.IX Item "Timeout"
.IP "Port" 4
.IX Item "Port"
.IP "ExactAddresses" 4
.IX Item "ExactAddresses"
.IP "Debug" 4
.IX Item "Debug"
.PD
See \fINet::SMTP::new()\fR for details.
.IP "Size" 4
.IX Item "Size"
.PD 0
.IP "Return" 4
.IX Item "Return"
.IP "Bits" 4
.IX Item "Bits"
.IP "Transaction" 4
.IX Item "Transaction"
.IP "Envelope" 4
.IX Item "Envelope"
.PD
See \fINet::SMTP::mail()\fR for details.
.IP "SkipBad" 4
.IX Item "SkipBad"
If true doesn't throw an error when multiple email addresses are provided
and some are not valid. See \fINet::SMTP::recipient()\fR
for details.
.IP "AuthUser" 4
.IX Item "AuthUser"
Authenticate with \fINet::SMTP::auth()\fR using this username.
.IP "AuthPass" 4
.IX Item "AuthPass"
Authenticate with \fINet::SMTP::auth()\fR using this password.
.IP "NoAuth" 4
.IX Item "NoAuth"
Normally if AuthUser and AuthPass are defined MIME::Lite will attempt to
use them with the \fINet::SMTP::auth()\fR command to
authenticate the connection, however if this value is true then no
authentication occurs.
.IP "To" 4
.IX Item "To"
Sets the addresses to send to. Can be a string or a reference to an
array of strings. Normally this is extracted from the To: (and Cc: and
Bcc: fields if \f(CW$AUTO_CC\fR is true).
.Sp
This value overrides that.
.IP "From" 4
.IX Item "From"
Sets the email address to send from. Normally this value is extracted
from the Return-Path: or From: field of the mail itself (in that order).
.Sp
This value overrides that.
.RE
.RS 4
.Sp
\&\fIReturns:\fR
True on success, croaks with an error message on failure.
.Sp
After sending, the method \fIlast_send_successful()\fR can be used to determine
if the send was successful or not.
.RE
.IP "send_by_testfile \s-1FILENAME\s0" 4
.IX Item "send_by_testfile FILENAME"
\&\fIInstance method.\fR
Print message to a file (namely \s-1FILENAME\s0), which will default to
mailer.testfile
If file exists, message will be appended.
.IP "last_send_successful" 4
.IX Item "last_send_successful"
This method will return \s-1TRUE\s0 if the last \fIsend()\fR or \fIsend_by_XXX()\fR method call was
successful. It will return defined but false if it was not successful, and undefined
if the object had not been used to send yet.
.IP "sendmail \s-1COMMAND...\s0" 4
.IX Item "sendmail COMMAND..."
\&\fIClass method, \s-1DEPRECATED.\s0\fR
Declare the sender to be \*(L"sendmail\*(R", and set up the \*(L"sendmail\*(R" command.
\&\fIYou should use \fIsend()\fI instead.\fR
.SS "Miscellaneous"
.IX Subsection "Miscellaneous"
.IP "quiet \s-1ONOFF\s0" 4
.IX Item "quiet ONOFF"
\&\fIClass method.\fR
Suppress/unsuppress all warnings coming from this module.
.Sp
.Vb 1
\&    MIME::Lite\->quiet(1);       ### I know what I\*(Aqm doing
.Ve
.Sp
I recommend that you include that comment as well.  And while
you type it, say it out loud: if it doesn't feel right, then maybe
you should reconsider the whole line.  \f(CW\*(C`;\-)\*(C'\fR
.SH "NOTES"
.IX Header "NOTES"
.ie n .SS "How do I prevent ""Content"" headers from showing up in my mail reader?"
.el .SS "How do I prevent ``Content'' headers from showing up in my mail reader?"
.IX Subsection "How do I prevent Content headers from showing up in my mail reader?"
Apparently, some people are using mail readers which display the \s-1MIME\s0
headers like \*(L"Content-disposition\*(R", and they want MIME::Lite not
to generate them \*(L"because they look ugly\*(R".
.PP
Sigh.
.PP
Y'know, kids, those headers aren't just there for cosmetic purposes.
They help ensure that the message is \fIunderstood\fR correctly by mail
readers.  But okay, you asked for it, you got it...
here's how you can suppress the standard \s-1MIME\s0 headers.
Before you send the message, do this:
.PP
.Vb 1
\&    $msg\->scrub;
.Ve
.PP
You can \fIscrub()\fR any part of a multipart message independently;
just be aware that it works recursively.  Before you scrub,
note the rules that I follow:
.IP "Content-type" 4
.IX Item "Content-type"
You can safely scrub the \*(L"content-type\*(R" attribute if, and only if,
the part is of type \*(L"text/plain\*(R" with charset \*(L"us-ascii\*(R".
.IP "Content-transfer-encoding" 4
.IX Item "Content-transfer-encoding"
You can safely scrub the \*(L"content-transfer-encoding\*(R" attribute
if, and only if, the part uses \*(L"7bit\*(R", \*(L"8bit\*(R", or \*(L"binary\*(R" encoding.
You are far better off doing this if your lines are under 1000
characters.  Generally, that means you \fIcan\fR scrub it for plain
text, and you can \fInot\fR scrub this for images, etc.
.IP "Content-disposition" 4
.IX Item "Content-disposition"
You can safely scrub the \*(L"content-disposition\*(R" attribute
if you trust the mail reader to do the right thing when it decides
whether to show an attachment inline or as a link.  Be aware
that scrubbing both the content-disposition and the content-type
means that there is no way to \*(L"recommend\*(R" a filename for the attachment!
.Sp
\&\fBNote:\fR there are reports of brain-dead MUAs out there that
do the wrong thing if you \fIprovide\fR the content-disposition.
If your attachments keep showing up inline or vice-versa,
try scrubbing this attribute.
.IP "Content-length" 4
.IX Item "Content-length"
You can always scrub \*(L"content-length\*(R" safely.
.SS "How do I give my attachment a [different] recommended filename?"
.IX Subsection "How do I give my attachment a [different] recommended filename?"
By using the Filename option (which is different from Path!):
.PP
.Vb 3
\&    $msg\->attach(Type => "image/gif",
\&                 Path => "/here/is/the/real/file.GIF",
\&                 Filename => "logo.gif");
.Ve
.PP
You should \fInot\fR put path information in the Filename.
.SS "Benign limitations"
.IX Subsection "Benign limitations"
This is \*(L"lite\*(R", after all...
.IP "\(bu" 4
There's no parsing.  Get MIME-tools if you need to parse \s-1MIME\s0 messages.
.IP "\(bu" 4
MIME::Lite messages are currently \fInot\fR interchangeable with
either Mail::Internet or MIME::Entity objects.  This is a completely
separate module.
.IP "\(bu" 4
A content-length field is only inserted if the encoding is binary,
the message is a singlepart, and all the document data is available
at \f(CW\*(C`build()\*(C'\fR time by virtue of residing in a simple path, or in-core.
Since content-length is not a standard \s-1MIME\s0 field anyway (that's right, kids:
it's not in the \s-1MIME\s0 RFCs, it's an \s-1HTTP\s0 thing), this seems pretty fair.
.IP "\(bu" 4
MIME::Lite alone cannot help you lose weight.  You must supplement
your use of MIME::Lite with a healthy diet and exercise.
.SS "Cheap and easy mailing"
.IX Subsection "Cheap and easy mailing"
I thought putting in a default \*(L"sendmail\*(R" invocation wasn't too bad an
idea, since a lot of Perlers are on \s-1UNIX\s0 systems. (As of version 3.02 this is
default only on Non\-Win32 boxen. On Win32 boxen the default is to use \s-1SMTP\s0 and the
defaults specified in the site/lib/Net/libnet.cfg)
.PP
The out-of-the-box configuration is:
.PP
.Vb 1
\&     MIME::Lite\->send(\*(Aqsendmail\*(Aq, "/usr/lib/sendmail \-t \-oi \-oem");
.Ve
.PP
By the way, these arguments to sendmail are:
.PP
.Vb 1
\&     \-t      Scan message for To:, Cc:, Bcc:, etc.
\&
\&     \-oi     Do NOT treat a single "." on a line as a message terminator.
\&             As in, "\-oi vey, it truncated my message... why?!"
\&
\&     \-oem    On error, mail back the message (I assume to the
\&             appropriate address, given in the header).
\&             When mail returns, circle is complete.  Jai Guru Deva \-oem.
.Ve
.PP
Note that these are the same arguments you get if you configure to use
the smarter, taint-safe mailing:
.PP
.Vb 1
\&     MIME::Lite\->send(\*(Aqsendmail\*(Aq);
.Ve
.PP
If you get \*(L"X\-Authentication-Warning\*(R" headers from this, you can forgo
diddling with the envelope by instead specifying:
.PP
.Vb 1
\&     MIME::Lite\->send(\*(Aqsendmail\*(Aq, SetSender=>0);
.Ve
.PP
And, if you're not on a Unix system, or if you'd just rather send mail
some other way, there's always \s-1SMTP,\s0 which these days probably requires
authentication so you probably need to say
.PP
.Vb 2
\&     MIME::Lite\->send(\*(Aqsmtp\*(Aq, "smtp.myisp.net",
\&        AuthUser=>"YourName",AuthPass=>"YourPass" );
.Ve
.PP
Or you can set up your own subroutine to call.
In any case, check out the \fIsend()\fR method.
.SH "WARNINGS"
.IX Header "WARNINGS"
.SS "Good-vs-bad email addresses with \fIsend_by_smtp()\fP"
.IX Subsection "Good-vs-bad email addresses with send_by_smtp()"
If using \fIsend_by_smtp()\fR, be aware that unless you
explicitly provide the email addresses to send to and from you will be
forcing MIME::Lite to extract email addresses out of a possible list
provided in the \f(CW\*(C`To:\*(C'\fR, \f(CW\*(C`Cc:\*(C'\fR, and \f(CW\*(C`Bcc:\*(C'\fR fields.  This is tricky
stuff, and as such only the following sorts of addresses will work
reliably:
.PP
.Vb 3
\&    username
\&    full.name@some.host.com
\&    "Name, Full" <full.name@some.host.com>
.Ve
.PP
\&\fBDisclaimer:\fR
MIME::Lite was never intended to be a Mail User Agent, so please
don't expect a full implementation of \s-1RFC\-822. \s0 Restrict yourself to
the common forms of Internet addresses described herein, and you should
be fine.  If this is not feasible, then consider using MIME::Lite
to \fIprepare\fR your message only, and using Net::SMTP explicitly to
\&\fIsend\fR your message.
.PP
\&\fBNote:\fR
As of MIME::Lite v3.02 the mail name extraction routines have been
beefed up considerably. Furthermore if Mail::Address if provided then
name extraction is done using that. Accordingly the above advice is now
less true than it once was. Funky email names \fIshould\fR work properly
now. However the disclaimer remains. Patches welcome. :\-)
.SS "Formatting of headers delayed until \fIprint()\fP"
.IX Subsection "Formatting of headers delayed until print()"
This class treats a \s-1MIME\s0 header in the most abstract sense,
as being a collection of high-level attributes.  The actual
RFC\-822\-style header fields are not constructed until it's time
to actually print the darn thing.
.SS "Encoding of data delayed until \fIprint()\fP"
.IX Subsection "Encoding of data delayed until print()"
When you specify message bodies
(in \fIbuild()\fR or \fIattach()\fR) \*(--
whether by \fB\s-1FH\s0\fR, \fBData\fR, or \fBPath\fR \*(-- be warned that we don't
attempt to open files, read filehandles, or encode the data until
\&\fIprint()\fR is invoked.
.PP
In the past, this created some confusion for users of sendmail
who gave the wrong path to an attachment body, since enough of
the \fIprint()\fR would succeed to get the initial part of the message out.
Nowadays, \f(CW$AUTO_VERIFY\fR is used to spot-check the Paths given before
the mail facility is employed.  A whisker slower, but tons safer.
.PP
Note that if you give a message body via \s-1FH,\s0 and try to \fIprint()\fR
a message twice, the second \fIprint()\fR will not do the right thing
unless you  explicitly rewind the filehandle.
.PP
You can get past these difficulties by using the \fBReadNow\fR option,
provided that you have enough memory to handle your messages.
.SS "\s-1MIME\s0 attributes are separate from header fields!"
.IX Subsection "MIME attributes are separate from header fields!"
\&\fBImportant:\fR the \s-1MIME\s0 attributes are stored and manipulated separately
from the message header fields; when it comes time to print the
header out, \fIany explicitly-given header fields override the ones that
would be created from the \s-1MIME\s0 attributes.\fR  That means that this:
.PP
.Vb 2
\&    ### DANGER ### DANGER ### DANGER ### DANGER ### DANGER ###
\&    $msg\->add("Content\-type", "text/html; charset=US\-ASCII");
.Ve
.PP
will set the exact \f(CW"Content\-type"\fR field in the header I write,
\&\fIregardless of what the actual \s-1MIME\s0 attributes are.\fR
.PP
\&\fIThis feature is for experienced users only,\fR as an escape hatch in case
the code that normally formats \s-1MIME\s0 header fields isn't doing what
you need.  And, like any escape hatch, it's got an alarm on it:
MIME::Lite will warn you if you attempt to \f(CW\*(C`set()\*(C'\fR or \f(CW\*(C`replace()\*(C'\fR
any \s-1MIME\s0 header field.  Use \f(CW\*(C`attr()\*(C'\fR instead.
.SS "Beware of lines consisting of a single dot"
.IX Subsection "Beware of lines consisting of a single dot"
Julian Haight noted that MIME::Lite allows you to compose messages
with lines in the body consisting of a single \*(L".\*(R".
This is true: it should be completely harmless so long as \*(L"sendmail\*(R"
is used with the \-oi option (see \*(L"Cheap and easy mailing\*(R").
.PP
However, I don't know if using Net::SMTP to transfer such a message
is equally safe.  Feedback is welcomed.
.PP
My perspective: I don't want to magically diddle with a user's
message unless absolutely positively necessary.
Some users may want to send files with \*(L".\*(R" alone on a line;
my well-meaning tinkering could seriously harm them.
.SS "Infinite loops may mean tainted data!"
.IX Subsection "Infinite loops may mean tainted data!"
Stefan Sautter noticed a bug in 2.106 where a m//gc match was
failing due to tainted data, leading to an infinite loop inside
MIME::Lite.
.PP
I am attempting to correct for this, but be advised that my fix will
silently untaint the data (given the context in which the problem
occurs, this should be benign: I've labelled the source code with
\&\s-1UNTAINT\s0 comments for the curious).
.PP
So: don't depend on taint-checking to save you from outputting
tainted data in a message.
.SS "Don't tweak the global configuration"
.IX Subsection "Don't tweak the global configuration"
Global configuration variables are bad, and should go away.
Until they do, please follow the hints with each setting
on how \fInot\fR to change it.
.SH "A MIME PRIMER"
.IX Header "A MIME PRIMER"
.SS "Content types"
.IX Subsection "Content types"
The \*(L"Type\*(R" parameter of \f(CW\*(C`build()\*(C'\fR is a \fIcontent type\fR.
This is the actual type of data you are sending.
Generally this is a string of the form \f(CW"majortype/minortype"\fR.
.PP
Here are the major \s-1MIME\s0 types.
A more-comprehensive listing may be found in \s-1RFC\-2046.\s0
.IP "application" 4
.IX Item "application"
Data which does not fit in any of the other categories, particularly
data to be processed by some type of application program.
\&\f(CW\*(C`application/octet\-stream\*(C'\fR, \f(CW\*(C`application/gzip\*(C'\fR, \f(CW\*(C`application/postscript\*(C'\fR...
.IP "audio" 4
.IX Item "audio"
Audio data.
\&\f(CW\*(C`audio/basic\*(C'\fR...
.IP "image" 4
.IX Item "image"
Graphics data.
\&\f(CW\*(C`image/gif\*(C'\fR, \f(CW\*(C`image/jpeg\*(C'\fR...
.IP "message" 4
.IX Item "message"
A message, usually another mail or \s-1MIME\s0 message.
\&\f(CW\*(C`message/rfc822\*(C'\fR...
.IP "multipart" 4
.IX Item "multipart"
A message containing other messages.
\&\f(CW\*(C`multipart/mixed\*(C'\fR, \f(CW\*(C`multipart/alternative\*(C'\fR...
.IP "text" 4
.IX Item "text"
Textual data, meant for humans to read.
\&\f(CW\*(C`text/plain\*(C'\fR, \f(CW\*(C`text/html\*(C'\fR...
.IP "video" 4
.IX Item "video"
Video or video+audio data.
\&\f(CW\*(C`video/mpeg\*(C'\fR...
.SS "Content transfer encodings"
.IX Subsection "Content transfer encodings"
The \*(L"Encoding\*(R" parameter of \f(CW\*(C`build()\*(C'\fR.
This is how the message body is packaged up for safe transit.
.PP
Here are the 5 major \s-1MIME\s0 encodings.
A more-comprehensive listing may be found in \s-1RFC\-2045.\s0
.IP "7bit" 4
.IX Item "7bit"
Basically, no \fIreal\fR encoding is done.  However, this label guarantees that no
8\-bit characters are present, and that lines do not exceed 1000 characters
in length.
.IP "8bit" 4
.IX Item "8bit"
Basically, no \fIreal\fR encoding is done.  The message might contain 8\-bit
characters, but this encoding guarantees that lines do not exceed 1000
characters in length.
.IP "binary" 4
.IX Item "binary"
No encoding is done at all.  Message might contain 8\-bit characters,
and lines might be longer than 1000 characters long.
.Sp
The most liberal, and the least likely to get through mail gateways.
Use sparingly, or (better yet) not at all.
.IP "base64" 4
.IX Item "base64"
Like \*(L"uuencode\*(R", but very well-defined.  This is how you should send
essentially binary information (tar files, GIFs, JPEGs, etc.).
.IP "quoted-printable" 4
.IX Item "quoted-printable"
Useful for encoding messages which are textual in nature, yet which contain
non-ASCII characters (e.g., Latin\-1, Latin\-2, or any other 8\-bit alphabet).
.SH "HELPER MODULES"
.IX Header "HELPER MODULES"
MIME::Lite works nicely with other certain other modules if they are present.
Good to have installed are the latest MIME::Types,
Mail::Address, MIME::Base64,
MIME::QuotedPrint, and Net::SMTP.
Email::Date::Format is strictly required.
.PP
If they aren't present then some functionality won't work, and other features
wont be as efficient or up to date as they could be. Nevertheless they are optional
extras.
.SH "BUNDLED GOODIES"
.IX Header "BUNDLED GOODIES"
MIME::Lite comes with a number of extra files in the distribution bundle.
This includes examples, and utility modules that you can use to get yourself
started with the module.
.PP
The ./examples directory contains a number of snippets in prepared
form, generally they are documented, but they should be easy to understand.
.PP
The ./contrib directory contains a companion/tool modules that come bundled
with MIME::Lite, they don't get installed by default. Please review the \s-1POD\s0
they come with.
.SH "BUGS"
.IX Header "BUGS"
The whole reason that version 3.0 was released was to ensure that MIME::Lite is
up to date and patched. If you find an issue please report it.
.PP
As far as I know MIME::Lite doesn't currently have any serious bugs, but my
usage is hardly comprehensive.
.PP
Having said that there are a number of open issues for me, mostly caused by the
progress in the community as whole since Eryq last released. The tests are
based around an interesting but non standard test framework. I'd like to change
it over to using Test::More.
.PP
Should tests fail please review the ./testout directory, and in any bug reports
please include the output of the relevant file. This is the only redeeming
feature of not using Test::More that I can see.
.PP
Bug fixes / Patches / Contribution are welcome, however I probably won't apply
them unless they also have an associated test. This means that if I don't have
the time to write the test the patch wont get applied, so please, include tests
for any patches you provide.
.SH "VERSION"
.IX Header "VERSION"
Version: 3.030
.SH "CHANGE LOG"
.IX Header "CHANGE LOG"
Moved to ./changes.pod
.PP
\&\s-1NOTE:\s0 Users of the \*(L"advanced features\*(R" of 3.01_0x smtp sending
should take care: These features have been \s-1REMOVED\s0 as they never
really fit the purpose of the module. Redundant \s-1SMTP\s0 delivery is
a task that should be handled by another module.
.SH "TERMS AND CONDITIONS"
.IX Header "TERMS AND CONDITIONS"
.Vb 3
\&  Copyright (c) 1997 by Eryq.
\&  Copyright (c) 1998 by ZeeGee Software Inc.
\&  Copyright (c) 2003,2005 Yves Orton. (demerphq)
.Ve
.PP
All rights reserved.  This program is free software; you can
redistribute it and/or modify it under the same terms as Perl
itself.
.PP
This software comes with \fB\s-1NO WARRANTY\s0\fR of any kind.
See the \s-1COPYING\s0 file in the distribution for details.
.SH "NUTRITIONAL INFORMATION"
.IX Header "NUTRITIONAL INFORMATION"
For some reason, the \s-1US FDA\s0 says that this is now required by law
on any products that bear the name \*(L"Lite\*(R"...
.PP
Version 3.0 is now new and improved! The distribution is now 30% smaller!
.PP
.Vb 7
\&    MIME::Lite                |
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    Serving size:             | 1 module
\&    Servings per container:   | 1
\&    Calories:                 | 0
\&    Fat:                      | 0g
\&      Saturated Fat:          | 0g
.Ve
.PP
Warning: for consumption by hardware only!  May produce
indigestion in humans if taken internally.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc. (\fIhttp://www.zeegee.com\fR).
.PP
Go to \fIhttp://www.cpan.org\fR for the latest downloads
and on-line documentation for this module.  Enjoy.
.PP
Patches And Maintenance by Yves Orton and many others.
Consult ./changes.pod