Home » Networking » Net_SMTP » Manual

Class Summary Net_SMTP

Class Summary Net_SMTP – Provides an implementation of the SMTP protocol using PEAR's Net_Socket:: class.

Provides an implementation of the SMTP protocol using PEAR's Net_Socket:: class.

This package implements the Simple Mail Transfer Protocol (SMTP), Internet's standard host-to-host mail transport protocol, using the Net_Socket:: class for the server connection. The SMTP provides mechanisms for the transmission of mail.

Class Trees for Net_SMTP

• Net_SMTP

Introduction and Guide

Introduction and Guide – Provides an implementation of the SMTP protocol

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();
?>

constructor Net_SMTP::Net_SMTP

constructor Net_SMTP::Net_SMTP() – Instantiates a new Net_SMTP object, overriding any networkings with parameters that are passed in.

Synopsis

void constructor Net_SMTP::Net_SMTP ( string $host = null , int $port = null , string $localhost = null )

Description

Constructor,Instantiates a new Net_SMTP object.

Parameter

string $host

The server to connect to.

integer $port

The port to connect to.

string $localhost

The value to give when sending EHLO or HELO.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::auth

Net_SMTP::auth() – Attempt to do SMTP authentication.

Synopsis

mixedNet_SMTP::auth ( string $uid , string $pwd , string $method = '' )

Description

This function initializes an authentication session using the supported methods. These are, in order of preference: Digest-MD5,CRAMMD5,LOGIN, and PLAIN.

Parameter

string $uid

The userid to authenticate as.

string $pwd

The password to authenticate with.

string $method

The requested authentication method.If none is specified, the best supported method will be used.

boolean $tls

Flag indicating whether or not TLS should be attempted.

string $authz

An optional authorization identifier. If specified, this identifier will be used as the authorization proxy.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::connect

Net_SMTP::connect() – Attempt to connect to the SMTP server.

Synopsis

mixed Net_SMTP::connect ( int $timeout = null )

Description

Attempt to establish a connection with the SMTP server

Parameter

integer $timeout

The timeout value (in seconds) for thesocket connection.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::data

Net_SMTP::data() – Send the DATA command to start message body

Synopsis

mixedNet_SMTP::data ( string $data )

Description

This function sends the message body with the DATA command and terminates the message session.

Parameter

string $data

The message body to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::disconnect

Net_SMTP::disconnect() – Attempt to disconnect from the SMTP server.

Synopsis

mixedNet_SMTP::disconnect ( )

Description

Attempt to close the connection with the SMTP server.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::getResponse

Net_SMTP::getResponse() – Return a 2-tuple containing the last response from the SMTP server.

Synopsis

array Net_SMTP::getResponse ( )

Description

Return a two-element array containing the last response from the SMPT server.

Return value

returns A two-element array: the first element contains the response code as an integer and the second element contains the response's arguments as a string.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::helo

Net_SMTP::helo() – Send the HELO command.

Synopsis

mixed Net_SMTP::helo ( string $domain )

Description

Send the HELO command which is the first part of a mail-sending SMTP transaction where the Internet extender first tries to send mail.

Parameter

string $domain

The domain name to say we are.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::identifySender

Net_SMTP::identifySender() – Backwards-compatibility method.identifySender()'s functionality is now handled internally.

Synopsis

booleanNet_SMTP::identifySender ( )

Description

Backwards-compatibility method.identifySender()'s functionality is now handled internally.

Return value

returns This method always return true.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::mailFrom

Net_SMTP::mailFrom() – Send the MAIL FROM: command.

Synopsis

mixedNet_SMTP::mailFrom ( string $sender )

Description

Send the MAIL FROM: command

Parameter

string $sender

The sender (reverse path) to set.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::noop

Net_SMTP::noop() – Send the NOOP command.

Synopsis

mixedNet_SMTP::noop ( )

Description

Send the NOOP command.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::quotedata

Net_SMTP::quotedata() – Quote the data so that it meets SMTP standards.

Synopsis

void Net_SMTP::quotedata ( string &$data )

Description

This is provided as a separate public function to facilitate easier overloading for the cases where it is desirable to customize the quoting behavior.

Parameter

string &$data

The message text to quote. The string must be passed by reference, and the text will be modified in place.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::rcptTo

Net_SMTP::rcptTo() – Send the RCPT TO: command.

Synopsis

mixedNet_SMTP::rcptTo ( string $recipient )

Description

sends the RCPT TO SMTP protocol command

Parameter

string $recipient

The recipient (forward path) to add.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::rset

Net_SMTP::rset() – Send the RSET command.

Synopsis

mixed Net_SMTP::rset ( )

Description

Sends the RSET SMTP protocol command.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::saml_from

Net_SMTP::saml_from() – Send the SAML FROM: command.

Synopsis

mixedNet_SMTP::saml_from ( string $path )

Description

Sends the SAML FROM SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::send_from

Net_SMTP::send_from() – Send the SEND FROM: command.

Synopsis

mixed Net_SMTP::send_from ( string $path )

Description

Sends the SEND FROM SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::setDebug

Net_SMTP::setDebug() – Set the value of the debugging flag.

Synopsis

voidNet_SMTP::setDebug ( boolean $debug , callback $handler )

Description

Enables or disables debugging. Once debugging is enabled, messages preceded by "DEBUG: " are being echoed out.

See also Debugging introduction

Parameter

boolean $debug

New value for the debugging flag.

callback $handler

Callback function that gets called with Net_SMTP object and message to display.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::soml_from

Net_SMTP::soml_from() – Send the SOML FROM: command.

Synopsis

mixed Net_SMTP::soml_from ( string $path )

Description

Sends the SOML FROM: SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_SMTP::vrfy

Net_SMTP::vrfy() – Send the VRFY command.

Synopsis

mixed Net_SMTP::vrfy ( string $string )

Description

Sends the VRFY SMTP protocol command.

Parameter

string $string

The string to verify

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.