Signatur
Beschreibung
imap_mail_compose() baut eine MIME-konforme E-Mail-Nachricht zusammen, die aus einem Umschlag (envelope) mit Kopfzeilen-Informationen wie Absender, Empfänger und Betreff sowie aus einem Body-Array mit einem oder mehreren Nachrichtenteilen besteht. Die Funktion gibt die fertige Rohdarstellung der E-Mail als String zurück, die anschließend z. B. per mail(), SMTP oder direkt in eine Mailbox geschrieben werden kann.
Das $envelope-Array kann folgende Schlüssel enthalten: replyto, return_path, date, from, to, cc, bcc, message_id und subject. Das $body-Array ist ein numerisch indiziertes Array aus Teilen, wobei jeder Teil selbst ein assoziatives Array mit Schlüsseln wie type, subtype, encoding, description, contents.data und disposition sein kann.
Die Funktion ist besonders nützlich, wenn mehrteilige MIME-Nachrichten mit Anhängen, HTML-Inhalt und alternativem Plaintext-Inhalt programmatisch erzeugt werden sollen, ohne manuell MIME-Grenzen und Kodierungen verwalten zu müssen. Sie gehört zur IMAP-Erweiterung von PHP und erfordert deren Aktivierung.
Hinweis: Für neue Projekte wird häufig die Verwendung einer dedizierten Bibliothek wie PHPMailer oder Symfony Mailer empfohlen, da diese mehr Kontrolle und bessere Fehlerverwaltung bieten. imap_mail_compose() ist jedoch eine praktische Low-Level-Alternative, wenn die IMAP-Erweiterung ohnehin genutzt wird.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $envelope Pflicht | array | Assoziatives Array mit Kopfzeilen-Informationen der E-Mail. Unterstützte Schlüssel: replyto, return_path, date, from, to, cc, bcc, message_id, subject. Die Werte müssen korrekt formatierte RFC-2822-Strings sein. |
|
| $body Pflicht | array | Numerisch indiziertes Array von Nachrichten-Teilen. Jeder Teil ist ein assoziatives Array mit möglichen Schlüsseln: type (MIME-Haupttyp als IMAP-Konstante, z. B. TYPETEXT), subtype (MIME-Untertyp, z. B. 'PLAIN' oder 'HTML'), encoding (Kodierung als IMAP-Konstante, z. B. ENC7BIT), charset, contents.data (der eigentliche Inhalt), disposition (Array mit filename für Anhänge), description und lines. Für mehrteilige Nachrichten kann ein nested.msg-Schlüssel verwendet werden. |
Rückgabewert
false zurückgegeben.Beispiele
Einfache Plaintext-E-Mail erzeugen
<?php
// Einfache Plaintext-Nachricht mit imap_mail_compose erzeugen
$envelope = [
'from' => 'absender@example.com',
'to' => 'empfaenger@example.com',
'subject' => 'Testnachricht von imap_mail_compose',
'date' => date('r'),
];
$body = [
[
'type' => TYPETEXT,
'subtype' => 'PLAIN',
'encoding' => ENC8BIT,
'charset' => 'UTF-8',
'contents.data' => 'Hallo! Dies ist eine einfache Testnachricht.',
]
];
$message = imap_mail_compose($envelope, $body);
if ($message !== false) {
echo "Erzeugte MIME-Nachricht:\n";
echo $message;
} else {
echo "Fehler beim Erzeugen der Nachricht.";
}Mehrteilige MIME-Nachricht mit HTML und Plaintext
<?php
// Mehrteilige E-Mail (multipart/alternative) mit HTML und Plaintext-Fallback
$envelope = [
'from' => 'newsletter@example.com',
'to' => 'kunde@example.com',
'subject' => 'Ihr monatlicher Newsletter',
'date' => date('r'),
];
$body = [
[
'type' => TYPEMULTIPART,
'subtype' => 'ALTERNATIVE',
],
[
'type' => TYPETEXT,
'subtype' => 'PLAIN',
'encoding' => ENC8BIT,
'charset' => 'UTF-8',
'contents.data' => 'Willkommen zu unserem Newsletter!\nBesuchen Sie uns unter https://example.com',
],
[
'type' => TYPETEXT,
'subtype' => 'HTML',
'encoding' => ENC8BIT,
'charset' => 'UTF-8',
'contents.data' => '<html><body><h1>Willkommen!</h1><p>Besuchen Sie uns unter <a href="https://example.com">example.com</a></p></body></html>',
],
];
$message = imap_mail_compose($envelope, $body);
if ($message !== false) {
// Nachricht z. B. per mail() versenden
// mail('kunde@example.com', '', $message); // Rohformat
echo "Mehrteilige MIME-Nachricht erfolgreich erzeugt (" . strlen($message) . " Bytes).";
} else {
echo "Fehler beim Erzeugen der Nachricht.";
}// Wichtig · Fallstricke
Erweiterungsabhängigkeit: imap_mail_compose() setzt die aktivierte PHP-IMAP-Erweiterung (ext-imap) voraus. Diese ist standardmäßig nicht immer aktiv und muss ggf. in der php.ini aktiviert oder nachinstalliert werden.
Deprecation: Ab PHP 8.1.0 wurde die gesamte IMAP-Erweiterung als veraltet markiert und als PECL-Paket ausgelagert. In PHP 8.4 ist sie nicht mehr Bestandteil des PHP-Kerns. Neue Projekte sollten daher auf Alternativen wie PHPMailer, Symfony Mailer oder die php-imap-Bibliothek setzen.
Sicherheit: Werden Benutzereingaben in das $envelope-Array übernommen, besteht die Gefahr von E-Mail-Header-Injection. Alle Werte müssen vor der Verwendung sorgfältig validiert und bereinigt werden — insbesondere die Felder to, cc, bcc und subject. Zeilenumbrüche (\r, \n) dürfen in diesen Feldern nicht vorkommen.
Zeichenkodierung: Bei der Verwendung von UTF-8-Inhalten empfiehlt es sich, sicherzustellen, dass Betreff und Absenderadressen ebenfalls korrekt kodiert werden (z. B. als =?UTF-8?B?...?=), da imap_mail_compose() dies nicht automatisch vornimmt.