Email Documentation

This documentation refers to the 2.0.1 revision of email. For other versions please see the documentation included with your download.

For more information, not presented here, please see the email website or contact the author by sending a message to <jtjacques@users.sourceforge.net>.

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-2008 Jason Jacques <jtjacques@users.sourceforge.net>.

Email is licensed under the MIT license, a copy of which is shown here.

Copyright (c) 2005-2008 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.

Returns TRUE on success, FALSE on failure.

name (optional)

The name of the recipient.

email

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.

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

Email address.

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.0.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.0.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->addHeader('From', '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->addHeader('MIME-Version', '1.0');
$email->addHeader('Content-type', 'text/html; charset=iso-8859-1');

// Additional headers
$email->addHeader('To', 'Mary <mary@example.com>, Kelly <kelly@example.com>');
$email->addHeader('From', '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).

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.

Note: email() does not parse the CC: or BCC: headers. Mail is only delivered to the user or users specified in the to parameter.

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.

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.