php-doc-en/reference/mail/functions/mail.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.29 $ -->
<!-- splitted from ./en/functions/mail.xml, last change in rev 1.2 -->
  <refentry id="function.mail">
   <refnamediv>
    <refname>mail</refname>
    <refpurpose>Send mail</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <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>
    <simpara>
     <function>mail</function> automatically mails the message
     specified in <parameter>message</parameter> to the receiver
     specified in <parameter>to</parameter>. Multiple recipients can
     be specified by putting a comma between each address in
     <parameter>to</parameter>.  Email with attachments and special
     types of content can be sent using this function. This is
     accomplished via MIME-encoding - for more information, see this
     <ulink url="&url.email.mime.zend;">
     Zend article</ulink> or the <ulink url="&url.pear.package;Mail_Mime">
     PEAR Mime Classes</ulink>.
     </simpara>     
     <simpara>
     The following RFC's may also be useful:
     <ulink url="&url.rfc;1896">RFC 1896</ulink>,
     <ulink url="&url.rfc;2045">RFC 2045</ulink>,
     <ulink url="&url.rfc;2046">RFC 2046</ulink>,
     <ulink url="&url.rfc;2047">RFC 2047</ulink>,
     <ulink url="&url.rfc;2048">RFC 2048</ulink>, and 
     <ulink url="&url.rfc;2049">RFC 2049</ulink>.
    </simpara>
    <para>
     <function>mail</function> returns &true; if the mail was successfully
     accepted for delivery, &false; otherwise.
    </para>
    <warning>
     <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). 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.
      PHP &lt; 4.3 only supported the <literal>Cc:</literal>
      header element (and was case-sensitive). PHP &gt;= 4.3
      supports all the mentioned header elements and is no longer
      case-sensitive.
     </para>
    </warning>
    <para>
     <example>
      <title>Sending mail.</title>
      <programlisting role="php">
<![CDATA[
<?php
mail("joecool@example.com", "My Subject", "Line 1\nLine 2\nLine 3");
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     If a fourth string argument is passed, this string is inserted at
     the end of the header.  This is typically used to add extra
     headers. Multiple extra headers are separated with a carriage return
     and newline.
    </simpara>
    <note>
     <para>
     You must use <literal>\r\n</literal> to separate headers, although
     some Unix mail transfer agents replace <literal>\n</literal> by
     <literal>\r\n</literal> automatically (leads to doubling
     <literal>\r</literal> if <literal>\r\n</literal> is used).
     </para>
    </note>
    <para>
     <example>
      <title>Sending mail with extra headers.</title>
      <programlisting role="php">
<![CDATA[
<?php
mail("nobody@example.com", "the subject", $message,
     "From: webmaster@{$_SERVER['SERVER_NAME']}\r\n" .
     "Reply-To: webmaster@{$_SERVER['SERVER_NAME']}\r\n" .
     "X-Mailer: PHP/" . phpversion());
?>
]]>
      </programlisting>
     </example>
    </para>
    <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. You may need to add
     the user that your web server runs as to your sendmail configuration
     to prevent a 'X-Warning' header from being added to the message when
     you set the envelope sender using this method.
     <example>
      <title>Sending mail with extra headers and setting an additional command line parameter.</title>
      <programlisting role="php">
<![CDATA[
<?php
mail("nobody@example.com", "the subject", $message,
     "From: webmaster@{$_SERVER['SERVER_NAME']}", "-fwebmaster@{$_SERVER['SERVER_NAME']}");
?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      This fifth parameter was added in PHP 4.0.5. Since PHP 4.2.3 this
      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; if you're trying to use it.
     </para>
    </note>
    <para>
     You can also use simple string building techniques to build complex
     email messages.
     <example>
      <title>Sending complex email.</title>
      <programlisting role="php">
<![CDATA[
<?php
/* recipients */
$to  = "mary@example.com" . ", " ; // note the comma
$to .= "kelly@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, you can set the Content-type header. */
$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";

/* and now mail it */
mail($to, $subject, $message, $headers);
?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
       Make sure you do not have any newline characters in the
       <parameter>to</parameter> or <parameter>subject</parameter>,
       or the mail may not be sent properly.
     </para>
    </note>
    <note>
     <para>
      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 (Particularly under Windows).
     </para>
    </note>
    <para>
     See also <function>imap_mail</function>.
    </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
-->