LIBMAIL

Description

This library offers an object oriented way to send email from a PHP program.

Important! users of 1.2 version , download the last version. A bug in v1.2. was impacting file attachment functionnality.

Some of the libMail functionalities are :

Sending one or more file in attachment
Specify one or many recipients in To, CC or BCC
Format a message "ready to send" without sending it immediately
Auto checking of email addresses syntax
Add a receipt to the mail

ChangeLog

version 1.3

BUG FIX - file attachment didn't work
serious rewrite of the class
small optimization in _build_attachement()

version 1.2

added ReplyTo( $address ) method
added Receipt() method to add a mail receipt
added optional charset parameter to Body() method . should fix charset problem on some mail clients

version 1.1

added optional mimetype and disposition parameters to Attach() method
fixed parenthesis bug in sizeof()

Synopsis

	include "libmail.php";
	$m= new Mail; // create the mail
	$m->From( "leo@isp.com" );
	$m->To( "destination@somewhere.fr" );
	$m->Subject( "the subject of the mail" );
	$m->Body( "Hello\nThis is a test of the Mail component" );	// set the body
	$m->Cc( "someone@somewhere.fr");
	$m->Bcc( "someoneelse@somewhere.fr");
	$m->Priority(4) ;	// set the priority to Low
	$m->Attach( "/home/leo/toto.gif", "image/gif", "inline" ) ;	// attach a file of type image/gif to be displayed in the message if possible
	$m->Send();	// send the mail
	echo "Mail was sent:<br><pre>", $m->Get(), "</pre>";

Installation

Download libmail.zip

Content:

libmail.php: the Mail component
libmail_fr.html: documentation in french
libmail_en.html: documentation in english

No specific configuration is required in the library itself. In php3.ini (php.ini for PHP4):

configure the sendmail address sendmail_from
configure the SMTP server host SMTP

	SMTP           = smtp@isp.com			; for win32 only
	sendmail_from  = valid_address@chezmoi.fr	;for win32 only

Documentation

Constructor

Create an instance of a Mail.

	$mail = new Mail();

Subject( string sujet )

Defines the mail subject line. optional.

	$mail->Subject( "Bonjour, monde" );

From( address )

Defines the mail sender. call required.

	$mail->From( "me@isp.com" );

To( mixed address )

Defines the recipient(s). call required. The address parameter can be either an adress (string) or an array of addresses.

	$mail->To( "you@isp.com" );

	$tos = array( "you@isp.com", "u2@isp.com" );
	$mail->To( $tos );

CC( mixed address )

Defines one or many Carbon-copy recipients. The address parameter can be either an email adress (string) or an array of addresses.

	$mail->CC( "toto@somehost.fr" ); // un seul destinataire en CC

	$adr_en_cc = array( "a@isp.com", "b@isp.com", "c@isp.com" );
	$mail->CC( $adr_en_cc ); // many recipients in CC

BCC( mixed address )

Defines one or many invisible carbon-copy recipients. The address parameter can be either an email adress (string) or an array of addresses.

	$mail->BCC( "manager@somehost.fr" );

	$adr_en_bcc = array( "a@isp.com", "b@isp.com", "c@isp.com" );
	$mail->BCC( $adr_en_bcc ); // many recipients

Body( string body, [string charset] )

Defines the message body. the optional charset parameter defines the character set used in the message. The default is "us-ascii". Use iso-8859-1 charset if your message includes european characters such as accents.

	$mail->Body( "Message in english" );
	$mail->Body( "Message avé dé accents", "iso-8859-1" );

Note: Don't send HTML this way. See Advices to send a mail in HTML format.

Attach( string filename, [string mimetype], [string disposition] )

Attach a file $filename to the mail.

filename : path to the file on drive.
mimetype : string that defines the file MIME-type. Default MIME is 'application/x-unknown-content-type'. The Mime-Type is used by Email clients, for instance to display an image attached in the mail, or to "automagically" launch an attached virus for some of them :)
disposition : this code defines the method used to display the attachment. With inline (default), the mail client will display the file directly in the mail if possible. With attachment, the attched file will be presented as a link.

	// le fichier se trouve dans le repertoire courant
	$mail->Attach( "logo.gif", "image/gif" );

	// fichier indique en absolu - affiche sous forme de lien par le client mail
	$mail->Attach( "C:\\Mes Documents\\resume.doc", "application/x-msword", "attachment" );

autoCheck( boolean )

Activate or not the recipients email addresses validation. Default on. The validation is only a syntax one - the fact that this address exists or not is not checked.

	$mail->autoCheck( false ); // unactivate the validation
	$mail->autoCheck( true ); // activate the validation

Important : When on, any unvalid address will display an error message and stop the script. You can change this "safe mode" by :

a) modifying the CheckAdresses() method.

b) manually checking the addresses before and invoking AutoCheck(false)

Organization( string $org )

Defines the Organization field. Optionnal.

	$mail->Organization( "My company" );

ReplyTo( string address )

Defines a "Reply To" address that is different than the Sender address.

	$mail->ReplyTo( "helpdesk@mycompany.com" );

Priority( integer $priority )

Defines the mail priority. Optional.

priority must be an integer between 1 (highest) et 5 ( lowest ) This information is usuall used by mail clients, eg. by highlighting urgent messages.

	$mail->Priority( 1 ); // urgent
	$mail->Priority( 3 ); // normal
	$mail->Priority( 5 ); // pas urgent du tout

Receipt()

Add a receipt to the mail. This is a mecanism that sends a receipt back to sender when the message is opened by a recipient. The receipt is sent to the address defined in From field, unless if ReplyTo field is defined.

	$mail->Receipt();

Warning: this mecanism is not standardised, thus not fully supported by mail clients.

Send()

Send the mail. Don't forget to call this method :)

	$mail->Send();

Get()

	Return the whole email (headers + message + attachments) in raw format.
	Can be used to display the mail, or to save it in a File or DB.

	$msg = $mail->Get();

	// display the message on the page
	echo "Your message has been sent:<br><pre>", nl2br( $msg ) , "</pre>";

	// log it in a database
	$msg = str_replace( "'", "''", $msg );
	$bdd->exec(  "insert into Mailbox( user, folder, message, senttime ) values ( 'toto', 'Sent', '$msg', $FCT_CURRENT_TIME" );

Advices

Send a mail in HTML format

Fist point: I personally hate receiving HTML mails: I *don't* recommend to use it.

To send a HTML mail with libMail, you must attach your HTML source as a file:

	$file = "mail.html";
	$mail->Body( "This mail is formatted in HTML - shame on me" );
	// inline intructs the mail client to display the HTML if it can
	$mail->Attach( $file, "text/html", "inline" );

If your HTML page contains some images or links don't forget either to :

rewrite them in absolute : /mahomepage.html becomes http://chez.moi.com/mahomepage.html
define a BASE HREF in the HEAD section. All relative links will be relative to this URL

	<head>
		<base href="http://chez.moi.com/">
	</head>

When your recipients don't have any web access, you have a few solutions left such as the data: URLs that i describe here (french) or the linked parts that i should document soon.

Statut

Name	libmail
Lang	php3 / php4
Version	1.3
Lastmod	Thu Oct 12 12:12:36 UTC 2000
Author	Leo West