NAME

Liz::Mail - Simple mail sending module, allows sending of attachments


SYNOPSIS

 use Liz::Mail;

 $mail = new Liz::Mail;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::Mail;

 $mail = new Liz::Mail;
 $mail->From( 'info@xxLINK.nl' );
 $mail->To( 'liz@xxLINK.nl' );
 $mail->Cc( 'wendy@xxLINK.nl' );
 $mail->Subject( 'This is a test message' );
 $mail->Body( <<EOD );
 This is a test message, really!
 EOD
 $mail->File( 'test.doc' );
 $mail->send;

 # or: quick and dirty and compatible with older scripts but without files

 Liz::Mail::SendMail( <<EOD );
 To: liz\@xxLINK.nl
 From: info\@xxLINK.nl
 Cc: wendy\@xxLINK.nl
 Subject: This is a test message

 Really, this is a test message!
 EOD


DESCRIPTION

The Liz::Mail package allows an easy to use interface for sending email, optionally including files that can be sent as MIME-attachments.


BASIC METHODS

The following methods are the basic methods of the Liz::Mail module.


new

Create a new Liz::Mail object. Optionally sets the subject of the email to be sent.

Input Parameters

 1 subject of email to be sent
   (default: none)
Output Parameters

 1 instantiated object
Example

 $mail = Liz::Mail->new( 'Something fishy at the OK Corral' );


receive

Create a new Liz::Mail object by importing a MIME-formatted email message, either from a value or from STDIN.

Scans the header for standard Liz::Email methods such as To, Subject, From etc.

Input Parameters

 1 complete email message
   (default: read message from STDIN)
 2 flag: whether to leave the attachments encoded in the object
   (default: decode)
Output Parameters

 1 instantiated object
Example

 undef( $/ );
 $mail = Liz::Mail->receive( <STDIN> );


send

Sends the email message contained in the object. Execute routine previously specified by FixupHandler before actually sending the object when necessary.

Output Parameters

 1 the complete email message, for archiving and debugging purposes
Example

 $archive = $mail->send;


CONTENT METHODS

The following methods allow changes to information that is associated with an entire mail.


Bcc

Specify/Return the Bcc: addressee(s) of the email object. You may prefix any extra addressee with ``+='' to add to the already existing addressee(s).

Input Parameters

 1 new/additional Bcc: addressee
   (default: no change)
Output Parameters

 1 current/old Bcc: addressee(s)
Example:

 $mail->Bcc( 'wendy@xxLINK.nl' );


Body

Specify the body (actual message) of the email to be sent. Look at method HTML also if you would like to send an alternate version of the text in HTML format.

Input Parameters

 1 new body
   (default: no change)
Output Parameters

 1 current/old body
Example:

 $mail->Body( <<EOD );
 Hi,

 what do you think of this message?  It was sent with the Liz::Mail module!

 Kind regards,

 Liz
 EOD


Cc

Specify/Return the Cc: addressee(s) of the email object. You may prefix any extra addressee with ``+='' to add to the already existing addressee(s).

Input Parameters

 1 new/additional Cc: addressee
   (default: no change)
Output Parameters

 1 current/old Cc: addressee(s)
Example:

 $mail->Cc( 'wendy@xxLINK.nl' );


ContentEncoding

Specify/Return the Content-Encoding: of the main part of the email object. This is not necessary in most cases, only if you want to send a message to a mail system that you know only supports certain types of encoding.

See method Encode for supported types of encoding.

Input Parameters

 1 new Content-Encoding
   (default: quoted-printable)
Output Parameters

 1 current/old Content-Encoding
Example:

 $mail->ContentEncoding( 'base64' );


ContentType

Specify/Return the Content-Type: of the main part of the email object. This is not necessary in most cases, only if you want to send a non-text file as the only part of the email object (without any extra text or other attachments). For sending files with an email object it is usually better to use the File method.

Input Parameters

 1 new Content-Type
   (default: text/plain)
Output Parameters

 1 current/old Content-Type
Example:

 $mail->ContentType( 'image/gif' );


