Home » Mail » Mail » Manual

Introduction

Introduction – How to send a mail and the mailer backends

How To send a mail

Mail supports different types of backends to send email. So two steps are necessary to send an email.

• Step 1 Create a new instance of a specific Mail-Backend with the factory() method.
• Step 2 Send the mail using the send() method.

The mailer backends

Mail supports three types of backends:

• mail Sends a mail using PHP's built-in mail() function.
• sendmail Sends a mail using a sendmail program.
• smtp Sends a mail directly connecting to a smtp server.

Mail::factory()

Mail::factory() – creates a mailer instance

Synopsis

object &factory ( string $backend , array $params = array() )

Description

Creates a instance of a backend-specific mailer class.

Parameter

• string $backend - the name of the backend "mail","smtp", "sendmail"
• array $params - a array of backend specific parameters. List of parameter for the backends
  • mail
    • If safe mode is disabled, $params will be passed as the fifth argument to the PHP mail() function. If $params is an array, its elements will be joined as a space-delimited string.
  • sendmail
    • $params["sendmail_path"] - The location of the sendmail program on the filesystem. Default is /usr/bin/sendmail.
    • $params["sendmail_args"] - Additional parameters to pass to the sendmail. Default is -i.
  • smtp
    • $params["host"] - The server to connect. Default is localhost.
    • $params["port"] - The port to connect. Default is 25.
    • $params["auth"] - Whether or not to use SMTP authentication. Default is FALSE.
    • $params["username"] - The username to use for SMTP authentication.
    • $params["password"] - The password to use for SMTP authentication.
    • $params["localhost"] - The value to give when sending EHLO or HELO. Default is localhost
    • $params["timeout"] - The SMTP connection timeout. Default is NULL (no timeout).
    • $params["verp"] - Whether to use VERP or not. Default is FALSE.
    • $params["debug"] - Whether to enable SMTP debug mode or not. Default is FALSE. Mail internally uses Net_SMTP::setDebug .
    • $params["persist"] - Indicates whether or not the SMTP connection should persist over multiple calls to the send() method.
    • $params["pipelining"] - Indicates whether or not the SMTP commands pipelining should be used.

Return value

object - a specific Mail instance or a PEAR_Error object on failure.

Throws

Note

This function should be called statically.

See

"Introduction"

Mail::send()

Mail::send() – sends a mail

Synopsis

mixed send ( mixed $recipients , array $headers , string $body )

Description

Sends a mail. The send() method is provided by the object returned from factory()

Parameter

• mixed $recipients - an array or a string with comma separated recipients.
• array $headers - an associative array of headers. The header name is used as key and the header value as value. If you want to override the envelope sender of the email, set the Return-Path header and that value will be used instead of the value of the From: header.
• string $body - the body of the email.

Return value

boolean - TRUE or a PEAR_Error object on failure.

Throws

<?php
$headers['From'] = 'mymail@example.com';
?>

<?php
$headers['From'] = 'mymail@example.com';
?>

Note

This function can not be called statically.

Example

<?php
include('Mail.php');

$recipients = 'joe@example.com';

$headers['From']    = 'richard@example.com';
$headers['To']      = 'joe@example.com';
$headers['Subject'] = 'Test message';

$body = 'Test message';

$params['sendmail_path'] = '/usr/lib/sendmail';

// Create the mail object using the Mail::factory method
$mail_object =& Mail::factory('sendmail', $params);

$mail_object->send($recipients, $headers, $body);
?>

See

Mail::factory()

RFC822 - Introduction

RFC822 - Introduction – email address validation

Description

This class performs email address checking according to the RFC822 specification.

Note that the class only checks for a proper format of the indicated email address. This means it is not guaranteed that the email address itself exists or is owned by the particular user. You may also want to send the user an email, and force them to respond.

Mail_RFC822::parseAddressList()

Mail_RFC822::parseAddressList() – extract the parts of a list of email addresses

Synopsis

array parseAddressList ( string $address = '' , string $defaultDomain = 'localhost' , boolean $nestGroups = null , boolean $validate = null )

Description

Extracts the given addresses into their parts.

Parameter

• string $address - the address(es) to validate
• string $defaultDomain - the default domain to use in case of absence in the given email address.
• boolean $nestGroups - whether to return the structure with groups nested for easier viewing.
• boolean $validate - whether to validate atoms. Turn this off if you need to run addresses through before encoding the personal names, for instance.

Return value

array - a nested array of anonymous objects.

If $nestGroups set to FALSE, you can jump over the next paragraph.

Every array entry contains an object per group. This object has two attributes:

• groupname - the name of the group
• addresses - an array of all addresses of a group

The addresses array consists of an array of anonymous objects for each address. This object comes with the following attributes:

• personal - the name of the address owner
• comment - an array, an entry for each comment per address
• mailbox - the name of the mailbox, the part before the @
• host - the name of the server, the part after the @

Throws

Note

This function can be called statically.

This class checks the string only. It does not check for the existence of an email address.

Example

Extract some addresses

<?php
$address = 'My group: "Richard" <richard@localhost>;, ted@example.com (A comment)';

$addresses = Mail_RFC822::parseAddressList($address, 'phpguru.org', TRUE);
print_r($addresses);
?>