mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 08:58:56 +00:00
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.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@179738 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Aidan Lister
parent
ab0fda3b0b
commit
ac069c014c
1 changed files with 346 additions and 167 deletions
|
|
@ -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>
|
||||
<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 < 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">
|
||||
<!-- $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>user@example.com</member>
|
||||
<member>user@example.com, anotheruser@example.com</member>
|
||||
<member>User <user@example.com></member>
|
||||
<member>User <user@example.com>, Another User <anotheruser@example.com></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
|
||||
mail("joecool@example.com", "My Subject", "Line 1\nLine 2\nLine 3");
|
||||
$text = str_replace("\n.", "\n..", $text);
|
||||
?>
|
||||
]]>
|
||||
</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>
|
||||
</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>
|
||||
<example>
|
||||
<title>Sending mail with extra headers.</title>
|
||||
<programlisting role="php">
|
||||
Using <function>mail</function> to send a simple email:
|
||||
</para>
|
||||
<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());
|
||||
// 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>
|
||||
</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@' . $_SERVER['SERVER_NAME'] . "\r\n" .
|
||||
'Reply-To: webmaster@' . $_SERVER['SERVER_NAME'] . "\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>
|
||||
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("nobody@example.com", "the subject", $message,
|
||||
"From: webmaster@{$_SERVER['SERVER_NAME']}", "-fwebmaster@{$_SERVER['SERVER_NAME']}");
|
||||
mail('nobody@example.com', '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 = "mary@example.com" . ", " ; // note the comma
|
||||
$to .= "kelly@example.com";
|
||||
// multiple recipients
|
||||
$to = 'aidan@example.com' . ', '; // note the comma
|
||||
$to .= 'wez@example.com';
|
||||
|
||||
/* 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";
|
||||
// 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";
|
||||
// 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 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 <someone@example.com>". 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 <someone@example.com>". 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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue