mail.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d43f29f6a628996d1b7c3be487dcff39450146bf Maintainer: nobody Status: ready -->
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mail</refname>
  <refpurpose>Sendet eine E-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 class="union"><type>array</type><type>string</type></type><parameter>additional_headers</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_params</parameter><initializer>""</initializer></methodparam>
  </methodsynopsis>
  <para>
   Sendet eine E-Mail.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       Ein oder mehrere Empfänger der E-Mail.
      </para>
      <para>
       Die Formatierung dieser Zeichenkette muss nach <link
       xlink:href="&url.rfc;2822">RFC 2822</link> erfolgen. Beispiele:
       <simplelist>
        <member>benutzer@example.com</member>
        <member>benutzer@example.com, benutzer2@example.com</member>
        <member>Name &lt;benutzer@example.com&gt;</member>
        <member>Name &lt;benutzer@example.com&gt;, Name2 &lt;benutzer2@example.com&gt;</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Der Betreff der E-Mail.
      </para>
      <caution>
       <para>
        Die Formatierung dieser Zeichenkette muss nach <link
        xlink:href="&url.rfc;2047">RFC 2047</link> erfolgen.
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       Die zu sendende Nachricht.
      </para>
      <para>
       Jede Zeile muss durch CRLF (\r\n) getrennt werden. Außerdem sollten die
       Zeilen nicht mehr als 70 Zeichen enthalten.
      </para>
      <caution>
       <para>
        (Nur unter Windows) Falls PHP direkt mit einem SMTP-Server
        kommuniziert und wenn ein Punkt (.) an einem Zeilenanfang steht, wird
        dieser Punkt entfernt. Um das zu verhindern, können Sie diese Punkte
        durch zwei Punkte ersetzen.
        <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>
       <type>string</type> oder <type>array</type>, das am Ende des
       E-Mail-Headers eingefügt werden soll.
      </para>
      <para>
       Dies kann benutzt werden, um zusätzliche Header wie From, Cc oder Bcc
       anzugeben. Falls mehrere solcher zusätzlichen Header angegeben werden
       sollen, müssen diese durch ein CRLF-Zeichen (\r\n) getrennt werden.
       Wenn von außen kommende Daten verwendet werden, um diesen Header
       zusammenzustellen, sollten diese Daten bereinigt werden, so dass keine
       ungewünschten Header eingeschleust werden können.
      </para>
      <para>
       Wird ein <type>array</type> übergeben, werden dessen Schlüssel als
       Header-Namen, und dessen Werte als entsprechende Header-Werte
       interpretiert.
      </para>
      <note>
       <para>
        Um eine E-Mail zu senden, <emphasis>muss</emphasis> die E-Mail einen
        <literal>From</literal>-Header enthalten. Dies kann entweder durch
        Setzen eines <parameter>additional_headers</parameter>-Parameters oder
        durch Setzen eines Standardwertes in der &php.ini; geschehen.
       </para>
       <para>
        Falls dies nicht geschieht, wird eine Fehlermeldung ähnlich wie
        <literal>Warning: mail(): "sendmail_from" not set in php.ini or custom
        "From:" header missing</literal> ausgegeben. Der
        <literal>From</literal>-Header setzt unter Windows auch den
        <literal>Return-Path</literal>-Header.
       </para>
      </note>
      <note>
       <para>
        Wenn E-Mails nicht ankommen, versuchen Sie bitte, nur das LF-Zeichen
        (\n) zu verwenden. Einige UNIX-MTAs (Mail Transfer Agents) (ganz
        besonders <link xlink:href="&url.qmail;">qmail</link>) ersetzen leider
        LF durch CRLF (\r\n) automatisch (wodurch das CR-Zeichen verdoppelt
        wird, wenn CRLF verwendet wird). Dies sollte aber nur in
        Ausnahmefällen geschehen, da es gegen <link
        xlink:href="&url.rfc;2822">RFC 2822</link> verstößt.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_params</parameter> (optional)</term>
     <listitem>
      <para>
       Der Parameter <parameter>additional_params</parameter>
       kann verwendet werden, um zusätzliche Parameter an das Programm zu
       senden, das für den E-Mail-Versand konfiguriert ist (wenn die
       <literal>sendmail_path</literal>-Einstellung verwendet wird).
       Zum Beispiel kann hiermit die Envelope Sender Address
       (Umschlag-Absenderadresse) gesetzt werden, wenn sendmail mit der
       <literal>-f</literal>-Option verwendet wird.
      </para>
      <para>
       Dieser Parameter wird intern durch <function>escapeshellcmd</function>
       maskiert, um die Kommando-Injection zu verhindern.
       <function>escapeshellcmd</function> verhindert die Kommando-Injection,
       erlaubt aber, zusätzliche Parameter hinzuzufügen. Aus
       Sicherheitsgründen wird empfohlen, dass dieser Parameter bereinigt
       wird, um zu verhindern, dass keine unerwünschten Parameter an das
       Shell-Kommando übergeben werden.
      </para>
      <para>
       Da <function>escapeshellcmd</function> automatisch angewendet wird,
       können einige Zeichen, die gemäß Internet-RFCs in E-Mail-Adressen
       erlaubt sind, nicht verwendet werden. <function>mail</function> kann
       solche Zeichen nicht erlauben, so dass für Programme, die diese Zeichen
       unterstützen müssen, alternative Methoden für den E-Mail-Versand (wie
       beispielsweise die Verwendung eines Frameworks oder einer Bibliothek)
       empfohlen werden.
      </para>
      <para>
       Der Benutzer, unter dem der Webserver läuft, sollte als
       vertrauenswürdiger Benutzer in der sendmail-Konfiguration eingetragen
       werden, um zu verhindern, dass ein 'X-Warning'-Header zu den E-Mails
       hingefügt wird, wenn mit dieser Methode (-f) der Absender gesetzt wird.
       Sendmail-Benutzer finden diese Datei hier:
       <filename>/etc/mail/trusted-users</filename>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt &true; zurück, wenn die E-Mail erfolgreich für den Versand akzeptiert
   wurde, sonst &false;.
  </para>
  <para>
   Dass eine E-Mail für den Versand akzeptiert wurde, bedeutet NICHT, dass sie
   auch wirklich den gewünschten Empfänger erreichen wird.
  </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>7.2.0</entry>
       <entry>
        Der Parameter <parameter>additional_headers</parameter> akzeptiert nun
        auch ein <type>array</type>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Verschicken einer E-Mail</title>
    <para>
     <function>mail</function> wird benutzt, um eine einfache E-Mail zu
     versenden:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Die Nachricht
