E-Mails mit conzept 16 (Teil 1)

conzept 16 bietet die Möglichkeit E-Mails direkt aus der Applikation zu versenden. Anwendungsfälle gibt es dafür viele: Sei es eine Feedback-Funktion für den Kunden, eine Benachrichtigung im Fehlerfall für den Administrator oder zum einfachen Versenden von Dateien.

Der Versand von E-Mails wird über die Mail-Funktionen realisiert. Diese verwenden zur Kommunikation das Simple Mail Transfer Protocol (SMTP). Voraussetzung ist ein erreichbarer und SMTP-fähiger Mailserver.

In einem früheren Artikel haben wir bereits eine Methode zum Empfangen von E-Mails mit conzept 16 vorgestellt.

Die Funktionen zum Versand im Überblick:

• MailOpen() – E-Mail erstellen
• MailData() – E-Mail verfassen
  • Nachrichtenkopf definieren
  • Nachrichteninhalt definieren
  • Anhänge hinzufügen
• MailClose() – E-Mail versenden

E-Mail erstellen

Zum Erstellen einer E-Mail wird der Befehl MailOpen() verwendet. Diese Funktion speichert die Verbindungsdaten zum Mailserver und reserviert einen Speicherbereich zum Ablegen der Nachricht.

Die Art der Kommunikation zum Mailserver wird im ersten Parameter definiert. Im zweiten Parameter wird der Name bzw. die IP-Adresse des Mailservers angegeben.

Die Funktion liefert den Deskriptor auf ein Mail-Objekt zurück.

// Unverschlüsselte Verbindung zum Mailserver aufbauen
tMail # MailOpen(_MailSMTP, sMyMailserver);

// Verschlüsselte Verbindung per SSL/TLS zum Mailserver aufbauen
tMail # MailOpen(_MailSMTPS, sMyMailserver);

Der Standardport für SMTP ist der Port 25. Sofern der Mailserver die Kommunikation auf einem anderen Port erwartet, kann dieser im dritten Parameter definiert werden. Weiterhin können ein Timeout und Anmeldedaten, bestehend aus Benutzername und Kennwort, für den Mailserver, beim Anlegen der E-Mail angegeben werden.

// Verbindung über Port 50001
tMail # MailOpen(_MailSMTP, sMyMailserver, 50001);

// Verbindung mit 30 Sekunden Timeout und Authentifizierung
tMail # MailOpen(_MailSMTP, sMyMailserver, 0, 30, sMyUser, sMyPwd);

An dieser Stelle wird noch keine Verbindung zum Mailserver aufgebaut. Eine ungültige Mailserveradresse oder falsche Anmeldedaten werden erst beim Versenden der E-Mail erkannt.

Nachrichtenkopf definieren

Der Nachrichtenkopf (engl. Header) einer E-Mail besteht aus mehreren Einträgen. Jeder Eintrag steht für eine Eigenschaft der E-Mail, z. B. Absender, Empfänger oder Erstellungsdatum. Über die Funktion MailData() können diese Einträge definiert werden. Die Funktion erwartet als ersten Parameter den Deskriptor eines Mail-Objektes. Im zweiten Parameter wird per Konstante angegeben, welcher Header-Eintrag erstellt werden soll. Eine Übersicht der Konstanten ist in der conzept 16-Dokumentation unter dem Index-Eintrag "MailData – Nachrichtenkopf" zu finden. Der Wert des Header-Eintrags wird im dritten Parameter definiert. Im vierten Parameter kann ein Zusatz zu dem Eintrag angegeben werden, beispielsweise den Anzeigename zu einer Adresse.

// Absender definieren
tMail->MailData(_SMTPFrom, '', 'Emil A. D. Resse');

// Empfänger hinzufügen
tMail->MailData(_SMTPTo, '', 'vectorsoft AG (Support)');

// Betreff definieren
tMail->MailData(_SMTPSubject, 'Frage zu conzept 16');

Jede E-Mail muss einen Absender und mindestens einen Empfänger besitzen!

