Net_SMTP Introduction and Guide

The Net_SMTP package supports the SMTP authentication standard (as defined by RFC-2554). Net_SMTP supports several authentication methods like DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN.

Dependencies

The PEAR_Error Class

The Net_SMTP package uses the PEAR_Error class for all of its error handling.

The Net_Socket Package

The Net_Socket package is used as the basis for all network communications.

The Auth_SASL Package

The Auth_SASL package is an optional dependency. If it is available, the Net_SMTP package will be able to support the DIGEST-MD5 and CRAM-MD5 SMTP authentication methods. Otherwise, only the LOGIN and PLAIN methods will be available.

Error Handling

All of the Net_SMTP class's public methods return a PEAR_Error object if an error occurs. The standard way to check for a PEAR_Error object is by using PEAR::isError()

SMTP Authentication

The Net_SMTP package supports the SMTP authentication standard (as defined by RFC-2554). The Net_SMTP package supports the following authentication methods, in order of preference:

DIGEST-MD5

The DIGEST-MD5 authentication method uses RSA Data Security Inc.'s MD5 Message Digest algorithm. It is considered the most secure method of SMTP authentication.

The DIGEST-MD5 authentication method is only supported if the AUTH_SASL package is available.

CRAM-MD5

The CRAM-MD5 authentication method has been superseded by the DIGEST-MD5 method in terms of security. It is provided here for compatibility with older SMTP servers that may not support the newer DIGEST-MD5 algorithm.

The CRAM-MD5 authentication method is only supported if the AUTH_SASL package is available.

LOGIN

The LOGIN authentication method encrypts the user's password using the Base64 encoding scheme. Because decrypting a Base64-encoded string is trivial, LOGIN is not considered a secure authentication method and should be avoided.

PLAIN

The PLAIN authentication method sends the user's password in plain text. This method of authentication is not secure and should be avoided.

Secure Connections

If secure socket transports have been enabled in PHP, it is possible to establish a secure connection to the remote SMTP server:


<?php
$smtp = new Net_SMTP('ssl://mail.example.com', 465);
?>

This example connects to mail.example.com on port 465 (a common SMTPS port) using the ssl:// transport.

Data Quoting

By default, all outbound string data is quoted in accordance with SMTP standards. This means that all native Unix (\n) and Mac (\r) line endings are converted to Internet-standard CRLF (\r\n) line endings. Also, because the SMTP protocol uses a single leading period (.) to signal an end to the message data, single leading periods in the original data string are "doubled" (e.g. "..").

These string transformation can be expensive when large blocks of data are involved. For example, the Net_SMTP package is not aware of MIME parts (it just sees the MIME message as one big string of characters), so it is not able to skip non-text attachments when searching for characters that may need to be quoted.

Because of this, it is possible to extend the Net_SMTP class in order to implement your own custom quoting routine. Just create a new class based on the Net_SMTP class and reimplement the quotedata() method:


<?php
require 'Net/SMTP.php';

class Net_SMTP_custom extends Net_SMTP
{
    function quotedata($data)
    {
        /* Perform custom data quoting */
    }
}
?>

Note that the $data parameter will be passed to the quotedata() function by reference. This means that you can operate directly on $data. It also the overhead of copying a large $data string to and from the quotedata() method.

Debugging

The Net_SMTP package contains built-in debugging output routines (disabled by default). Debugging output must be explicitly enabled via the setDebug() method:


<?php
$smtp->setDebug(true);
?>

The debugging messages will be sent to the standard output stream.

Examples

The following script demonstrates how a simple email message can be sent using the Net_SMTP package:


<?php
require 'Net/SMTP.php';

$host = 'mail.example.com';
$from = 'user@example.com';
$rcpt = array('recipient1@example.com', 'recipient2@example.com');
$subj = "Subject: Test Message\n";
$body = "Body Line 1\nBody Line 2";

/* Create a new Net_SMTP object. */
if (! ($smtp = new Net_SMTP($host))) {
    die("Unable to instantiate Net_SMTP object\n");
}

/* Connect to the SMTP server. */
if (PEAR::isError($e = $smtp->connect())) {
    die($e->getMessage() . "\n");
}

/* Send the 'MAIL FROM:' SMTP command. */
if (PEAR::isError($smtp->mailFrom($from))) {
    die("Unable to set sender to <$from>\n");
}

/* Address the message to each of the recipients. */
foreach ($rcpt as $to) {
    if (PEAR::isError($res = $smtp->rcptTo($to))) {
        die("Unable to add recipient <$to>: " . $res->getMessage() . "\n");
    }
}

/* Set the body of the message. */
if (PEAR::isError($smtp->data($subj . "\r\n" . $body))) {
    die("Unable to send data\n");
}

/* Disconnect from the SMTP server. */
$smtp->disconnect();
?>

Introduction and Guide