ErrorsTo

Specify/Return the Errors-to: addressee of the email object. This indicates the email address where email should be returned to if there is a failure in the delivery. Please note that this feature is not supported by all Mail Transfer Agents: those who do not support this will usually return undeliverable mail to the From: address.

Input Parameters

 1 new ErrorsTo: addressee
   (default: no change)
Output Parameters

 1 current/old ErrorsTo: addressee(s)
Example:

 $mail->ErrorsTo( 'postmaster@xxLINK.nl' );


ExternalID

Specify/Return an external ID of the email object. This has no meaning within Liz::Mail, but only when being used in conjunction with the Liz::TrackSet module.

Input Parameters

 1 new external ID
   (default: no change)
Output Parameters

 1 current/old external ID
Example:

 $mail->ExternalID( $ID );
 $ID = $mail->ExternalID;


FixupHandler

Specify/Return a reference to a subroutine that should be called as a method (first parameter is the Liz::Mail object) just before the mail is actually sent. This can e.g. be useful when it is needed to keep track of mails being sent (e.g. mailing lists with Liz::BulkMail).

Input Parameters

 1    new reference to subroutine (either alpha or code reference)
      (default: no change)
 2..N parameters to be passed to the fixuphandler subroutine
Output Parameters

 1    current/old reference to subroutine
Example:

 $mail->FixupHandler( \&AddTracking,$dbh );


File

Add a file to the message to be sent. Use method Part to obtain information about attachments that are already associated with an email message.

Optionally allows an already MIME-encoded data-stream to be associated with the email message. MIME-encoding can be performed by the Encode method. The advantage of MIME-encoding beforehand is less now since the object will now remember the encoding when sending multiple mails. So encoding beforehand only makes sense if the encoded version is saved in a file (e.g. a 2Mb Word document) and added already encoded from that file.

Input Parameters

 1 file (contents or file-specification)
 2 name of file
   (default: file-specification or 'noname')
 3 MIME-type of contents
   (default: application/octet-stream)
 4 encoding used
   (default: none)
Example

 $mail->File( '/tmp/filename' );
Example

 $mail->File( <<EOD,'sample.txt','text/plain' );
 This is a sample text that will be sent as an attachment.
 EOD
Example

 Liz::WriteContents( Liz::Mail::Encode( Liz::Contents('word.doc'),'base64' ),'word.doc.base64' ); # only once

 $mail->File( Liz::Contents( 'word.doc.base64' ),'word.doc','microsoft/word','base64' ); # when mail is sent


From

Specify/Return the From: address of the email object.

Input Parameters

 1 new From: addressee
   (default: no change)
Output Parameters

 1 current/old From: addressee(s)
Example:

 $mail->From( 'info@xxLINK.nl' );


Header

Specify additional header lines in the email to be sent. If you would like to specify extra header lines that start with 'X-...:', then it is better to use the X method.

It is usually not necessary to call this method, as all standard email header lines are generated automatically by this module. It is only necessary if you would like to add special, non-standard header lines.

You may prefix any extra header line with ``+='' to add to the already existing header lines. It is advised to always prefix additional header lines with ``X-'' to indicate that they are non-standard.

Input Parameters

 1 new/extra additional header line
   (default: no change)
Output Parameters

 1 current/old additional header lines
Example:

 $mail->Header( "X-MyHeader: whoopee\n" );


HTML

Specify the body (actual message) of the email to be sent in HTML-format. This only works if you also have a plain-text version of the message specified with the Body method.

Input Parameters

 1 new HTML-version of the body
   (default: no change)
Output Parameters

 1 current/old HTML-version of the body
Example:

 $mail->HTML( <<EOD );
 <HTML><BODY BGCOLOR="yellow">
 Hi,
 <P>
 what do you think of this message?  It was sent with the Liz::Mail module!
 <HR>
 Kind regards,

 <I>Liz</I>
 </BODY></HTML>
 EOD
Note

Not all email-programs, especially the ones that use text-mode, support this type of email messaging.


Importance

Specify/Return the Importance: of the email object.

