About Email
Information about the email script.
What is email?
Email is a multi-platform MTA script for PHP 4.3 and above. Email brings configuration free mail deployment to PHP by utilising core PHP APIs to directly deliver mail to their intended destinations and giving real-time indications of delivery success.
Email utilises a comprehensive object model to allow safe, reliable constructs for mail creation and dispatch. For backwards compatibility, and full functional compatibility with the built in PHP mail() function email also provides a function method which can be invoked to provide simpler, more compatible access.
Why use email?
Email provides a configuration free method of sending mail from PHP scripts and does not depend on sendmail or a third party SMTP relay server as with the built in mail() function. Email also provides real-time feedback on the mail delivery status allowing much more intelligent script operation. To improve the chance of successful message delivery email uses intelligent defaults for all the required fields of a message - significantly reducing the delivery failure rate with no additional effort on the part of the developer.
Email provides a powerful object-oriented system to send mail from PHP scripts which allows messages to be easily created and sent using simple and intelligent access methods. One of email's most popular uses is as a drop-in replacement for the PHP mail() function where it provides full functional compatibility using the email() function call method of invocation.
Why not to use email
Simply put, email is inefficient. As email has to directly contact the receiving server for each message and actually push the message content to that server; email introduces an appreciable delay in sending each message. While this direct access allows email to provide real-time delivery status information it can also hold up the script to an unacceptable level.
Email also opens an SMTP connection for each message it dispatches, rather than sending messages destined for the same provider in a bulk transaction. This creates additional DNS look-up and connection delays. One of the long term development goals for email is to intelligently batch together messages sent in the same call to remove these additional delays.
System Requirements
Email requires PHP 4.3 or above and fully supports PHP 5. To maintain compatibility with PHP 4 email lacks private variables and methods. As such only documented methods are supported.
Comments
Comments, suggestions, support and feature requests can be directed to jtjacques@users.sourceforge.net. Please be aware that it may take some time to respond to requests and without detailed information it may not be possible to offer assistance.
Bug Reporting
If you are submitting a bug or support request, please provide the output of getStatus() if possible in your message as this will greatly reduce debugging time in most cases. If you are using the function interface, email(), please attempt to use the object interface to verify correct operation in your environment before submitting a support request.
Copyright & License
Email is Copyright © 2005-2009 Jason Jacques <jtjacques@users.sourceforge.net>.
Email is licensed under the MIT license, a copy of which is shown here.
Copyright (c) 2005-2009 Jason Jacques <jtjacques@users.sourceforge.net> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Object Reference
Email includes an object oriented interface which provides simple and powerful access to all available features.
Methods
Email contains many methods to allow messages to be easily generated and dispatched. Undocumented methods may change between releases and are not recommended for production use.
email ( [string $dns] ) constructor
Returns object.
dns (optional)
The IP address or fully qualified domain name of a recursive DNS server. This allows the default DNS server, 208.67.222.222 provided by OpenDNS, to be changed.
setDNS ( string $dns )
Allows the default DNS server, 208.67.222.222 provided by OpenDNS, to be changed.
Returns TRUE on success, FALSE on failure.
dns
The IP address or fully qualified domain name of a recursive DNS server.
addRecipient ( [string $name,] string $email )
Adds a recipient for this message.
Note: only addresses specified using addRecipient() will receive a copy of the message. Email does not parse message headers.
Returns TRUE on success, FALSE on failure.
name (optional)
The name of the recipient.
The email address of the recipient.
setSubject ( string $subject )
Sets the message subject.
Returns TRUE on success, FALSE on failure.
subject
The message subject.
addHeader ( string $header [, string $content] )
Adds a header for this message. If header already exists, overwrite. Headers must be added one at a time.
Note: only addresses specified using addRecipient() will receive a copy of the message. Email does not parse message headers.
Returns TRUE on success, FALSE on failure.
header
The name of the header or full header including content, colon delimited.
content (optional)
The content for the header.
setMessage ( string $message )
Sets the message content.
Returns TRUE.
message
Freeform message content.
Each line should be seperated with a LF (\n). Lines should not be longer than 70 characters.
setAnnounceEmail ( string $email )
The email to report during connection to the receiving mail server. Defaults to the address specified in the From header if not specified.
Returns TRUE on success, FALSE on failure.
Email address.
setFrom ( [string $name,] string $email )
Specify the sender of the message.
Returns TRUE on success, FALSE on failure.
name (optional)
The name of the sender.
The email address of the sender.
setHTML ( [ string $charSet ] )
Add the required headers to send a HTML formatted mail message and identifies the character set used by the message.
Returns TRUE on success, FALSE on failure.
charSet
Character set used in the message. Defaults to iso-8859-1.
send ( )
Sends the message.
Returns TRUE on success, FALSE on failure.
Unsupported Methods
These methods are unsupported and may change from release to release, however, they are documented for more advanced use of the library.
getStatus ( )
Returns a status array. The array has one top level item for each destination address.
Returns Array.
Example Array
For the purpose of bug reporting binary responses are base64 encoded to preserve data. Message content is ROT13 encoded to provided limited privacy. Note: If submitting a bug report you may remove the message data and subject header. Please leave any email addresses intact as this will assist with debugging.
In this example we see the first address fail as email was unable to connect to the MX server. This is indicated by the blank representing a FALSE value after the [connected] key in the array. In fact upon further investigation we find that there is no MX server for homedsl.co.uk and email intelligently fell back to the domain itself.
With the second address a connection was made to a GMail MX server, which refused the message. On further investigation we find that our IP address is on the residential list (which it is indeed) at http://www.spamhaus.org/ and many services such as Hotmail and GMail will refuse mail from this IP address.
Array
(
[0] => Array
(
[name] => Jason Jacques
[address] => jason@homedsl.co.uk
[domain] => homedsl.co.uk
[mxAddress] => homedsl.co.uk
[fromAddress] => jtjacques@users.sourceforge.net
[headers] => To: "Jason Jacques" <jason@homedsl.co.uk>
Subject: This is a test message.
From: jtjacques@users.sourceforge.net
Date: Thu, 08 Nov 2007 16:14:16 +0000
X-Mailer: email 2.1.0
[message] => Guvf vf n grfg zrffntr.
[connected] =>
)
[1] => Array
(
[name] => jtjacques@gmail.com
[address] => jtjacques@gmail.com
[domain] => gmail.com
[mxAddress] => gmail-smtp-in.l.google.com.
[fromAddress] => jtjacques@users.sourceforge.net
[headers] => To: "jtjacques@gmail.com" <jtjacques@gmail.com>
Subject: This is a test message.
From: jtjacques@users.sourceforge.net
Date: Thu, 08 Nov 2007 16:14:16 +0000
X-Mailer: email 2.1.0
[message] => Guvf vf n grfg zrffntr.
[connected] => 1
[mxResponse] => Array
(
[0] => 220 mx.google.com ESMTP 31si4031447ugg
[1] => 250 mx.google.com at your service
[2] => 250 2.1.0 OK
[3] => 250 2.1.5 OK
[4] => 354 Go ahead
[5] => 550-5.7.1 [79.76.xxx.xxx] The IP you're using to send email is not authorized
[6] => 550-5.7.1 to send email directly to our servers. Please use
)
)
)
checkValue ( string $variable )
Returns value of variable specified.
variable
The variable to read.
mxQuery class
The mxQuery class is a supporting class which allows the system to perform an MX lookup on unsupported operating systems. The interfaces may change at any time and the class is entirely unsupported.
Examples
Example 1. Sending mail.
Use email to send a simple message:
<?php
// Include email class and email() function
require_once('email.php');
// Create new instance of email
$email = new Email();
// Add recipient
$email->addRecipient('caffinated@example.com');
// Set subject
$email->setSubject('My Subject');
// Set message
$email->setMessage("Line 1\nLine 2\nLine 3");
// Send message
$email->send();
?>
Example 2. Sending mail with additional headers.
The addition of basic headers, telling the MUA the From and Reply-To addresses:
<?php
// Include email class and email() function
require_once('email.php');
// Create new instance of email
$email = new Email();
$email->addRecipient('nobody@example.com');
$email->setSubject('the subject');
// Additional headers
$email->setFrom('webmaster@example.com');
$email->addHeader('Reply-To', 'webmaster@example.com');
$email->addHeader('X-Mailer', 'PHP/' . phpversion());
$email->setMessage('hello');
$email->send();
?>
Example 3. Setting the envelope sender.
The system can report a different sender to the receiving mail server during the connection process. This is equivilant to the -f parameter on previous versions of email.
<?php
// Include email class and email() function
require_once('email.php');
// Create new instance of email
$email = new Email();
$email->addRecipient('nobody@example.com');
$email->setSubject('the subject');
$email->setMessage('the message');
// Set envelope sender reported to destination MX server
$email->setAnnounceEmail('webmaster@example.com');
$email->send();
?>
Example 4. Sending HTML mail.
It is also possible to send HTML messages with email().
<?php
// Include email class and email() function
require_once('email.php');
// Create new instance of email
$email = new Email();
// Multiple recipients
$email->addRecipient('aidan@example.com');
$email->addRecipient('wez@example.com');
// Subject
$email->setSubject('Birthday Reminders for August');
// message
$message = '
<html>
<head>
<title>Birthday Reminders for August</title>
</head>
<body>
<p>Here are the birthdays upcoming in August!</p>
<table>
<tr>
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
</tr>
<tr>
<td>Joe</td><td>3rd</td><td>August</td><td>1970</td>
</tr>
<tr>
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
</tr>
</table>
</body>
</html>
';
$email->setMessage($message);
// To send HTML mail, the Content-type header must be set
$email->setHTML();
// Additional headers
$email->addHeader('To', 'Mary <mary@example.com>, Kelly <kelly@example.com>');
$email->setFrom('Birthday Reminder', 'birthday@example.com');
$email->addHeader('Cc', 'birthdayarchive@example.com');
$email->addHeader('Bcc', 'birthdaycheck@example.com');
// Send message
$email->send();
?>
Function Reference
Email includes a function interface to allow it to be used as a drop in replacement for the built in PHP function, mail().
Requirements
To use email the email script must be included into the calling script. It is strongly recommended that this is done using the require_once() directive, just prior to the execution of email(). The following example assumes the email.php script is located in the same directory or in the PHP include path.
<?php // Include email class and email() function require_once('email.php'); ?>
Description
bool email ( string $to, string $subject, string $message [, string $additional_headers [, string $additional_parameters]] )
Sends an email message.
Parameters
to
Receiver or recievers of the email.
The fomatting of this string must comply to RFC 2822. Some examples are:
user@example.com
user@example.com, anotheruser@example.com
User <user@example.com>, Another User
<anotheruser@example.com>
subject
Subject of the message to be sent.
message
Message to be sent.
Each line should be seperated with a LF (\n). Lines should not be longer than 70 characters.
additional_headers (optional)
String to be inserted at the end of the message header.
This is typically used to add extra headers (From, Cc, and Bcc). Multiple headers should be seperated by CRLF (\r\n).
Note: only addresses specified using to parameter will receive a copy of the message. Email does not parse message headers.
additional_parameters (optional)
The additional_parameters parameter can be used to pass additional parameters to email(). At present the only avaliable additional parameter is the -f parameter to set the envelope sender. See Example 3. for an example. Other additional parameters will be ignored.
Return Values
Returns TRUE if the message was successfully delivered, FALSE otherwise.
Examples
Example 1. Sending mail.
Use email to send a simple message:
<?php
// Include email() function.
require_once("email.php");
// The message
$message = "Line 1\nLine 2\nLine 3";
// Send
email('caffinated@example.com', 'My Subject', $message);
?>
Example 2. Sending mail with additional headers.
The addition of basic headers, telling the MUA the From and Reply-To addresses:
<?php
// Include email() function.
require_once("email.php");
$to = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = 'From: webmaster@example.com' .
"\r\n" .
'Reply-To: webmaster@example.com' . "\r\n" .
'X-Mailer: PHP/' .
phpversion();
email($to, $subject, $message, $headers);
?>
Example 3. Sending mail with an additional command line parameter.
The additional_parameters parameter can be used to send an additional parameter to the function.
<?php
// Include email() function.
require_once("email.php");
email('nobody@example.com', 'the subject', 'the message', null,
'-fwebmaster@example.com');
?>
Example 4. Sending HTML mail.
It is also possible to send HTML messages with email().
<?php
// Include email() function.
require_once("email.php");
// multiple recipients
$to = 'aidan@example.com' . ', '; //
note the comma
$to .= 'wez@example.com';
// subject
$subject = 'Birthday Reminders for August';
// message
$message = '
<html>
<head>
<title>Birthday Reminders for August</title>
</head>
<body>
<p>Here are the birthdays upcoming in August!</p>
<table>
<tr>
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
</tr>
<tr>
<td>Joe</td><td>3rd</td><td>August</td><td>1970</td>
</tr>
<tr>
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
</tr>
</table>
</body>
</html>
';
// To send HTML mail, the Content-type header must be
set
$headers = 'MIME-Version: 1.0' . "\r\n";
$headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";
// Additional headers
$headers .= 'To: Mary <mary@example.com>, Kelly
<kelly@example.com>' . "\r\n";
$headers .= 'From: Birthday Reminder <birthday@example.com>' . "\r\n";
$headers .= 'Cc: birthdayarchive@example.com' . "\r\n";
$headers .= 'Bcc: birthdaycheck@example.com' . "\r\n";
// Mail it
email($to, $subject, $message, $headers);
?>
Notes
Differences exist between mail() and email(). Please ensure that your particular application is suited before switching between the two functions.
Note: additional_parameters only supports -f as email() does not utilise sendmail.
See Also
Notes
These notes refer to email() when utilised via the function or object interfaces.
General Notes
Note: It is worth noting that email is not suited to large volumes of email in a loop. This function opens and closes an SMTP connection and completes a DNS look-up for each receiving address for the message which is not very efficient.
Note: email() does not parse the TO:, CC: or BCC: headers. Mail is only delivered to the user or users specified using the addRecipient method (object interface) or in the to parameter (function interface).
Terminology
Note: email refers to the email.php script you have downloaded; mail and message refer to the actual message and associated content the script will send to an internet user; mail() refers to the built in PHP mail() function.