E-Mail-Versand

1. Einleitung

Zum Versand von E-Mails stellt das APF eine eigene API zur Verfügung. Das objektorientierte Interface erleichtert den Versand im Vergleich zur nativen Nutzung der PHP-Funktion mail() deutlich und sorgt so für klar strukturierten Code.

Die bereitgestellte API besteht aus zwei Komponenten:

  • Message: Repräsentiert eine E-Mail-Nachricht inklusive aller Eigenschaften wie z.B. Absender, Empfänger, Typ des Inhalts und Inhalt.
  • MailAddress: Repräsentiert einen E-Mail-Absender und -Empfänger.

Die beiden Klassen erlauben den Versand von E-Mails gemäß RFC2822 und unterstützen alle in RFC5321 beschriebenen Nachrichten-Optionen.

2. Versand

Der Versand einer einfachen Text-Nachricht lässt sich mit Hilfe der Klassen Message und MailAddress wie folgt erledigen:

PHP-Code
$sender = new MailAddress('Absender-Name', 'sender@example.com'); $subject = 'Betreff'; $content = 'Inhalt der Nachricht'; $message = new Message($sender, $subject, $content); $message->addRecipient(new MailAddress('Empfänger-Name', 'recipient@example.com')); $message->send();

Zur Erstellung einer Nachricht werden zunächst der Absender, die Betreffzeile und der Inhalt der Nachricht benötigt. Empfänger und andere Optionen lassen sich bequem nachträglich hinzufügen.

3. Weitere Anwendungsfälle

Die folgenden Kapitel zeigen Ihnen die erweiterten Konfigurations- und Versand-Möglichkeiten der APF E-Mail-API.

3.1. Definition von Empfängern

Die Klasse Message unterstützt drei verschiedene Typen von Empfänger: direkte Empfänger (TO), Kopie-Empfänger (CC) und Blind-Kopie-Empfänger (BCC). Mit dem folgenden Code-Block lassen sich alle drei Typen zu einer E-Mail hinzufügen:

PHP-Code
$message->addRecipient(new MailAddress('recipient name', 'recipient@example.com')); $message->addCopyRecipient(new MailAddress('Recipient name', 'recipient@example.com')); $message->addBlindCopyRecipient(new MailAddress('Recipient name', 'recipient@example.com'));

Mehrere Empfänger gleichzeitig lassen sich mit den folgenden Methoden-Aufrufen definieren:

PHP-Code
$recipients = [ new MailAddress('recipient one', 'recipient.one@example.com'), new MailAddress('recipient two', 'recipient.two@example.com') ]; $message->setRecipients($recipients); $message->setCopyRecipients($recipients); $message->setBlindCopyRecipients($recipients);

Zur Abfrage der aktuellen Liste von Empfängern lassen sich die folgenden Methoden einsetzen:

PHP-Code
$recipients = $message->getRecipients(); $copyRecipients = $message->getCopyRecipients(); $blindCopyRecipients = $message->getBlindCopyRecipients();

Möchten Sie die Liste der Empfänger löschen - z.B. um eine einmal aufgesetzte E-Mail an mehrere unabhängige Empfänger zu versenden - so lässt sich das wie folgt erledigen:

PHP-Code
$message = new Message(...); // Versand an Gruppe 1 $message->addRecipient(new MailAddress('...', 'recipient.one@e-mail.de')); $message->send(); $message->clearRecipients() ->clearCopyRecipients() ->clearBlindCopyRecipients(); // Versand an Gruppe 2 $message->send(); $message->addRecipient(new MailAddress('...', 'recipient.two@e-mail.de')); $message->clearRecipients() ->clearCopyRecipients() ->clearBlindCopyRecipients(); ...

Möchten Sie bei einem Fehler in der Zustellung vom zuständigen Mail-Server benachrichtigt werden, so können Sie wie in der folgenden Code-Box beschrieben einen Return Path definieren:

PHP-Code
$message->setReturnPath(new MailAddress('return postbox', 'return@example.com'));

3.2. Definition der Nachrichten-Priorität

Die Priorität einer Nachricht lässt sich wie folgt definieren:

PHP-Code
$message->setPriority(Message::PRIORITY_HIGH); $message->setPriority(Message::PRIORITY_NORMAL); $message->setPriority(Message::PRIORITY_LOW);

3.3. Definition des MIME-Types

Der MIME- bzw. Inhalts-Typ einer E-Mail wird standardmäßig mit plain/text; charset=UTF-8 vorgelegt. Der verwendete Zeichensatz ergibt sich aus dem Registry-Eintrag Charset aus dem Namespace APF\core. Details zur Basis-Konfiguration des Frameworks finden Sie unter Grundlagen.

Möchten Sie die Konfiguration des Inhalts-Typs ändern, so nutzen Sie bitte die Methode setContentType():

PHP-Code
$message->setContentType('text/html; charset=ISO-8859-1');

3.4. Erzeugen einer vorkonfigurierten Nachricht

Um den Umstieg auf die mit Release 3.3 eingeführte E-Mail-Versand-API zu erleichtern, bringt das Framework den MessageBuilder mit. Dieser dient dazu die für den mailSender (mit Version 3.3 entfernt) angelegte Konfiguration zu nutzen um eine vorkonfigurierte E-Mail zu erzeugen.

Die Konfiguration beihaltet die folgenden Attribute (Auszug aus der Konfiguration des Kontaktformular Moduls):

APF-Konfiguration
[ContactForm] Mail.SenderName = "..." Mail.SenderEMail = "..." Mail.ReturnPath = "..." Mail.ContentType = "text/plain; charset=utf-8"

Die Konfiguration beinhaltet Absender, Return-Path und Inhalts-Typ der zu versendenen E-Mail. Mit Hilfe des MessageBuilder lassen sich diese Werte bequem vorkonfigurieren.

Das nachfolgende Beispiel zeigt die Erstellung einer Nachricht (Message) an Hand der Konfiguration DEFAULT_mailsender.ini aus dem Namespace APF\tools\mail:

PHP-Code
$builder = $this->getServiceObject(MessageBuilder::class); $message = $builder->createMessage('ContactForm', $subject, $content);

Das erste Argument der Methode createMessage() referenziert die Konfigurations-Sektion, die zur Konfiguration der Nachricht eingesetzt werden soll. Möchten Sie mehrere unterschiedliche Nachrichten-Typen versenden, definieren Sie bitte eine Konfigurations-Sektion pro Nachrichten-Typ und referenzieren Sie die gewünschte Sektion beim Aufruf der Methode.

Details zur generellen Definition von Konfigurationsdateien erfahren Sie unter Konfiguration.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
Für diesen Artikel liegen aktuell keine Kommentare vor.