PEAR Manual
Prev |  | Next

# Mail::send()

Mail::send() -- sends a mail

## Synopsis

    require_once 'Mail.php';

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

## Description

Sends a mail. The send()-function 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.

- `string $body` - the body of the email.

## Return value

`boolean` - `TRUE` or a PEAR_Error object, if fails

## Throws

Table 46-1. Possible PEAR_Error values

Mailer driver | Error code | Error message | Reason | Solution
--- | --- | --- | --- | ---
sendmail/smtp | `NULL` | "No from address given." | The `$headers` array requires at least a `from` entry. | Add a from header:
    $headers['From'] = 'mymail@example.com';
sendmail | `NULL` | "From address specified with dangerous characters." | The from entry in the `$headers` array contains one ore more characters which could be non-RFC compliant | Check the given from address for characters like: spaces or `;` or `&` or ``` (backtick)
sendmail | `NULL` | "sendmail [`path to sendmail`] not executable" | The path to sendmail program is not correct. No sendmail executable found there. | Check the `$param['sendmail_path']` entry in your Mail::factory() call. If you use another mailer then sendmail, ie. qmail, check installation of the mailer. Normally it should includes a sendmail wrapper.
sendmail | `NULL` | "sendmail returned error code `code`" | Sendmail returns a error, which must be handled by use. | See the documention of your mailer programm.
smtp | `NULL` | "unable to instantiate Net_SMTP object" | Failure in class creation | Reinstall/update the Net_SMTP package.
smtp | `NULL` | "unable to connect to smtp server `host:port`" | Connect to SMTP server failed | Check `$param['port']` and `$param['host']` entries in your Mail::factory() call.
smtp | `NULL` | "unable to authenticate to smtp server" | Authentication failed | Check `$param['auth']`, `$param['username']` and `$param['password']` entries in your Mail::factory() call. Ensure to use the correct authentication method for the SMTP server.
smtp | `NULL` | "unable to identify smtp server" | Start request to SMTP server failed | Check the RFC-compliances of the SMTP server to connect.
smtp | `NULL` | "unable to set sender to `from`" | Sending the from address failed | Check the RFC-compliances of the from address and the server connnectivity.
smtp | `NULL` | "unable to add recipient `recipient`:`error code` " | Sending of recipient address failed | Check the RFC-compliances of the recipient address and the server connnectivity.
smtp | `NULL` | "unable to send data" | Body of the mail message could not send | Check the RFC-compliances of the message body and the server connnectivity.

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

If one wishes to specify recipients for `Bcc:`, the variable `recipients` must be an associative array:

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

    $recipients = array('To' => 'joe@example.com',
                        'Bcc' => 'jane@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()

Prev | Home | Next
Mail::factory() | Up | RFC822 - Introduction