PHP CookBook

Recipe 17.2 Sending Mail

17.2.1 Problem

You want to send an email message. This can be in direct response to a user's action, such as signing up for your site, or a recurring event at a set time, such as a weekly newsletter.

17.2.2 Solution

Use PEAR's Mail class:

require 'Mail.php';

$to = 'adam@example.com';

$headers['From'] = 'webmaster@example.com';
$headers['Subject'] = 'New Version of PHP Released!';

$body = 'Go to http://www.php.net and download it today!';

$message =& Mail::factory('mail');
$message->send($to, $headers, $body);

If you can't use PEAR's Mail class, use PHP's built-in mail( ) function:

$to = 'adam@example.com';
$subject = 'New Version of PHP Released!';
$body = 'Go to http://www.php.net and download it today!';
  
mail($to, $subject, $body);

17.2.3 Discussion

PEAR's Mail class allows you to send mail three ways. You indicate the method to use when instantiating a mail object with Mail::factory( ).

• To send mail using an external program such as sendmail or qmail, pass sendmail.

• To use an SMTP server, pass smtp.

• To use the built-in mail( ) function, pass mail. This tells Mail to apply the settings from your php.ini.

To use sendmail or smtp, you have to pass a second parameter indicating your settings. To use sendmail, specify a sendmail_path and sendmail_args:

$params['sendmail_path'] = '/usr/sbin/sendmail';
$params['sendmail_args'] = '-oi -t';

$message =& Mail::factory('sendmail', $params);

One good value for sendmail_path is /usr/lib/sendmail. Unfortunately, sendmail tends to jump around from system to system, so it can be hard to track down. If you can't find it, try /usr/sbin/sendmail or ask your system administrator.

Two useful flags to pass sendmail are -oi and -t. The -oi flag tells sendmail not to think a single dot (.) on a line is the end of the message. The -t flag makes sendmail parse the file for To: and other header lines.

If you prefer qmail, try using /var/qmail/bin/qmail-inject or /var/qmail/bin/sendmail.

If you're running Windows, you may want to use an SMTP server because most Windows machines don't have copies of sendmail installed. To do so, pass smtp:

$params['host'] = 'smtp.example.com';

$message =& Mail::factory('smtp', $params);

In smtp mode, you can pass five optional parameters. The host is the SMTP server hostname; it defaults to localhost. The port is the connection port; it defaults to 25. To enable SMTP authentication, set auth to true. To allow the server to validate you, set username and password. SMTP functionality isn't restricted to Windows; it also works on Unix servers.

If you don't have PEAR's Mail class, you can use the built-in mail( ) function. The program mail( ) uses to send mail is specified in the sendmail_path configuration variable in your php.ini file. If you're running Windows, set the SMTP variable to the hostname of your SMTP server. Your From address comes from the sendmail_from variable.

Here's an example that uses mail( ):

$to = 'adam@example.com';
$subject = 'New Version of PHP Released!';
$body = 'Go to http://www.php.net and download it today!';
  
mail($to, $subject, $body);

The first parameter is the recipient's email address, the second is the message subject, and the last is the message body. You can also add extra headers with an optional fourth parameter. For example, here's how to add Reply-To and Organization headers:

$to = 'adam@example.com';
$subject = 'New Version of PHP Released!';
$body = 'Go to http://www.php.net and download it today!';
$header = "Reply-To: webmaster@example.com\r\n"
         ."Organization: The PHP Group";

mail($to, $subject, $body, $header);

Separate each header with \r\n, but don't add \r\n following the last header.

Regardless of which method you choose, it's a good idea to write a wrapper function to assist you in sending mail. Forcing all your mail through this function makes it easy to add logging and other checks to every message sent:

function pc_mail($to, $headers, $body) {
    $message =& Mail::factory('mail');

    $message->send($to, $headers, $body);
    error_log("[MAIL][TO: $to]");
}

Here a message is written to the error log, recording the recipient of each message that's sent. This provides a time stamp that allows you to more easily track complaints that someone is trying to use the site to send spam. Another option is to create a list of "do not send" email addresses, which prevent those people from ever receiving another message from your site. You can also validate all recipient email addresses, which reduces the number of bounced messages.

17.2.4 See Also

Section 13.6 for a regular expression to validate email addresses; Section 17.3 for sending MIME email; Section 17.4 for more on retrieving mail; documentation on mail( ) at http://www.php.net/mail; the PEAR Mail class at http://pear.php.net/package-info.php?package=Mail; RFC 822 at http://www.faqs.org/rfcs/rfc822.html; O'Reilly publishes two books on sendmail, called sendmail by Bryan Costales with Eric Allman and sendmail Desktop Reference by Bryan Costales and Eric Allman.