Input Parameters

 1 new Importance of email object
   (default: no change)
Output Parameters

 1 current/old Importance of email object
Example:

 $mail->Importance( 'high' );
Note:

Most email programma's only recognize the following values for importance:

  1 or highest
  2 or high
  3 or normal
  4 of low
  5 or lowest

A value of '3' or 'normal' will not add any header to the email. Another value from the above list will add both an 'X-Priority:' header as well as an 'Importance:' header. If the value specified is not recognized, then only an 'Importance:' header will be added.


IP

Specify an additional ``X-IP'' header line with a given IP-address, or the IP-address of the remote user when in a web environment.

Input Parameters

 1 IP-number to add extra header line for
   (default: $ENV{'REMOTE_ADDR'})
Example:

 $mail->IP;
 $mail->IP( '193.79.208.1' );


Organization

Specify/Return the Organization: of the email object.

Input Parameters

 1 new Organization of email object
   (default: no change)
Output Parameters

 1 current/old Organization of email object
Example:

 $mail->Organization( 'xxLINK Internet Services' );


Part

Return information about associated parts (attachments) to the mail object. Parts can be created with the File method, or be automatically created by the receive method if the email stream contained MIME-attachments of the correct type.

Input Parameters

 1 ordinal number of the part to return information from
   (default: 1)
Output Parameters

 1 content of the part
 2 filename of the part
 3 mime-type of the part
Example:

 $contents = $mail->Part( 1 );
 ($contents,$filename,$mime) = $mail->Part( 1 );


Parts

Return the number of associated parts (attachments) of the mail object. Use method Part to obtain specific information aboyt a single part.

Output Parameters

 1 number of parts available
Example

 foreach( 1..$mail->Parts ) {
   ($contents,$filename,$mime) = $mail->Part( $_ );
   print "$filename ($mime): $contents\n";
 }


ReplyTo

Specify/Return the Reply-to: addressee of the email object. This indicates the email address where email should be sent to if the user uses hisr/her ``Reply'' function in their email program. Please note that this feauture is not supported by all email programs: those who do not support this will usually return undeliverable mail to the From: address.

Input Parameters

 1 new ReplyTo: addressee
   (default: no change)
Output Parameters

 1 current/old ReplyTo: addressee(s)
Example:

 $mail->ReplyTo( 'liz@xxLINK.nl' );


Subject

Specify/Return the Subject: of the email object. This can also be done when the object is created with the new method.

Input Parameters

 1 new Subject:
   (default: no change)
Output Parameters

 1 current/old Subject:
Example:

 $mail->Subject( 'About this and that' );


To

Specify/Return the To: addressee(s) of the email object. You may prefix any extra addressee with ``+='' to add to the already existing addressee(s).

Input Parameters

 1 new/additional To: addressee
   (default: no change)
Output Parameters

 1 current/old To: addressee(s)
Example:

 $mail->To( 'liz@xxLINK.nl' );


X

Specify/Return a special X-...: header in the Email Header. Only allows one copy of each X-...: in the header. It is especially handy for changing a specific X-...: header line in an already defined Header.

Input Parameters

 1 identification name of header
 2 new value of X-...: header line
   (default: no change)
Output Parameters

 1 current/old value of X-...: header line
Example:

 $mail->X( 'contactID',$contactID );


SEND METHODS

The following methods allow the developer to specify in which way the messages are sent, or returned, or written to a file.


Boundary

Set or return the boundary that will be printed by method SendMail if a FileHandle was specified to write the message to. This is mainly used in bulk operations. This indirectly also affect the operation of method send.

The boundary should be a string that by itself will not occur in an entire line in the message to be sent. It must contain any newline character(s) that are needed to make the system find out it is a whole line when read (usually a \n at the end).

Input Parameters

 1 new setting of the boundary
   (default: no change)
Output Parameters

 1 current/old setting of the boundary
Example

 $mail->Boundary( "@@@@@@@@@@@\n" );
 $boundary = $mail->Boundary;


FileHandle

