Mail-System über PHP aufrufen

Ziel des Tutorials

Hinweis: Dieses Tutorial richtet sich an Entwickler und zeigt, wie das integrierte Mail-System des bluetronix CMS direkt über PHP aufgerufen werden kann.

Das bluetronix CMS stellt zentrale PHP-Funktionen für den E-Mail-Versand zur Verfügung.

Dadurch müssen SMTP-Verbindungen, Mail-Accounts und grundlegende Versandfunktionen nicht für jedes eigene PHP-Skript erneut programmiert werden.

Für den direkten E-Mail- und Newsletter-Versand steht folgende Funktion zur Verfügung:

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Für den Versand von Formular-E-Mails steht zusätzlich folgende Funktion zur Verfügung:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

BlueSMTPMail()

Mit BlueSMTPMail() können normale E-Mails und Newsletter über das zentrale Mail-System des bluetronix CMS versendet werden.

Der Funktionsaufruf lautet:

BlueSMTPMail(
   $MailType,
   $MailAccount,
   $SMTPType,
   $From,
   $To,
   $NewsletterTo,
   $Subject,
   $TextContent,
   $HTMLContent,
   $Attachments,
   $EmbedImages,
   $MailPlaceholderReplacement,
   $FormEntry
);

$MailType

Bestimmt, welche Art von E-Mail versendet werden soll.

Mögliche Werte:

Mail
Newsletter

Beispiel:

$MailType = "Mail";

oder:

$MailType = "Newsletter";

$MailAccount

$MailAccount bestimmt den E-Mail-Account, dessen SMTP-Einstellungen verwendet werden.

Über diesen Wert werden die entsprechenden SMTP-Konfigurationsdaten aus den CMS-Datenbanktabellen geladen.

Welche Konfiguration verwendet wird, hängt zusätzlich von $SMTPType ab.

$SMTPType

Bestimmt, ob ein interner oder externer E-Mail-Account verwendet wird.

Mögliche Werte:

Intern
Extern

Intern

Bei:

$SMTPType = "Intern";

wird ein E-Mail-Account verwendet, der direkt im bluetronix CMS eingerichtet wurde.

Die Accounts befinden sich unter:

Email → Accounts

Die unter $From verwendete Absenderadresse muss dort als Account vorhanden sein.

Extern

Bei:

$SMTPType = "Extern";

werden externe SMTP-Zugangsdaten verwendet.

Diese werden im CMS unter:

Email → Server - Extern

verwaltet.

Die unter $From verwendete Absenderadresse muss dort entsprechend eingerichtet sein.

$From

Enthält die E-Mail-Adresse des Absenders.

Beispiel:

$From = "info@example.com";

Die E-Mail-Adresse muss zur gewählten SMTP-Konfiguration passen.

$To

Enthält die E-Mail-Adresse des Empfängers einer normalen E-Mail.

Beispiel:

$To = "customer@example.com";

Bei einem normalen Mail-Versand wird diese Variable als Empfänger verwendet.

$NewsletterTo

$NewsletterTo wird beim Newsletter-Versand verwendet.

Die Variable enthält mehrere E-Mail-Adressen als Text. Jede E-Mail-Adresse wird durch einen Zeilenumbruch getrennt.

Beispiel:

$NewsletterTo = "customer1@example.com\ncustomer2@example.com\ncustomer3@example.com";

$Subject

Enthält den Betreff der E-Mail.

Beispiel:

$Subject = "Welcome to our website";

$TextContent

Enthält den reinen Textteil der E-Mail.

Dieser Teil kann beispielsweise von E-Mail-Programmen verwendet werden, die keine HTML-E-Mails darstellen.

Beispiel:

$TextContent = "Thank you for your request.";

$HTMLContent

Enthält den HTML-Teil der E-Mail.

Beispiel:

$HTMLContent = "<h1>Thank you</h1><p>Thank you for your request.</p>";

Damit können formatierte E-Mails mit Überschriften, Texten, Links, Bildern und weiteren HTML-Elementen versendet werden.

$Attachments

Mit $Attachments können Dateien an die E-Mail angehängt werden.

Die Dateien werden über ihren Pfad innerhalb der Webseite angegeben.

Beispiel:

$Attachments = "/bx_doc/Intro.pdf";

Bei mehreren Anhängen werden die einzelnen Dateipfade durch einen Zeilenumbruch getrennt.

Beispiel:

$Attachments = "/bx_doc/Intro.pdf\n/bx_doc/PriceList.pdf";

$EmbedImages

Mit $EmbedImages kann festgelegt werden, ob Bilder direkt in die E-Mail eingebettet werden sollen.

Beispiel:

$EmbedImages = "ja";

Bei aktivierter Option werden die innerhalb der HTML-E-Mail verwendeten Bilder direkt in die E-Mail integriert und nicht ausschließlich über externe URLs geladen.

Dadurch können die Bilder beim Empfänger direkt innerhalb der E-Mail verfügbar sein, ohne dass diese zunächst separat vom Webserver geladen werden müssen.

$MailPlaceholderReplacement

Mit $MailPlaceholderReplacement können Platzhalter innerhalb von:

$TextContent
$HTMLContent

durch individuelle Werte ersetzt werden.

Das Prinzip lautet:

Search
   ↓
Replace

