php-doc-en/functions/mail.xml

<?xml encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->
 <reference id="ref.mail">
  <title>Mail functions</title>
  <titleabbrev>Mail</titleabbrev>
  <partintro>
   <simpara>
    The <function>mail</function> function allows you to send mail
   </simpara>
  </partintro>

  <refentry id="function.mail">
   <refnamediv>
    <refname>mail</refname>
    <refpurpose>send mail</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>mail</function></funcdef>
      <paramdef>string <parameter>to</parameter></paramdef>
      <paramdef>string <parameter>subject</parameter></paramdef>
      <paramdef>string <parameter>message</parameter></paramdef>
      <paramdef>string
       <parameter><optional>additional_headers</optional></parameter>
      </paramdef>
      <paramdef>string
       <parameter><optional>additional_parameters</optional>
       </parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <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
	 <ulink url="http://www.zend.com/zend/spotlight/sendmimeemailpart1.php"
	 >http://www.zend.com/zend/spotlight/sendmimeemailpart1.php</ulink> or
	 RFC 1896 (Visit <ulink url="http://www.rfc-editor.org/"
	 >http://www.rfc-editor.org/</ulink>).
    </simpara>
    <para>
     <function>mail</function> returns &true; if the mail
     is sucessfully sent, &false; otherwise.
    </para>
    <para>
     <example>
      <title>Sending mail.</title>
      <programlisting>
mail("rasmus@lerdorf.on.ca", "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 newline.
    </simpara>
    <note>
     <para>
     On Win32 systems, you must use <literal>\r\n</literal> to
     seperate headers.  Please also note that the cc: and bcc: headers
     are case sensitve and should be written as <literal>Cc:</literal>
     and <literal>Bcc:</literal> on Win32 systems.
     </para>
    </note>
    <simpara>
     If the fifth parameter is supplied, PHP will add this data
     to the call to the mailer.  This is useful when setting the
     correct Return-Path header when using sendmail.
    </simpara>
    <para>
     <example>
      <title>Sending mail with extra headers.</title>
      <programlisting>
mail("nobody@aol.com", "the subject", $message,
     "From: webmaster@$SERVER_NAME\nReply-To: webmaster@$SERVER_NAME\nX-Mailer: PHP/" . phpversion());
      </programlisting>
     </example>
     With the fifth parameter you can set additional command line parameters to
     the actual mailer. In the example below we set the correct Return-Path
     header for sendmail. Normally sendmail will add the X-Authentication-Warning
     header when using the -f parameter, because the webserver user is probably
     not a member of the trusted users. To suppress this warning, you should add
     the web server user to the trusted users in your sendmail config file.
    </para>
    <note>
     <para>
      This fifth parameter was added in PHP 4.0.5.
     </para>
    </note>
    <para>
     <example>
      <title>Sending mail with extra headers and setting an additional command line parameter.</title>
      <programlisting>
mail("nobody@aol.com", "the subject", $message,
     "From: webmaster@$SERVER_NAME", "-fwebmaster@$SERVERNAME");
      </programlisting>
     </example>
     You can also use fairly simple string building techniques to
     build complex email messages.
     <example>
      <title>Sending complex email.</title>
      <programlisting>
/* recipients */
$recipient .= "Mary &lt;mary@u.college.edu>" . ", " ; //note the comma
$recipient .= "Kelly &lt;kelly@u.college.edu>" . ", ";
$recipient .= "ronabop@php.net";

/* subject */
$subject = "Birthday Reminders for August";

/* message */
$message .= "The following email includes a formatted ASCII table\n";
$message .= "Day \t\tMonth \t\tYear\n";
$message .= "3rd \t\tAug \t\t1970\n";
$message .= "17rd\t\tAug \t\t1973\n";

/* you can add a stock signature */
$message .= "--\r\n"; //Signature delimiter
$message .= "Birthday reminder copylefted by public domain";

/* additional header pieces for errors, From cc's, bcc's, etc */

$headers .= "From: Birthday Reminder &lt;birthday@php.net>\n";
$headers .= "X-Sender: &lt;birthday@php.net>\n";
$headers .= "X-Mailer: PHP\n"; // mailer
$headers .= "X-Priority: 1\n"; // Urgent message!
$headers .= "Return-Path: &lt;birthday@php.net>\n";  // Return path for errors

/* If you want to send html mail, uncomment the following line */
// $headers .= "Content-Type: text/html; charset=iso-8859-1\n"; // Mime type

$headers .= "cc: birthdayarchive@php.net\n"; // CC to
$headers .= "bcc: birthdaycheck@php.net, birthdaygifts@php.net"; // BCCs to

/* and now mail it */
mail($recipient, $subject, $message, $headers);
      </programlisting>
     </example>
    </para>
    <note>
     <para>
       Make sure you have no new-line (or other whitespace) after your to or
       subject parameters, as this may cause strange results.
     </para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.ezmlm-hash">
   <refnamediv>
    <refname>ezmlm_hash</refname>
    <refpurpose>Calculate the hash value needed by EZMLM</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>ezmlm_hash</function></funcdef>
      <paramdef>string <parameter>addr</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <function>ezmlm_hash</function> calculates the hash value needed
     when keeping EZMLM mailing lists in a MySQL database.
    </simpara>
    <para>
     <example>
      <title>Calculating the hash and subscribing a user</title>
      <programlisting>
$user = "kris@koehntopp.de";
$hash = ezmlm_hash ($user);
$query = sprintf ("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
$db->query($query); // using PHPLIB db interface
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

 </reference>

 <!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->