activeMailLib Manual v0.1

What is activeMailLib?
activeMailLib is a PHP class to validate and send MIME E-mail messages using the PHP function mail().

What can activeMailLib actually do?
activeMailLib can generate MIME TEXT or HTML E-mail messages with user defined headers, body parts and character encoding. File parts (attachments) can be included in the generated messages too. It is also capable of doing E-mail address validation based on a regular expression and optionally on the PHP function getmxrr() (UNIX systems).

activeMailLib methods overview
  • activeMailLib([$type]) -> Class constructor. The parameter $type sets the E-mail type ('plain' or 'html') and is optional. The default value is 'plain'.
  • enableAddressValidation() -> Checks automatically the validity of an E-mail address based on a regular expression. Each of the following methods, that has an invalid E-mail address, will not procced.
  • enableServerValidation() -> Checks automatically the validity of an E-mail address based on the PHP function getmxrr() (UNIX). Each of the following methods, that has an invalid E-mail server, will not procced. On Windows systems there will be no validation.
  • To($mail) -> Sets the E-mail recipient. The parameter $mail is the recipient`s E-mail address (string or array). Multiple addresses can be set if $mail is an array. This method is required to create and send an E-mail message.
  • From($mail,[$name]) -> Sets the E-mail sender. The parameter $mail is the sender`s E-mail address (string). The optional parameter $name is the sender`s name (string). This method is required to create and send an E-mail message.
  • Reply($mail) -> Sets a different reply E-mail address than the sender`s. The parameter $mail is the reply E-mail address (string). This method modifies the value of the following header: 'Reply-To' (default: the sender`s E-mail address).
  • Cc($mail) -> Sets the E-mail carbon copy recipient. The parameter $mail is the recipient`s E-mail address (string).
  • Bcc($mail) -> Sets the E-mail blind carbon copy recipient. The parameter $mail is the recipient`s E-mail address (string).
  • Subject([$var]) -> Sets the E-mail subject. The parameter $var is optional (string).
  • Message([$var,$charset,$encoding]) -> Sets the E-mail message body. Use the optional method parameters as follows: $var: message (string); $charset: message charset (default: 'iso-8859-1'); $encoding: message encoding e.g '8bit', '7bit', 'binary', 'base64' and 'quoted-printable' (default: 'quoted-printable').
  • Attachment($filepath,[$filename,$maxsize,$disp,$type]) -> Sets a file part (attachment) to the E-mail message (base64 encoding). The parameter $filepath is the path (for local server and uploaded files) or the URL of the file to be attached (string). To use an URL for the file please make sure that the parameter allow_url_fopen in php.ini is set true. Use the other optional method parameters as follows: $filename: the name you want the attachment file to have in the E-mail message (string). The default value is the file path or URL; $maxsize: the maximal size in bytes of the attachment file (only for local server or uploaded files). Set it to false, if no file size validation is necessary (default: false); $disp: file disposition: 'attachment' or 'inline' (default: 'attachment'); $type: file content type (default: 'application/octet-stream'). Call this method multiple times, if multiple attachments are necessary. The method returns false if the file or the url could not be found.
  • Priority($num) -> Sets the E-mail priority using the parameter $num (ignored by many E-mail programs). Accepted values are: 1 (for highest priority) to 5 (for lowest priority). The method creates the following headers: 'Priority', 'X-Priority' and 'X-MSMail-Priority'.
  • Receipt([$mail]) -> Returns a receipt to the E-mail address set by the optional parameter $mail, when the E-mail is read (ignored by many E-mail programs). If no parameter is set, a receipt will be sent to the E-mail sender. The method creates the following headers: 'Disposition-Notification-To' and 'X-Confirm-Reading-To'.
  • Send() -> Sends the E-mail message using the PHP function mail(). The class methods From() and To() have to be at least called to generate and send the E-mail message.
  • isSent($mail) -> Returns true if an E-mail message was sent to the E-mail address $mail or false if not. Call this method after calling the method Send().
  • checkAddress($mail) -> Checks the validity of the E-mail address $mail based on a regular expression. Call this method if you want to validate the E-mail address manually, before sending an E-mail. It returns true if the E-mail address was found valid or false if not.
  • checkServer($mail) -> Checks the validity of the E-mail address $mail based on the PHP function getmxrr() (UNIX). Call this method if you want to validate the E-mail server manually, before sending an E-mail. It returns true if the E-mail server was found valid or false if not. On Windows systems there will be no validation and the method returns true.
  • getRawData() -> Returns the E-mail recipient(s), the E-mail subject, the E-mail message body and the generated E-mail headers as an html string (test function).

activeMailLib E-mail validation regular expression
^[_a-zA-Z0-9-](\.{0,1}[_a-zA-Z0-9-])*@([a-zA-Z0-9-]{2,}\.){0,}[a-zA-Z0-9-]{3,}(\.[a-zA-Z]{2,4}){1,2}$

activeMailLib code examples
SIMPLE TEXT E-MAIL SIMPLE HTML E-MAIL WITH MANY RECIPIENT
<?php
require_once("activeMailLib.php");
$email = new activeMailLib();
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To("you@yourhost.com");//set a valid E-mail
$email->Subject("activeMailLib Text Mail");
$email->Message("This is an test for the activeMailLib");
$email->Send();
?> 		<?php
require_once("activeMailLib.php");
$to=array("you@yourhost.com","info@yourhost.com")//set valid E-mails
$email = new activeMailLib("html");
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To($to);
$email->Subject("activeMailLib HTML Mail");
$email->Message("This is an test for the <b>activeMailLib</b>");
$email->Send();
?>
SIMPLE TEXT E-MAIL WITH VALIDATION (MANUALLY) SIMPLE HTML E-MAIL WITH VALIDATION (AUTOMATICALLY)
<?php
require_once("activeMailLib.php");
$to="you@@yourhost..com";//invalid E-mail
$email = new activeMailLib();
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To($to);
$email->Subject("activeMailLib Text Mail");
$email->Message("This is an test for the activeMailLib");
if ($email->checkAddress($to)) $email->Send();
else print "Invalid E-mail: ".$to;
?> 		<?php
require_once("activeMailLib.php");
$to="you@@yourhost..com";//invalid E-mail
$email = new activeMailLib("html");
$email->enableAddressValidation();
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To($to);
$email->Subject("activeMailLib HTML Mail");
$email->Message("This is an test for the <b>activeMailLib</b>");
$email->Send();
//this E-mail was not sent. If you want to be sure:
if ($email->isSent($to)) print "E-mail sent: ".$to;
else print "Invalid E-mail: ".$to;
?>
SIMPLE TEXT E-MAIL WITH SERVER FILE ATTACHMENTS SIMPLE HTML E-MAIL WITH AN UPLOADED FILE ATTACHMENT
<?php
require_once("activeMailLib.php");
$att1="files/somefile1.txt";//set a valid file path
$att2="files/somefile2.txt";//set a valid file path
$email = new activeMailLib();
$email->enableAddressValidation();
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To("you@yourhost.com");//set a valid E-mail
$email->Subject("activeMailLib Text Mail");
$email->Message("This is an test for the activeMailLib");
$email->Attachment($att1,"somename1.txt");
$email->Attachment($att2,"somename2.txt");
$email->Send();
?> 		<?php
require_once("activeMailLib.php");
$email = new activeMailLib("html");
$email->enableAddressValidation();
$email->From("webmaster@yourhost.com");//set a valid E-mail
$email->To("you@yourhost.com");//set a valid E-mail
$email->Subject("activeMailLib HTML Mail");
$email->Message("This is an test for the <b>activeMailLib</b>");
if (isset($_FILES['att'])){
$email->Attachment($_FILES['att']['tmp_name'],$_FILES['att']['name']);
}
$email->Send();
?>

(c) Giorgos Tsiledakis, Crete Greece