Dadurch können beispielsweise personalisierte Inhalte innerhalb einer E-Mail erzeugt werden.

Typische Einsatzmöglichkeiten sind:

• Name des Empfängers
• Kundennummer
• Bestellnummer
• individuelle Links
• weitere dynamische Inhalte

$FormEntry

Mit $FormEntry kann festgelegt werden, ob der Versand zusätzlich im Formulararchiv gespeichert werden soll.

Bei:

$FormEntry = "JA";

wird zusätzlich ein Eintrag in der Datenbanktabelle:

00_form

gespeichert.

Damit kann der Versand gleichzeitig als Formular- bzw. Archiv-Eintrag dokumentiert werden.

Beispiel: Normale E-Mail versenden

Das folgende Beispiel versendet eine normale HTML- und Text-E-Mail über einen internen Mail-Account.

$MailType                  = "Mail";
$MailAccount               = "info@example.com";
$SMTPType                  = "Intern";
$From                      = "info@example.com";
$To                        = "customer@example.com";
$NewsletterTo              = "";
$Subject                   = "Your request";
$TextContent               = "Thank you for your request.";
$HTMLContent               = "<h1>Thank you</h1><p>Thank you for your request.</p>";
$Attachments               = "/bx_doc/Intro.pdf";
$EmbedImages               = "ja";
$MailPlaceholderReplacement = "";
$FormEntry                 = "NEIN";

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Der Ablauf lautet vereinfacht:

PHP
   ↓
BlueSMTPMail()
   ↓
internen Mail-Account laden
   ↓
SMTP-Verbindung verwenden
   ↓
E-Mail erzeugen
   ↓
E-Mail versenden
   ↓
MailCache-Eintrag erzeugen

Beispiel: Newsletter versenden

Für einen Newsletter wird $MailType auf:

Newsletter

gesetzt.

Die Empfänger werden anschließend über $NewsletterTo übergeben.

$MailType                  = "Newsletter";
$MailAccount               = "newsletter@example.com";
$SMTPType                  = "Intern";
$From                      = "newsletter@example.com";
$To                        = "";
$NewsletterTo              = "customer1@example.com\ncustomer2@example.com\ncustomer3@example.com";
$Subject                   = "Our latest news";
$TextContent               = "Discover our latest news and products.";
$HTMLContent               = "<h1>Our latest news</h1><p>Discover our latest news and products.</p>";
$Attachments               = "";
$EmbedImages               = "ja";
$MailPlaceholderReplacement = "";
$FormEntry                 = "NEIN";

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Die einzelnen Newsletter-Empfänger werden innerhalb von $NewsletterTo durch Zeilenumbrüche getrennt.

Externe SMTP-Verbindung verwenden

Soll ein externer Mailserver verwendet werden, wird:

$SMTPType = "Extern";

gesetzt.

Die SMTP-Zugangsdaten müssen zuvor unter:

Email → Server - Extern

eingerichtet worden sein.

Beispiel:

$SMTPType    = "Extern";
$From        = "mail@external-domain.com";
$MailAccount = "mail@external-domain.com";

BlueFormSend()

Zusätzlich zum direkten Mail-Versand steht die Funktion:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

zur Verfügung.

Diese Funktion ist speziell für den E-Mail-Versand in Verbindung mit CMS-Formularen vorgesehen.

Die Variablen sind bereits vollständig in englischer Schreibweise gehalten.

Parameter von BlueFormSend()

MailCache

Jeder Aufruf von BlueSMTPMail() erzeugt zusätzlich einen Eintrag in der Datenbanktabelle:

00_MailCache

Über diese Tabelle kann der Status des Mail-Versands kontrolliert werden.

Dort kann beispielsweise geprüft werden, ob eine E-Mail erfolgreich verarbeitet bzw. versendet wurde.

Die MailCache-Einträge werden für:

1 Woche

gespeichert.

Typischer Ablauf eines Mail-Versands

PHP-Skript
   ↓
BlueSMTPMail()
   ↓
MailType prüfen
   ↓
MailAccount auswählen
   ↓
SMTPType prüfen
   ↓
SMTP-Konfiguration laden
   ↓
Empfänger bestimmen
   ↓
Text- und HTML-Inhalt erstellen
   ↓
Platzhalter ersetzen
   ↓
Anhänge hinzufügen
   ↓
Bilder gegebenenfalls einbetten
   ↓
E-Mail versenden
   ↓
00_MailCache aktualisieren
   ↓
optional 00_form speichern

Übersicht der BlueSMTPMail-Parameter

Zusammenfassung

Das zentrale Mail-System des bluetronix CMS kann direkt aus eigenem PHP-Code aufgerufen werden.

Für normalen E-Mail- und Newsletter-Versand wird verwendet:

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Für CMS-Formulare steht zusätzlich zur Verfügung:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

Die SMTP-Konfiguration kann entweder über:

Intern
→ Email → Accounts

oder:

Extern
→ Email → Server - Extern

erfolgen.

Jeder Mail-Versand wird zusätzlich über:

00_MailCache

protokolliert. Die entsprechenden Cache-Einträge bleiben eine Woche erhalten.

Damit können Entwickler das bereits vorhandene Mail-System des bluetronix CMS direkt aus eigenen PHP-Skripten verwenden, ohne die komplette SMTP-Logik selbst implementieren zu müssen.