Liz::Mail - Simple mail sending module, allows sending of attachments
use Liz::Mail;
$mail = new Liz::Mail;
#!/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
The Liz::Mail package allows an easy to use interface for sending email, optionally including files that can be sent as MIME-attachments.
The following methods are the basic methods of the Liz::Mail module.
Create a new Liz::Mail object. Optionally sets the subject of the email to be sent.
1 subject of email to be sent (default: none)
1 instantiated object
$mail = Liz::Mail->new( 'Something fishy at the OK Corral' );
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.
1 complete email message (default: read message from STDIN) 2 flag: whether to leave the attachments encoded in the object (default: decode)
1 instantiated object
undef( $/ ); $mail = Liz::Mail->receive( <STDIN> );
Sends the email message contained in the object. Execute routine previously specified by FixupHandler before actually sending the object when necessary.
1 the complete email message, for archiving and debugging purposes
$archive = $mail->send;
The following methods allow changes to information that is associated with an entire mail.
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).
1 new/additional Bcc: addressee (default: no change)
1 current/old Bcc: addressee(s)
$mail->Bcc( 'wendy@xxLINK.nl' );
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.
1 new body (default: no change)
1 current/old body
$mail->Body( <<EOD ); Hi,
what do you think of this message? It was sent with the Liz::Mail module!
Kind regards,
Liz EOD
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).
1 new/additional Cc: addressee (default: no change)
1 current/old Cc: addressee(s)
$mail->Cc( 'wendy@xxLINK.nl' );
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.
1 new Content-Encoding (default: quoted-printable)
1 current/old Content-Encoding
$mail->ContentEncoding( 'base64' );
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.
1 new Content-Type (default: text/plain)
1 current/old Content-Type
$mail->ContentType( 'image/gif' );
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.
1 new ErrorsTo: addressee (default: no change)
1 current/old ErrorsTo: addressee(s)
$mail->ErrorsTo( 'postmaster@xxLINK.nl' );
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.
1 new external ID (default: no change)
1 current/old external ID
$mail->ExternalID( $ID ); $ID = $mail->ExternalID;
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).
1 new reference to subroutine (either alpha or code reference)
(default: no change)
2..N parameters to be passed to the fixuphandler subroutine
1 current/old reference to subroutine
$mail->FixupHandler( \&AddTracking,$dbh );
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.
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)
$mail->File( '/tmp/filename' );
$mail->File( <<EOD,'sample.txt','text/plain' ); This is a sample text that will be sent as an attachment. EOD
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
Specify/Return the From: address of the email object.
1 new From: addressee (default: no change)
1 current/old From: addressee(s)
$mail->From( 'info@xxLINK.nl' );
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.
1 new/extra additional header line (default: no change)
1 current/old additional header lines
$mail->Header( "X-MyHeader: whoopee\n" );
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.
1 new HTML-version of the body (default: no change)
1 current/old HTML-version of the body
$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
Not all email-programs, especially the ones that use text-mode, support this type of email messaging.
Specify/Return the Importance: of the email object.
1 new Importance of email object (default: no change)
1 current/old Importance of email object
$mail->Importance( 'high' );
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.
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.
1 IP-number to add extra header line for
(default: $ENV{'REMOTE_ADDR'})
$mail->IP; $mail->IP( '193.79.208.1' );
Specify/Return the Organization: of the email object.
1 new Organization of email object (default: no change)
1 current/old Organization of email object
$mail->Organization( 'xxLINK Internet Services' );
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.
1 ordinal number of the part to return information from (default: 1)
1 content of the part 2 filename of the part 3 mime-type of the part
$contents = $mail->Part( 1 ); ($contents,$filename,$mime) = $mail->Part( 1 );
Return the number of associated parts (attachments) of the mail object. Use method Part to obtain specific information aboyt a single part.
1 number of parts available
foreach( 1..$mail->Parts ) {
($contents,$filename,$mime) = $mail->Part( $_ );
print "$filename ($mime): $contents\n";
}
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.
1 new ReplyTo: addressee (default: no change)
1 current/old ReplyTo: addressee(s)
$mail->ReplyTo( 'liz@xxLINK.nl' );
Specify/Return the Subject: of the email object. This can also be done when the object is created with the new method.
1 new Subject: (default: no change)
1 current/old Subject:
$mail->Subject( 'About this and that' );
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).
1 new/additional To: addressee (default: no change)
1 current/old To: addressee(s)
$mail->To( 'liz@xxLINK.nl' );
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.
1 identification name of header 2 new value of X-...: header line (default: no change)
1 current/old value of X-...: header line
$mail->X( 'contactID',$contactID );
The following methods allow the developer to specify in which way the messages are sent, or returned, or written to a file.
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).
1 new setting of the boundary (default: no change)
1 current/old setting of the boundary
$mail->Boundary( "@@@@@@@@@@@\n" ); $boundary = $mail->Boundary;
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.
1 new setting of the filehandle (default: no change)
1 current/old setting of the filehandle
$mail->FileHandle( FILE ); $filehandle = $mail->FileHandle;
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''.
1 new sendmail program to be used (default: no change)
1 current/old sendmail program
$mail->MailProgram( '/usr/sbin/sendmail' );
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.
1 new setting of the return flag (default: no change)
1 current/old setting of the return flag
$mail->Return( 1 ); $return = $mail->Return;
Set or return the number of seconds to be waited between messages sent by SendMailFromFileHandle.
1 new number of seconds (default: no change)
1 current/old number of seconds
$mail->Sleep( 1 ); $sleep = $mail->Sleep;
The following methods are generally not used in normal situations but only once to set things up.
Encode a string according to the coding-type specified. Can also be used as a method. Performs the operation opposite to Decode.
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')
1 encoded string (undef if unsupported encoding specified)
$encoded = Liz::Mail::Encode( 'Encode this string','quoted-printable' ); $encoded = $mail->Encode( 'Encode this string','binary' );
Set the field ERROR if an encoding type was specified that is not supported.
Decode a string according to the coding-type specified. Can also be used as a method. Performs the operation opposite to Encode.
1 string to decode 2 type of encoding that was used (supported: quoted-printable, base64, binary, 8bit, x-uuencode, x-gzip64)
1 decoded string (undef if unsupported encoding specified) 2 filename found in encoded stream (optional: only valid with uuencoded streams)
$decoded = Liz::Mail::Decode( $string,'quoted-printable' ); $decoded = $mail->Decode( $string,'binary' );
Set the ERROR field of the object if used as a method and the type of encoding is not supported.
To be faded out: please use methode Encode instead.
To be faded out: please use methode Decode instead.
The following methods are intended for internal use only, but can also be used by experienced developers directly.
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.
1 message to be sent
1 complete message (for debugging and or archiving purposes)
Liz::Mail::SendMail( <<EOD ); From: liz@xxLINK.nl To: everybody Subject: This is a test
This is a test message EOD
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.
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)
1 number of unique messages sent 2 number of bytes sent
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1996-1999 International Network Consultants
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods receive and SendMailFromFileHandle.
Now no longer adds Exporter to ISA: it wasn't necessary.
Support for ExternalID added.
Added support for unsetting the FixupHandler.
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.
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.
Added new method X for specifying and returning X-...: header.
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.
Fixed additional problem with filename not being recognized if the Content-Disposition: line would extend over more than one line.
Fixed problem in receive with emails that would have an initial Content-type: that would extend over more than one line.
Fixed problem in receive that would cause Reply-To and Errors-To headers to not be included in the object.
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.
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.
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.
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.
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.
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.
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.
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.
Method/subroutine SendMailFromFileHandle now sends 10 messages without delay before sleeping. This allows times between messages to be specified as fractions.
Method/subroutine SendMailFromFileHandle now uses IO::File to open handles.
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.
Fixed problem in receive which would cause attachments to be missed if the initial Content-Type was the last line in the header.
Method/Subroutine SendMail now checks whether the exec() was successful or not, and sets
the Error field if it wasn't.
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.
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.
Subroutine/Method SendMail now removes the hidden Bcc: from the contents before returning it.
New method MailProgram: allows specification of alternate sendmail program.
Fixed various problems in SendMail.
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.
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.
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.
Method send now stores the complete header in the field ``HEADER''.
Added method Attachments as AUTOLOADed method.
Method Option moved to the Liz.pm module.
First version of this true Perl module, based on routines developed for several (customer) libraries.