LIBMAIL

Description

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

Show summary

License

This script is distributed under the GPL License

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Authors

This script is an extensions of original libMail by Leo West

Original script by Leo West - west_leo@yahoo.com
URL: http://lwest.free.fr/doc/php/lib/Mail/
Lastmod : Nov 2001
Version : 1.3

Modified by Setec Astronomy - setec@freemail.it
URL : http://digilander.iol.it/setecastronomy/
Lastmod : Gen 2004
Version : 1.4

Modified by Pier Luigi Pau - eregilofdarkwood@yahoo.com
URL : http://eregil.altervista.org/
Lastmod : Jan 2008
Version : 1.4.2, 1.5.0

Some of the libMail functionalities are :

ChangeLog

version 1.5.0

This version is released at the same time as 1.4.2; whereas 1.4.2 attempts to be a drop-in replacement for 1.4.1 (no radical interface change), this version adds some non-trivial functionality, namely multipart/alternative support. Thus, the way you send your HTML mail will have to be changed starting with this version.

version 1.4.2

This version tries to be a drop-in replacement of 1.4.1, but in any case, testing is strongly advised rather than simply replacing your libmail.php on a production server.

version 1.4.1

version 1.4

version 1.3

version 1.2

version 1.1

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:

Please note: multiple versions of libMail may be packaged together. However, each version is to be considered as a separate work, which may be redistributed under the GPL. In other words, you may redistribute, alter (and re-release under the GPL) or deploy a single version of the script even if you received or downloaded a package containing multiple versions.

No specific configuration is required in the library itself. In php.ini:

	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 subject])

Defines the mail subject line. optional.

	$mail->Subject ("Hello world!");

From (string from_email, [string from_name])

Defines the mail sender. call required. You can also specify the sender name.

	$mail->From( "me@isp.com" );
	$mail->From( "me@isp.com", "Me at ISP" );

