# mail

(PHP 4, PHP 5, PHP 7)

mail — 发送邮件

### 说明

mail ( string `$to` , string `$subject` , string `$message` [, string `$additional_headers` [, string `$additional_parameters` ]] ) : bool

发送一封电子邮件。

### 参数

`to`

  电子邮件收件人，或收件人列表。

  本字符串的格式必须符合 » RFC 2822。例如：

  - user@example.com
  - user@example.com, anotheruser@example.com
  - User <user@example.com>
  - User <user@example.com>, Another User <anotheruser@example.com>
`subject`

  电子邮件的主题。

  Caution

  本项不能包含任何换行符，否则邮件可能无法正确发送。

`message`

  所要发送的消息。

  行之间必须以一个 LF（\n）分隔。每行不能超过 70 个字符。

  Caution

  （Windows 下）当 PHP 直接连接到 SMTP 服务器时，如果在一行开头发现一个句号，则会被删掉。要避免此问题，将单个句号替换成两个句号。

      <?php
      $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers`（可选项）

  String to be inserted at the end of the email header.

  This is typically used to add extra headers (From, Cc, and Bcc). Multiple extra headers should be separated with a CRLF (\r\n).

  > Note:

  > When sending mail, the mail must contain a From header. This can be set with the `additional_headers` parameter, or a default can be set in php.ini.

  > Failing to do this will result in an error message similar to Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing.

  > Note:

  > If messages are not received, try using a LF (\n) only. Some poor quality Unix mail transfer agents replace LF by CRLF automatically (which leads to doubling CR if CRLF is used). This should be a last resort, as it does not comply with » RFC 2822.

`additional_parameters` (optional)

  The `additional_parameters` parameter can be used to pass an additional parameter to the program configured to use when sending mail using the sendmail_path configuration setting. For example, this can be used to set the envelope sender address when using sendmail with the -f sendmail option.

  The user that the webserver runs as should be added as a trusted user to the sendmail configuration to prevent a 'X-Warning' header from being added to the message when the envelope sender (-f) is set using this method. For sendmail users, this file is /etc/mail/trusted-users.

### 返回值

Returns `TRUE` if the mail was successfully accepted for delivery, `FALSE` otherwise.

It is important to note that just because the mail was accepted for delivery, it does NOT mean the mail will actually reach the intended destination.

### 更新日志

版本 | 说明
--- | ---
4.3.0 (Windows only) | All custom headers (like From, Cc, Bcc and Date) are supported, and are not case-sensitive. (As custom headers are not interpreted by the MTA in the first place, but are parsed by PHP, PHP < 4.3 only supported the Cc header element and was case-sensitive).
4.2.3 | The `additional_parameters` parameter is disabled in safe_mode and the mail() function will expose a warning message and return `FALSE` when used.
4.0.5 | The `additional_parameters` parameter was added.

### 范例

Example #1 Sending mail.

Using mail() to send a simple email:

    <?php
    // The message
    $message = "Line 1\nLine 2\nLine 3";

    // In case any of our lines are larger than 70 characters, we should use wordwrap()
    $message = wordwrap($message, 70);

    // Send
    mail('caffinated@example.com', 'My Subject', $message);
    ?>

Example #2 Sending mail with extra headers.

The addition of basic headers, telling the MUA the From and Reply-To addresses:

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = 'From: webmaster@example.com' . "\r\n" .
        'Reply-To: webmaster@example.com' . "\r\n" .
        'X-Mailer: PHP/' . phpversion();

    mail($to, $subject, $message, $headers);
    ?>

Example #3 Sending mail with an additional command line parameter.

The `additional_parameters` parameter can be used to pass an additional parameter to the program configured to use when sending mail using the sendmail_path.

    <?php
    mail('nobody@example.com', 'the subject', 'the message', null,
       '-fwebmaster@example.com');
    ?>

Example #4 Sending HTML email

It is also possible to send HTML email with mail().

    <?php
    // multiple recipients
    $to  = 'aidan@example.com' . ', '; // note the comma
    $to .= 'wez@example.com';

    // subject
    $subject = 'Birthday Reminders for August';

    // message
    $message = '
    <html>
    <head>
      <title>Birthday Reminders for August</title>
    </head>
    <body>
      <p>Here are the birthdays upcoming in August!</p>
      <table>
        <tr>
          <th>Person</th><th>Day</th><th>Month</th><th>Year</th>
        </tr>
        <tr>
          <td>Joe</td><td>3rd</td><td>August</td><td>1970</td>
        </tr>
        <tr>
          <td>Sally</td><td>17th</td><td>August</td><td>1973</td>
        </tr>
      </table>
    </body>
    </html>
    ';

    // To send HTML mail, the Content-type header must be set
    $headers  = 'MIME-Version: 1.0' . "\r\n";
    $headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";

    // Additional headers
    $headers .= 'To: Mary <mary@example.com>, Kelly <kelly@example.com>' . "\r\n";
    $headers .= 'From: Birthday Reminder <birthday@example.com>' . "\r\n";
    $headers .= 'Cc: birthdayarchive@example.com' . "\r\n";
    $headers .= 'Bcc: birthdaycheck@example.com' . "\r\n";

    // Mail it
    mail($to, $subject, $message, $headers);
    ?>

> Note:

> If intending to send HTML or otherwise Complex mails, it is recommended to use the PEAR package » PEAR::Mail.

### 注释

> Note:

> The Windows implementation of mail() differs in many ways from the Unix implementation. First, it doesn't use a local binary for composing messages but only operates on direct sockets which means a MTA is needed listening on a network socket (which can either on the localhost or a remote machine).

> Second, the custom headers like From:, Cc:, Bcc: and Date: are not interpreted by the MTA in the first place, but are parsed by PHP.

> As such, the `to` parameter should not be an address in the form of "Something <someone@example.com>". The mail command may not parse this properly while talking with the MTA.

> Note:

> It is worth noting that the mail() function is not suitable for larger volumes of email in a loop. This function opens and closes an SMTP socket for each email, which is not very efficient.

> For the sending of large amounts of email, see the » PEAR::Mail, and » PEAR::Mail_Queue packages.

> Note:

> The following RFCs may be useful: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049, and » RFC 2822.

### 参见

- imap_mail() - Send an email message
- » PEAR::Mail
- » PEAR::Mail_Mime