$nachricht = "Zeile 1\r\nZeile 2\r\nZeile 3";

// Falls eine Zeile der Nachricht mehr als 70 Zeichen enthälten könnte,
// sollte wordwrap() benutzt werden
$nachricht = wordwrap($nachricht, 70, "\r\n");

// Verschicken
mail('benutzer@example.com', 'Mein Betreff', $nachricht);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Verschicken einer E-Mail mit zusätzlichen Headern</title>
    <para>
     Hier werden einfache Header gesetzt, um dem MUA (Mail User Agent, &zb;
     ein E-Mail-Programm) die From- und die Reply-To-Adressen mitzuteilen:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$empfaenger = 'niemand@example.com';
$betreff = 'Der Betreff';
$nachricht = 'Hallo';
$header = 'From: webmaster@example.com' . "\r\n" .
    'Reply-To: webmaster@example.com' . "\r\n" .
    'X-Mailer: PHP/' . phpversion();

mail($empfaenger, $betreff, $nachricht, $header);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Verschicken einer E-Mail mit zusätzliche Headern als <type>Array</type></title>
    <para>
     Dieses Beispiel verschickt die selbe E-Mail wie das Beispiel direkt
     darüber, aber diesemal werden die zusätzlichen Header als Array übergeben
     (verfügbar von PHP 7.2.0 an).
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$empfaenger = 'niemand@example.com';
$betreff = 'Der Betreff';
$nachricht = 'Hallo';
$header = array(
    'From' => 'webmaster@example.com',
    'Reply-To' => 'webmaster@example.com',
    'X-Mailer' => 'PHP/' . phpversion()
);