To (mixed address)

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

	$mail->To ("you@isp.com");
	$tos = array ("you@isp.com", "u2@isp.com");
	$mail->To ($tos);
	$tos = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATED AS OF 1.4.2
	$mail->To ($tos);
	$tos = array ("You at ISP <you@isp.com>", "U2 at ISP <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. You can also specify the recipient(s) name.

	$mail->CC ("you@isp.com");
	$ccs = array ("you@isp.com", "u2@isp.com");
	$mail->CC ($ccs);
	$ccs = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATED AS OF 1.4.2
	$mail->CC ($ccs);
	$ccs = array ("You at ISP <you@isp.com>", "U2 at ISP <u2@isp.com>");
	$mail->CC ($ccs);

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. You can also specify the recipient(s) name.

	$mail->BCC ("you@isp.com");
	$bccs = array ("you@isp.com", "u2@isp.com");
	$mail->BCC ($bccs);
	$bccs = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATED AS OF 1.4.2
	$mail->BCC ($bccs);
	$bccs = array ("You at ISP <you@isp.com>", "U2 at ISP <u2@isp.com>");
	$mail->BCC ($bccs);

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.

Text ([string body], [string charset])

Alias of Body(). Available since 1.5.0

Html ([string html_body], [string charset])

Defines the message body in HTML version. See Advices for examples.
The optional charset parameter works the same as in the Body() method. Please note that only the last specified charset, among all methods called, is used for each e-mail; you cannot use different charsets for text and HTML.
Available since 1.5.0

SetCharset (string charset)

Defines the character set used in the message. Can be used as an alternative to the optional charset parameter in Body() and Html(). Please note that only the last specified charset, among all methods called, is used for each e-mail.
Available since 1.5.0

	$mail->SetCharset ("iso-8859-1");

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

Attach a file $filepath to the mail.

	$mail->Attach ("logo.gif", "image/gif");
	$mail->Attach ("C:\\My Documents\\resume.doc", "application/x-msword", "attachment");
	$mail->Attach ("C:\\My Documents\\resume.doc", "application/x-msword", "attachment", "cv.doc");

AttachString( string content, [string mimetype], [string disposition], [string filename] )

Create a file from string $content and attach it to the mail (the file will not be automatically stored!). Available since 1.4.2

	$some_content = "A text file containing this string will be created and attached.\n";
	$mail->AttachString($some_content, "text/plain", "attachment", "some_text.txt");

Organization (string $org)

Defines the Organization field. Optional.

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

ReplyTo (string replyto_email, [string replyto_name])

Defines a "Reply To" address that is different than the Sender address. You can also specify the Reply To name.

ReturnPath (string returnpath_email, [string returnpath_name])

Defines a "Return Path" address that is different than the Sender address. You can also specify the Return Path name.

	$mail->ReturnPath ("answer@mycompany.com");
	$mail->ReturnPath ("answer@mycompany.com", "My Company Support");

Priority ([integer $priority])

Defines the mail priority. Optional.

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

	$mail->Priority (1); // urgent
	$mail->Priority (3); // normal
	$mail->Priority (5); // lowest priority

Receipt ([boolean flag])

Add a receipt to the mail. This is a mechanism 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.
The flag parameter was added in version 1.5.0; it defaults to true. If set to false, it cancels any previous call of the Receipt() method, i.e. no longer sends a receipt request.

	$mail->Receipt ();
	$mail->Receipt (false); // I changed my mind (1.5.0 and up)
Warning: this mechanism is not standardised, thus not fully supported by mail clients.

Send ()

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

	$mail->Send ();

Get ([boolean full_headers])

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.

In version 1.4.2 and below, the full_headers parameter is not available; Subject and To headers are not included in the return value.

In version 1.5.0 and above, the full_headers parameter determines whether Subject and To headers should be included in the return value.
true: Subject and To headers are included in the return value (this is the default).
false: they are not included (1.4.x-like behaviour).

In other words, starting with version 1.5.0, Subject and To are included in the return value, but you can call Get(false) to force 1.4.x-like behaviour.

	$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

Please note: some users hate receiving e-mail in HTML format.

To send a HTML mail with libMail 1.4.x and below, 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");

With libMail 1.4.2, you don't need to save your HTML as a file first; you can take advantage of the new AttachString method:

	$html_content = "<html>...</html>";
	$mail->Body ("This mail is formatted in HTML - shame on me");
	$mail->AttachString ($html_content, "text/html", "inline");

A bug in libMail 1.4.1 and below also allowed users to send HTML mail like this:

	$html_content = "<html>...</html>";
	$mail->Body ($html_content);
	$mail->Attach ("noattach"); // or any non-existent file

This resulted in a broken e-mail message, which some clients and webmails were able to display "correctly" nonetheless, while other clients failed.
As version 1.4.2 tries to be a drop-in replacement for 1.4.1, it includes a kludge so that this broken functionality is kept, so long as the e-mail begins with an <html> tag (or <? or $lt;!); this kludge is removed in version 1.5.0. You should not rely on this method to send HTML mail, as the resulting e-mails will not be displayed correctly by some users, even if they have an HTML-enabled e-mail client.

Starting with libMail 1.5.0, the methods described above are deprecated (including the "good" ones). You should instead take advantage of the new Html() method, as well as include a plain text alternative:

	$text_content = "Hello, world!\n";
	$html_content = "<html><body><p>Hello, world!</p></body></html>";
	$mail->Body ($text_content);
	$mail->Html ($html_content);

This will create an e-mail with a multipart/alternative section that includes the two versions of your content. While you may use Html() alone without setting a plain text Body(), this is not recommended. Also, don't use Body() for HTML content.

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

Status

Name libmail
Lang php4 (4.3.0 and up)
Version 1.5.0
Lastmod Fri Jan 04 09:55 GMT 2008
Authors Leo West, Setec Astronomy, Pier Luigi Pau

Summary

  1. LIBMAIL
    1. Description
    2. ChangeLog
    3. Synopsis
    4. Installation
    5. Documentation
      1. Constructor
      2. Subject ([string subject])
      3. From (string from_email, [string from_name])
      4. To (mixed address)
      5. CC (mixed address)
      6. BCC (mixed address)
      7. Body ([string body], [string charset] )
      8. Text ([string body], [string charset] )
      9. Html ([string body], [string charset] )
      10. SetCharset (string charset)
      11. Attach (string filepath, [string mimetype], [string disposition], [string filename])
      12. AttachString (string content, [string mimetype], [string disposition], [string filename])
      13. Organization (string $org)
      14. ReplyTo (string replyto_email, [string replyto_name])
      15. ReturnPath (string returnpath_email, [string returnpath_name])
      16. Priority ([integer $priority])
      17. Receipt ([boolean flag])
      18. Send ()
      19. Get ([boolean full_headers])
    6. Advices
      1. Send a mail in HTML format
    7. Statut
    8. Summary