Set or return the filehandle to which method SendMail will write the message to. This is mainly used in bulk operations. This indirectly also affect the operation of method send.

Use method Boundary to specify a boundary between messages to be sent. Use method SendMailFromFileHandle to send mail that was previously saved in a file.

Input Parameters

 1 new setting of the filehandle
   (default: no change)
Output Parameters

 1 current/old setting of the filehandle
Example

 $mail->FileHandle( FILE );
 $filehandle = $mail->FileHandle;


MailProgram

Specify the program that will be used to send the actual email. In most situations it is not necessary to call this method if the Liz::Mail package is correctly installed.

The default is usually ``/usr/lib/sendmail''.

Input Parameters

 1 new sendmail program to be used
   (default: no change)
Output Parameters

 1 current/old sendmail program
Example:

 $mail->MailProgram( '/usr/sbin/sendmail' );


Return

Set or return the flag that will cause method SendMail to just return the message that was otherwise going to be sent. This is mainly used in debugging, or in bulk operations. This indirectly also affect the operation of method send.

Input Parameters

 1 new setting of the return flag
   (default: no change)
Output Parameters

 1 current/old setting of the return flag
Example

 $mail->Return( 1 );
 $return = $mail->Return;


Sleep

Set or return the number of seconds to be waited between messages sent by SendMailFromFileHandle.

Input Parameters

 1 new number of seconds
   (default: no change)
Output Parameters

 1 current/old number of seconds
Example

 $mail->Sleep( 1 );
 $sleep = $mail->Sleep;


UTILITY METHODS

The following methods are generally not used in normal situations but only once to set things up.


Encode

Encode a string according to the coding-type specified. Can also be used as a method. Performs the operation opposite to Decode.

Input Parameters

 1 string to encode
 2 type of encoding to be used
   (supported: quoted-printable, base64, 8bit, binary, x-uuencode, x-gzip64)
 3 filename to be used
   (default: 'noname')
Output Parameters

 1 encoded string
   (undef if unsupported encoding specified)
Example

 $encoded = Liz::Mail::Encode( 'Encode this string','quoted-printable' );
 $encoded = $mail->Encode( 'Encode this string','binary' );
Note

Set the field ERROR if an encoding type was specified that is not supported.


Decode

Decode a string according to the coding-type specified. Can also be used as a method. Performs the operation opposite to Encode.

Input Parameters

 1 string to decode
 2 type of encoding that was used
   (supported: quoted-printable, base64, binary, 8bit, x-uuencode, x-gzip64)
Output Parameters

 1 decoded string
   (undef if unsupported encoding specified)
 2 filename found in encoded stream
   (optional: only valid with uuencoded streams)
Example

 $decoded = Liz::Mail::Decode( $string,'quoted-printable' );
 $decoded = $mail->Decode( $string,'binary' );
Note

Set the ERROR field of the object if used as a method and the type of encoding is not supported.


Binary2MIME

To be faded out: please use methode Encode instead.


MIME2Binary

To be faded out: please use methode Decode instead.


INTERNAL METHODS

The following methods are intended for internal use only, but can also be used by experienced developers directly.


SendMail

Sends an email message. Message should contain alle the necessary fields such as From:, To:, Subject:, etc., etc. This routine can also be called as method, but is primarily intended for internal use only.

Input Parameters

 1 message to be sent
Output Parameters

 1 complete message (for debugging and or archiving purposes)
Example

 Liz::Mail::SendMail( <<EOD );
 From: liz@xxLINK.nl
 To: everybody
 Subject: This is a test

 This is a test message
 EOD


SendMailFromFileHandle

Low level method/subroutine that will send all messages that were previously saved in a file. It is usually used in bulk operations, where the file is the result of the use of methods FileHandle and Boundary.

Input Parameters

 1 handle to read messages from
   (default: field FILEHANDLE)
 2 boundary to be used to find the next message
   (default: field BOUNDARY)
 3 number of seconds to wait between messages
   (default: field SLEEP or 1)
 4 mail program to use
   (default: field MAILPROGRAM or /usr/lib/sendmail)
