<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.37 $ -->
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mail</refname>
  <refpurpose>Send mail</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>mail</methodname>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam><type>string</type><parameter>message</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_parameters</parameter></methodparam>
  </methodsynopsis>
  <para>
   Sends an email.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       Receiver, or receivers of the mail.
      </para>
      <para>
       The formatting of this string must comply with
       <link xlink:href="&url.rfc;2822">RFC 2822</link>. Some examples are:
       <simplelist>
        <member>user@example.com</member>
        <member>user@example.com, anotheruser@example.com</member>
        <member>User &lt;user@example.com&gt;</member>
        <member>User &lt;user@example.com&gt;, Another User &lt;anotheruser@example.com&gt;</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Subject of the email to be sent.
      </para>
      <caution>
       <para>
        This must not contain any newline characters, or the mail may not be
        sent properly.
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       Message to be sent.
      </para>
      <para>
       Each line should be separated with a LF (\n). Lines should not be larger
       than 70 characters.
      </para>
      <caution>
       <para>
        (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.
        <programlisting role="php">
<![CDATA[
<?php
$text = str_replace("\n.", "\n..", $text);
?>
]]>
        </programlisting>
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_headers</parameter> (optional)</term>
     <listitem>
      <para>
       String to be inserted at the end of the email header.
      </para>
      <para>
       This is typically used to add extra headers (From, Cc, and Bcc).
       Multiple extra headers should be separated with a CRLF (\r\n).
      </para>
      <note>
       <para>
        When sending mail, the mail <emphasis>must</emphasis> contain
        a <literal>From</literal> header. This can be set with the 
        <parameter>additional_headers</parameter> parameter, or a default
        can be set in &php.ini;.
       </para>
       <para>
        Failing to do this will result in an error
        message similar to <literal>Warning: mail(): "sendmail_from" not
        set in php.ini or custom "From:" header missing</literal>.
        The <literal>From</literal> header sets also
        <literal>Return-Path</literal> under Windows.
       </para>
      </note>
      <note>
       <para>
        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
        <link xlink:href="&url.rfc;2822">RFC 2822</link>.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_parameters</parameter> (optional)</term>
     <listitem>
      <para>
       The <parameter>additional_parameters</parameter> parameter
       can be used to pass an additional parameter to the program configured
       to use when sending mail using the <literal>sendmail_path</literal>
       configuration setting. For example, this can be used to set the
       envelope sender address when using sendmail with the
       <literal>-f</literal> sendmail option.
      </para>
      <para>
       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 <filename>/etc/mail/trusted-users</filename>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &true; if the mail was successfully accepted for delivery, &false; otherwise.
  </para>
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.3.0 (Windows only)</entry>
       <entry>
        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 &lt; 4.3 only supported the Cc header element
        and was case-sensitive).
       </entry>
      </row>
      <row>
       <entry>4.2.3</entry>
       <entry>
        The <parameter>additional_parameters</parameter> parameter is disabled in
        <link linkend="ini.safe-mode">safe_mode</link> and the
        <function>mail</function> function will expose a warning message
        and return &false; when used.
       </entry>
      </row>
      <row>
       <entry>4.0.5</entry>
       <entry>
        The <parameter>additional_parameters</parameter> parameter was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Sending mail.</title>
    <para>
     Using <function>mail</function> to send a simple email:
    </para>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Sending mail with extra headers.</title>
    <para>
     The addition of basic headers, telling the MUA
     the From and Reply-To addresses:
    </para>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Sending mail with an additional command line parameter.</title>
    <para>
     The <parameter>additional_parameters</parameter> parameter
     can be used to pass an additional parameter to the program configured
     to use when sending mail using the <literal>sendmail_path</literal>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
mail('nobody@example.com', 'the subject', 'the message', null,
   '-fwebmaster@example.com');
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Sending HTML email</title>
    <para>
     It is also possible to send HTML email with <function>mail</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
    <para>
     <note>
      <para>
       If intending to send HTML or otherwise Complex mails, it is recommended
       to use the PEAR package <link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link>.
      </para>
     </note>
    </para>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">    
  &reftitle.notes;
  <note>
   <para>
    The Windows implementation of <function>mail</function> 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
    <literal>MTA</literal> is needed listening on a network socket (which
    can either on the localhost or a remote machine).
   </para>
   <para>
    Second, the custom headers like
    <literal>From:</literal>,
    <literal>Cc:</literal>,
    <literal>Bcc:</literal> and
    <literal>Date:</literal> are
    <emphasis role="strong">not</emphasis> interpreted by the
    <literal>MTA</literal> in the first place, but are parsed by PHP.
   </para>
   <para>
    As such, the <parameter>to</parameter> parameter should not be an address
    in the form of &quot;Something &lt;someone@example.com&gt;&quot;. The
    mail command may not parse this properly while talking with 
    the MTA.
   </para>
  </note>
  
  <note>
   <para>
    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
    <link xlink:href="&url.email.mime.zend;">
    Zend article</link> or the <link xlink:href="&url.pear.package;Mail_Mime">
    PEAR Mime Classes</link>.
   </para>
  </note>

  <note>
   <para>
    It is worth noting that the <function>mail</function> 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.
   </para>
   <para>
    For the sending of large amounts of email, see the
    <link xlink:href="&url.pear.package;Mail">PEAR::Mail</link>, and
    <link xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link> packages.
   </para>
  </note>

  <note>
   <para>
    The following RFCs may be useful:
    <link xlink:href="&url.rfc;1896">RFC 1896</link>,
    <link xlink:href="&url.rfc;2045">RFC 2045</link>,
    <link xlink:href="&url.rfc;2046">RFC 2046</link>,
    <link xlink:href="&url.rfc;2047">RFC 2047</link>,
    <link xlink:href="&url.rfc;2048">RFC 2048</link>,
    <link xlink:href="&url.rfc;2049">RFC 2049</link>, and
    <link xlink:href="&url.rfc;2822">RFC 2822</link>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>imap_mail</function></member>
    <member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
    <member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->