Es können mehrere Empfänger, CCs und BCCs definiert werden. Dazu wird die jeweilige Anweisung mehrfach aufgerufen.

Im vierten Parameter können DSN (Delivery Status Notification)-Kommandos definiert werden.

Als Rückgabewert liefert die Funktion einen Fehlerwert.

Nachrichteninhalt definieren

Der Nachrichteninhalt, also der eigentliche Text in der E-Mail, wird ebenfalls über den Befehl MailData() definiert. Es kann für jede E-Mail ein Plain-Text und ein HTML-Text (_MimeTextHTML) definiert werden. Der HTML-Text ist dabei optional und sollte immer erst nach dem Plain-Text definiert werden, ansonsten kann es passieren, dass ein E-Mail-Client die E-Mail nicht korrekt darstellen kann.

Es sollte in jedem Fall ein Plain-Text mitgesendet werden, damit alle E-Mail-Clients, die nicht HTML-fähig sind, die E-Mail anzeigen können.

Es gibt prinzipiell drei Möglichkeiten den Nachrichteninhalt zu definieren:

• Aus einem Textpuffer (_MailBuffer),
• aus einer externen Datei (_MailFile) oder
• zeilenweise (_MailLine).

Kommt der Nachrichteninhalt aus einem Textpuffer muss dessen Deskriptor in einen Alpha-Wert konvertiert werden.

Beispiel für Textpuffer:

// Plain
tMail->MailData(_MailBuffer, CnvAI(tTextASCII, _FmtInternal));

// HTML
tMail->MailData(_MailBuffer | _MimeTextHTML, CnvAI(tTextHTML, _FmtInternal));

Beispiel für externe Dateien:

// Plain
tMail->MailData(_MailFile, _Sys->spPathMyDocuments + 'mail.txt');

// HTML
tMail->MailData(_MailFile | _MimeTextHTML, _Sys->spPathMyDocuments + 'mail.html');

Beispiel für zeilenweises Definieren:

// Plain
tMail->MailData(_MailLine, 'Sehr geehrte Damen und Herren,');
tMail->MailData(_MailLine, ''); // Leerzeile
...
tMail->MailData(_MailLine, 'Mit freundlichen Grüßen');
...

// HTML
tMail->MailData(_MailLine | _MimeTextHTML, '<html><body>');
tMail->MailData(_MailLine | _MimeTextHTML, '<p>Sehr geehrte Damen und Herren,</p>');
...
tMail->MailData(_MailLine | _MimeTextHTML, '<p>Mit freundlichen Grüßen</p>');
...
tMail->MailData(_MailLine | _MimeTextHTML, '</body></html>');

Anhänge hinzufügen

Wird bei dem Befehl MailData() ein zusätzlicher MIME-Typ (Multipurpose Internet Mail Extension) angegeben, kann eine externe Datei als Anhang der E-Mail hinzugefügt werden. Der MIME-Typ gibt den Typ der zu übertragenden Daten an.

Der Dateiname in der E-Mail wird aus der externen Datei übernommen.

// Bild hinzufügen
tMail->MailData(_MailFile | _MimeImageJPEG, _Sys->spPathMyPictures + 'image.jpg');

// ZIP-Datei hinzufügen
tMail->MailData(_MailFile | _MimeAppZIP, _Sys->spPathMyDocuments + 'info.zip');

E-Mail versenden

Das Versenden der E-Mail wird über den Befehl MailClose() ermöglicht. Dabei wird der Funktion das Argument _SMTPSendNow übergeben. Soll die erstellte E-Mail verworfen werden, muss _SMTPDiscard als Argument angegeben werden.

Die Funktion liefert einen Fehlerwert als Resultat zurück.

// E-Mail versenden
tMail->MailClose(_SMTPSendNow);

// E-Mail verwerfen
tMail->MailClose(_SMTPDiscard);

Ausblick

Es wird einen weiterführenden Artikel zu den Mail-Funktionen geben. In diesem werden die Themen Kodierung, Zeichensatz, verwenden von speziellen MIME-Typen und das Einbetten von Ressourcen – z. B. Bilder – in HTML-E-Mails erläutert.