Output Parameters }

 1 number of unique messages sent
 2 number of bytes sent
Example open( FILE,"gunzip -c /tmp/messages|" ); ($messages,$bytes) = Liz::Mail::SendMailFromHandle( FILE,"@@@@@@@@@@\n" );


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1996-1999 International Network Consultants


HISTORY

Version 2.14, 3 December 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods receive and SendMailFromFileHandle.

Version 2.13, 30 September 1999

Now no longer adds Exporter to ISA: it wasn't necessary.

Version 2.12, 7 September 1999

Support for ExternalID added.

Version 2.11, 6 September 1999

Added support for unsetting the FixupHandler.

Version 2.10, 21 July 1999

Added -F parameter to sendmail call also, so that any name specification is kept on the envelope. Now disects the From: to create a separate email and full name part, and passes these to the mailer program so that they can appear on the envelope.

Version 2.09, 20 July 1999

Added -f parameter to sendmail call in SendMail so that erroneously sent mail is returned to the From: address, instead of the userID/server combination. This indirectly affect send as well as the Liz::BulkMail module.

Version 2.08, 5 July 1999

Added new method X for specifying and returning X-...: header.

Version 2.07, 1 July 1999

Added method Importance to allow indication of the importance of an email.

Added method FixupHandler which allows the specification of a routine that will be executed by method send just before the mail is actually sent.

Changed source to new typography.

Version 2.06, 21 June 1999

Fixed additional problem with filename not being recognized if the Content-Disposition: line would extend over more than one line.

Version 2.05, 17 June 1999

Fixed problem in receive with emails that would have an initial Content-type: that would extend over more than one line.

Version 2.04, 30 April 1999

Fixed problem in receive that would cause Reply-To and Errors-To headers to not be included in the object.

Version 2.03, 30 March 1999

Fixed problem in Encode and Decode: either the POP protocol, or POP-servers or mail programs such as Eudora, stop when a null-byte is encountered in text. Encode now converts null bytes to '\0', whereas Decode now converts '\0' back to true null bytes.

Fixed problem in send which would cause text attachments without a trailing LF to be incorrectly formatted.

Version 2.02, 25 March 1999

Fixed problem in Part which would not return the last attachment.

Fixed problem in send that would cause the wrong encoding to be used for non-text attachments if the same object was used a second time to send mail.

Version 2.01, 24 March 1999

Methods Encode and Decode now set the field ERROR if an encoding type was specified that is not supported. This indirectly also affects method receive, which does create an object, but with an empty BODY field if an unsupported encoding was specified.

Version 2.0, 22 March 1999

Added method Parts to return the number of parts (attachments) that are currently associated with the mail object.

Added method Part to return information about associated parts (attachments) of the mail object. This replaces the undocumented, and now unsupported, direct access to the ATTACHMENTS field.

Added method HTML to specify an alternative Body in HTML-format. Added support for ``multipart/alternative'' to method send so that HTML bodies are now supported.

Improvement encoding logic of attachments: once an attachment is encoded, it will remain encoded in the object so that subsequent uses of the mail object do not need to re-encode the attachments again and again. This is particularly useful in a Liz::BulkMail situation, where the same mail object can be used over and over again.

New methods Encode and Decode allow easy encoding and decoding. These replace the now to be faded out methods Binary2MIME and MIME2Binary.

Method receive now stores the entire mail header in the HEADER field for inspection. It also sets a flag indicating that the contents of the HEADER field should not be used for sending a mail message with the object. This flag is automatically reset when a specific header line is added with the Header method: the ``received'' contents of the HEADER field will then be discarded.

Re-developed methods send and receive from scratch without using the MIME::Entity standard modules: they proved to be causing all sorts of unreproducable problems in a ModPerl environment.

Version 1.03, 14 March 1999

Method receive now removes header fields from the header that are stored in other fields of the Liz::Mail object. This prevents double entries in the header should the Liz::Mail object be used for sending or storing in other modules.

Version 1.02, 12 March 1999