mail($empfaenger, $betreff, $nachricht, $header);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Verschicken einer E-Mail mit einem zusätzlichen Kommandozeilen-Parameter</title>
    <para>
     Der Parameter <parameter>additional_params</parameter> kann verwendet
     werden, um einen zusätzlichen Parameter an das über
     <literal>sendmail_path</literal> konfigurierte Programm zu senden.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
mail('niemand@example.com', 'Betreff', 'Nachricht', null,
   '-fwebmaster@example.com');
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Verschicken einer HTML-E-Mail.</title>
    <para>
     Auch HTML-E-Mails können mit <function>mail</function> versendet werden.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// mehrere Empfänger
$empfaenger  = 'max@example.com, moritz@example.com'; // beachte das Komma

// Betreff
$betreff = 'Geburtstags-Erinnerungen für August';

// Nachricht
$nachricht = '
<html>
<head>
  <title>Geburtstags-Erinnerungen für August</title>
</head>
<body>
  <p>Hier sind die Geburtstage im August:</p>
  <table>
    <tr>
      <th>Person</th><th>Tag</th><th>Monat</th><th>Jahr</th>
    </tr>
    <tr>
      <td>Max</td><td>3.</td><td>August</td><td>1970</td>
    </tr>
    <tr>
      <td>Moritz</td><td>17.</td><td>August</td><td>1973</td>
    </tr>
  </table>
</body>
</html>
';

// für HTML-E-Mails muss der 'Content-type'-Header gesetzt werden
$header[] = 'MIME-Version: 1.0';
$header[] = 'Content-type: text/html; charset=iso-8859-1';

// zusätzliche Header
$header[] = 'To: Simone <simone@example.com>, Andreas <andreas@example.com>';
$header[] = 'From: Geburtstags-Erinnerungen <geburtstag@example.com>';
$header[] = 'Cc: geburtstagsarchiv@example.com';
$header[] = 'Bcc: geburtstagscheck@example.com';

// verschicke die E-Mail
mail($empfaenger, $betreff, $nachricht, implode("\r\n", $header));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <note>
    <para>
     Wenn HTML- oder anderweitig komplexe E-Mails versendet werden sollen, ist
     es empfehlenswert, das PEAR-Paket <link
     xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link> zu
     verwenden.
    </para>
   </note>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Die SMTP-Implementierung (nur unter Windows) von <function>mail</function>
    unterscheidet sich auf mehrere Arten von der Unix-Implementierung. Zum
    einen verwendet sie kein lokales Programm, um die Mails zu erstellen,
    sondern arbeitet auf Sockets, &dh;, es wird ein <literal>MTA</literal>
    benötigt, der auf einem Netzwerk-Socket lauscht (entweder auf dem eigenen
    oder einem entfernten Rechner).
   </para>
   <para>
    Zum anderen, werden die benutzerdefinierten Header wie
    <literal>From:</literal>, <literal>Cc:</literal>, <literal>Bcc:</literal>
    und <literal>Date:</literal> <emphasis role="strong">nicht</emphasis>
    direkt durch den <literal>MTA</literal> interpretiert, sondern zunächst
    von PHP geparst.
   </para>
   <para>
    Daher sollte der Parameter <parameter>to</parameter> keine Adresse der
    Form &quot;Irgendwas &lt;irgendwer@example.com&gt;&quot; enthalten, da
    dies von PHP möglicherweise nicht korrekt an den MTA übergeben werden
    kann.
   </para>
  </note>
  <note>
   <para>
    Es ist zu beachten, dass die Funktion <function>mail</function> nicht dazu
    geeignet ist, große Mengen von E-Mails in einer Schleife zu senden, da die
    Funktion für jede E-Mail einen SMTP-Socket öffnet und schließt, was nicht
    sehr effizient ist.
   </para>
   <para>
    Um große Mengen von E-Mails zu senden, können die PEAR-Pakete <link
    xlink:href="&url.pear.package;Mail">PEAR::Mail</link> und <link
    xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link>
    verwendet werden.
   </para>
  </note>

  <note>
   <para>
    Die folgenden RFCs könnten nützlich für Sie sein:
    <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> und
    <link xlink:href="&url.rfc;2822">RFC 2822</link>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mb_send_mail</function></member>
    <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:"~/.phpdoc/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
-->