# mail

(PHP 4, PHP 5)

mail — Send mail

### Description

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

Sends an email.

### Parameters

`to`

  Receiver, or receivers of the mail.

  The formatting of this string must comply with » RFC 2822. Some examples are:

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

  Subject of the email to be sent.

  Caution

  This must not contain any newline characters, or the mail may not be sent properly.

`message`

  Message to be sent.

  Each line should be separated with a LF (\n). Lines should not be larger than 70 characters.

  Caution

  (Windows only) When PHP is talking to a SMTP server directly, if a full stop is found on the start of a line, it is removed. To counter-act this, replace these occurrences with a double dot.

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

  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. The From header sets also Return-Path under Windows.

  > 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.

### Return Values

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.

### ChangeLog

Version | Description
--- | ---
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.

### Examples

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_Mime.

### Notes

> 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: Email with attachments and special types of content (e.g. HTML) can be sent using this function. This is accomplished via MIME-encoding - for more information, see this » Zend article or the » PEAR Mime Classes.

> 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.

### See Also

- imap_mail()
- » PEAR::Mail
- » PEAR::Mail_Mime