Method send now removes and CRLF's from the Body, replacing them by LF's, and changes any remaining (lonely) CR's to LF's. Subroutine SendMail now does NOT change any LF's into CRLF's anymore, as this seems to be unneccesary. Previously, CRCRLF strings could occur within the Body of a message, causing havoc in some mail readers.

Version 1.01, 10 March 1999

Changed encoding for text messages to ``quoted-printable'' and attachments to ``binary'' instead of using the -SUGGEST encoding option that sometimes bombs in method send.

Make sure that message body is always in CRLF format, to prevent possible problem with some mail programs in method send.

Version 1.00, 9 February 1999

Replaced the MIME parsing and conversion machinery that was developed beginning of 1996 in-house, by the now mature MIME::Parser module and its sub-modules. Advantage is complete compatibility with the Perl and Internet community (especially with regards to Content encoding types). Disadvantage is the sheer size of all the submodules that are needed: about 1.2 Mb increase in binary size when running under Apache in a ModPerl environment.

Only one problem remains: MIME::Entity in its present state does not allow pre-encoded MIME bodies to be specified. For the moment this is ``fixed'' by decoding an already encoded body before adding it to the MIME::Entity object.

Method SendFilesByMail no longer exists. Its function is now performed by the File and send methods.

Version 0.60, 4 February 1999

Method/subroutine SendMailFromFileHandle now sends 10 messages without delay before sleeping. This allows times between messages to be specified as fractions.

Version 0.59, 31 January 1999

Method/subroutine SendMailFromFileHandle now uses IO::File to open handles.

Version 0.58, 30 January 1999

New method/subroutine SendMailFromFileHandle added: send messags from a file that was previously most likely created with the use of methods FileHandle and Boundary.

New method Sleep added: specify the number of seconds to wait between messages with SendMailFromFileHandle.

New methods FileHandle and Boundary added: cause method SendMail to write messages to a file, and optionally add boundary strings to later be able to split the file into messages again.

New method Return added: specify or return the flag that causes SendMail to just return the raw message.

Version 0.57, 28 January 1999

Fixed problem in receive which would cause attachments to be missed if the initial Content-Type was the last line in the header.

Version 0.56, 13 January 1999

Method/Subroutine SendMail now checks whether the exec() was successful or not, and sets the Error field if it wasn't.

Version 0.55, 18 November 1998

New method IP: add special ``X-IP:'' header to the mail header so that the origin of an email can be better traced when being sent e.g. from a web-site.

Version 0.54, 6 October 1998

Reduced global variable usage and removed imports from modules by using fully qualified use of variables and subroutines. Reduced the memory footprint of this module by 8K.

Method Attachments now really allowed.

Version 0.53, 20 September 1998

Subroutine/Method SendMail now removes the hidden Bcc: from the contents before returning it.

Version 0.52, 29 August 1998

New method MailProgram: allows specification of alternate sendmail program.

Fixed various problems in SendMail.

Version 0.51, 28 August 1998

Method send no longer adapts the HEADER field to the actual header that was sent, but instead retains the original value in the Header field so that the same Mail object can now be used more than once to send an email.

Version 0.5, 13 July 1998

Sending of mail has now become much faster for users because a seperate process is now started for the actual sending of the email. This causes the possible delays to be only experienced by the spawned process, not the process the user is directly interacting with.

Version 0.4, 6 July 1998

New utility methods Binary2MIME and MIME2Binary to convert to and from MIME encoded data.

Method File now accepts an extra flag to indicate whether the contents is already MIME-encoded.

Method SendFilesByMail now accepts a list with 4 entries per attachment: flag for indicating whether the file is already encoded is added to each entry. This is *INCOMPATIBLE* with previous versions *IFF* more than one attachment is sent.

Version 0.3, 4 June 1998

Method send now stores the complete header in the field ``HEADER''.

Version 0.2, 4 June 1998

Added method Attachments as AUTOLOADed method.

Method Option moved to the Liz.pm module.

Version 0.1, 22 May 1998

First version of this true Perl module, based on routines developed for several (customer) libraries.