aidan Sun Feb 13 21:45:49 2005 EDT
Modified files:
/phpdoc/en/reference/mail/functions mail.xml
Log:
Complete rewrite and update to the new format. I've intergrated all the user
notes (except 2, which were better left as notes). Please review thoroughly, as
this is one of the manual pages many people have problems with, and I'd like it
to be as clear as possible.
http://cvs.php.net/diff.php/phpdoc/en/reference/mail/functions/mail.xml?r1=1.29&r2=1.30&ty=u
Index: phpdoc/en/reference/mail/functions/mail.xml
diff -u phpdoc/en/reference/mail/functions/mail.xml:1.29
phpdoc/en/reference/mail/functions/mail.xml:1.30
--- phpdoc/en/reference/mail/functions/mail.xml:1.29 Sat Nov 27 04:35:05 2004
+++ phpdoc/en/reference/mail/functions/mail.xml Sun Feb 13 21:45:46 2005
@@ -1,209 +1,388 @@
<?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>
+<!-- $Revision: 1.30 $ -->
+<refentry id="function.mail">
+ <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
+ <ulink url="&url.rfc;2822">RFC 2822</ulink>. Some examples are:
+ <simplelist>
+ <member>[EMAIL PROTECTED]</member>
+ <member>[EMAIL PROTECTED], [EMAIL PROTECTED]</member>
+ <member>User <[EMAIL PROTECTED]></member>
+ <member>User <[EMAIL PROTECTED]>, Another User <[EMAIL
PROTECTED]></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 occurences 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).
+ <note>
+ <para>
+ If messages are not received, try using a LF (\n) only.
+ Some poor quality Unix mail transfer agents replace \n by \r\n
+ automatically (which leads to doubling \r if \r\n is used).
+ This should be a last resort, as it does not comply with
+ <ulink url="&url.rfc;2822">RFC 2822</ulink>.
+ </para>
+ </note>
+ </para>
+ </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 you set the envelope sender (-f) 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 < 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>
- <function>mail</function> returns &true; if the mail was successfully
- accepted for delivery, &false; otherwise.
+ Using <function>mail</function> to send a simple email:
</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 < 4.3 only supported the <literal>Cc:</literal>
- header element (and was case-sensitive). PHP >= 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">
+ <programlisting role="php">
<![CDATA[
<?php
-mail("[EMAIL PROTECTED]", "My Subject", "Line 1\nLine 2\nLine 3");
+// 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('[EMAIL PROTECTED]', 'My Subject', $message);
?>
]]>
- </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>
+ </programlisting>
+ </example>
+ <example>
+ <title>Sending mail with extra headers.</title>
<para>
- <example>
- <title>Sending mail with extra headers.</title>
- <programlisting role="php">
+ The addition of basic headers, telling the MUA
+ the From and Reply-To addresses:
+ </para>
+ <programlisting role="php">
<![CDATA[
<?php
-mail("[EMAIL PROTECTED]", "the subject", $message,
- "From: [EMAIL PROTECTED]'SERVER_NAME']}\r\n" .
- "Reply-To: [EMAIL PROTECTED]'SERVER_NAME']}\r\n" .
- "X-Mailer: PHP/" . phpversion());
+$to = '[EMAIL PROTECTED]';
+$subject = 'the subject';
+$message = 'hello';
+$headers = 'From: webmaster@' . $_SERVER['SERVER_NAME'] . "\r\n" .
+ 'Reply-To: webmaster@' . $_SERVER['SERVER_NAME'] . "\r\n" .
+ 'X-Mailer: PHP/' . phpversion();
+
+mail($to, $subject, $message, $headers);
?>
]]>
- </programlisting>
- </example>
- </para>
+ </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>
- 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">
+ to use when sending mail using the <literal>sendmail_path</literal>.
+ </para>
+ <programlisting role="php">
<![CDATA[
<?php
-mail("[EMAIL PROTECTED]", "the subject", $message,
- "From: [EMAIL PROTECTED]'SERVER_NAME']}", "[EMAIL
PROTECTED]'SERVER_NAME']}");
+mail('[EMAIL PROTECTED]', 'the subject', 'the message', null,
+ '-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>
+ </programlisting>
+ </example>
+ <example>
+ <title>Sending HTML email</title>
<para>
- You can also use simple string building techniques to build complex
- email messages.
- <example>
- <title>Sending complex email.</title>
- <programlisting role="php">
+ It is also possible to send HTML email with <function>mail</function>.
+ </para>
+ <programlisting role="php">
<![CDATA[
<?php
-/* recipients */
-$to = "[EMAIL PROTECTED]" . ", " ; // note the comma
-$to .= "[EMAIL PROTECTED]";
+// multiple recipients
+$to = '[EMAIL PROTECTED]' . ', '; // note the comma
+$to .= '[EMAIL PROTECTED]';
-/* subject */
-$subject = "Birthday Reminders for August";
+// subject
+$subject = 'Birthday Reminders for August';
-/* message */
+// message
$message = '
<html>
<head>
- <title>Birthday Reminders for August</title>
+ <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>
+ <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 <[EMAIL PROTECTED]>, Kelly <[EMAIL PROTECTED]>\r\n";
-$headers .= "From: Birthday Reminder <[EMAIL PROTECTED]>\r\n";
-$headers .= "Cc: [EMAIL PROTECTED]";
-$headers .= "Bcc: [EMAIL PROTECTED]";
+// 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 <[EMAIL PROTECTED]>, Kelly <[EMAIL PROTECTED]>' . "\r\n";
+$headers .= 'From: Birthday Reminder <[EMAIL PROTECTED]>' . "\r\n";
+$headers .= 'Cc: [EMAIL PROTECTED]' . "\r\n";
+$headers .= 'Bcc: [EMAIL PROTECTED]' . "\r\n";
-/* and now mail it */
+// 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 "Something <[EMAIL PROTECTED]>". The
- mail command may not parse this properly while talking with
- the MTA (Particularly under Windows).
- </para>
- </note>
+ </programlisting>
<para>
- See also <function>imap_mail</function>.
+ <note>
+ <para>
+ If intending to send HTML or otherwise Complex mails, it is recommended
+ to use the PEAR package <ulink
url="&url.pear.package;Mail">PEAR::Mail</ulink>.
+ </para>
+ </note>
</para>
- </refsect1>
- </refentry>
+ </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 "Something <[EMAIL PROTECTED]>". 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
+ <ulink url="&url.email.mime.zend;">
+ Zend article</ulink> or the <ulink url="&url.pear.package;Mail_Mime">
+ PEAR Mime Classes</ulink>.
+ </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
+ <ulink url="&url.pear.package;Mail">PEAR::Mail</ulink>, and
+ <ulink url="&url.pear.package;Mail_Mime">PEAR::Mail_Queue</ulink> packages.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ The following RFC's may 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>,
+ <ulink url="&url.rfc;2049">RFC 2049</ulink>, and
+ <ulink url="&url.rfc;2822">RFC 2822</ulink>.
+ </para>
+ </note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>imap_mail</function></member>
+ <member><ulink url="&url.pear.package;Mail">PEAR::Mail</ulink></member>
+ <member><ulink
url="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</ulink></member>
+ </simplelist>
+ </para>
+ </refsect1>
+</refentry>
+
<!-- Keep this comment at the end of the file
Local variables:
