E-Mail-Versand in APEX

Der alte Weg: UTL_SMTP

Das Paket UTL_SMTP ist natürlich nicht verschwunden und funktioniert wie bisher. Mittels UTL_SMTP öffnet man eine Verbindung zu deinem SMTP-Server, gibt nacheinander über unterschiedliche Prozeduren Sender, Empfänger und Betreff an, und fügt zum Schluss die eigentliche Nachricht an, bevor man die E-Mail abschließt. Im Code schaut das in etwa so aus:

DECLARE
  c UTL_SMTP.CONNECTION;
 
  PROCEDURE send_header(name IN VARCHAR2, header IN VARCHAR2) AS
  BEGIN
    UTL_SMTP.WRITE_DATA(c, name || ': ' || header || UTL_TCP.CRLF);
  END;
 
BEGIN
  c := UTL_SMTP.OPEN_CONNECTION('smtp-server.acme.com');
  UTL_SMTP.HELO(c, 'foo.com');
  UTL_SMTP.MAIL(c, 'sender@foo.com');
  UTL_SMTP.RCPT(c, 'recipient@foo.com');
  UTL_SMTP.OPEN_DATA(c);
  UTL_SMTP.WRITE_DATA(c, 'From: "Sender" <anmo-noreply@muniqsoft-consulting.de>'|| UTL_TCP.CRLF);
  UTL_SMTP.WRITE_DATA(c, 'To: "Andreas Mößel" <anmo-test@muniqsoft-consulting.de >'|| UTL_TCP.CRLF);
  UTL_SMTP.WRITE_DATA(c, 'Subject: UTL_SMTP'|| UTL_TCP.CRLF);
  UTL_SMTP.WRITE_DATA(c, UTL_TCP.CRLF || 'Das ist eine Test Email über das UTL_SMTP Package');
  UTL_SMTP.CLOSE_DATA(c);
  UTL_SMTP.QUIT(c);
END;

E-Mail-Versand in APEX

Doch für APEX gibt es einen weiteren Weg, der als eigener deklarativer Prozess unter dem Typ „E-Mail versenden“ verpackt ist. Wenn eine E-Mail mit diesem Prozess versendet werden soll, dann landet diese erstmal in einer Queue, welche ein APEX eigener Job periodisch abarbeitet und die E-Mails tatsächlich los schickt.

Konfiguration des Prozesses

Wie man auf dem Bild sieht, gibt es eine überschaubare Anzahl an Eigenschaften für den Prozess. Ein paar davon sind Pflichtfelder, ohne die keine E-Mail abgeschickt werden kann, der Rest ist für komplexere E-Mails gedacht.

Pflichtfelder

• From: Der Sender der E-Mail. Das Feld muss ein gültiges E-Mail-Format enthalten.
• To:: Empfänger der E-Mail. Das Feld muss eine oder mehrere mit Komma separierte, gültige E-Mail-Adressen enthalten.
• Subject: Der Betreff einer E-Mail.
• Body Plain Text: Der Inhalt der E-Mail in einem einfachen Textformat, falls das E-Mali-Programm des Empfängers kein HTML oder Rich-Text unterstützt.

Zusatzfelder

• Cc: steht für ‚Carbon Copy‘. Die hier angegebenen E-Mail-Adressen erhalten die E-Mail ebenfalls, sind aber in der Regel nicht direkt durch die E-Mail angesprochen.
• Bcc: steht für ‚Blind Carbon Copy‘. Diese E-Mai-Adressen erhalten die E-Mail ebenfalls, werden aber nicht den anderen Empfängern angezeigt und können selber nur die Empfänger aus dem An-Feld sehen.
• Reply to: Antworten werden an diese E-Mail-Adresse geschickt.
• Email Template: Auswahlfeld für ein Template, das in den Shared Components angelegt werden kann, um ähnliche E-Mails an mehreren Stellen in der Applikation zentral zu verwalten.
• Body HTML: Eingabefeld für einen mit HTML-Code aufbereiteten Inhalt der E-Mail
• Attachment SQL: SQL mit denen Anhänge im BLOB-Format auf der Datenbank selektiert werden.

APEX_MAIL Paket

Hinter dem Prozess steht ein APEX eigenes Paket APEX_MAIL, das die Funktionen des Prozesses bündelt. Dieses Paket baut auf dem Paket UTL_SMTP auf, weshalb jenes fehlerfrei kompiliert sein muss.

APEX_MAIL ist von Oracle dokumentiert und kann hier nachgelesen werden.

Konfiguration eines E-Mail-Servers

Da dem E-Mail-Versand das Paket UTL_SMTP zugrunde liegt, ist es nötig einen E-Mail-Server zu konfigurieren. Dazu meldet man sich erstmal auf der Datenbank an und richtet das Network ACL ein.

SQLPLUS CONNECT AS SYS AS SYSDBA
DECLARE
  L_USERNAME VARCHAR2(30) := 'APEX_220200';
BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    HOST => 'localhost',
    LOWER_PORT => 25,
    ACE  =>  xs$ace_type(privilege_list => xs$name_list('connect'),
                         principal_name => l_username,
                         principal_type => xs_acl.ptype_db));
  COMMIT;
END;

In HOST und LOWER_PORT wird entsprechend die der Hostadresse des SMTP Servers und der dazu gehörige Port übergeben.

Anschließend meldet man sich in APEX im INTERNAL Workspace an und steuert ‚Manage Instance‘  -► ‚Instance Settings‘ an, um in APEX die nötigen Informationen für den E-Mail-Versand zu konfigurieren:

• Oracle APEX Instance URL: voreingetragen
• Oracle APEX Images URL: voreingetragen
• SMTP Host Address: Wie in der Network ACL die Hostadresse des SMTP-Servers eintragen
• SMTP Host Port: Wie in der Network ACL den Port des SMTP-Servers eintragen
• SMTP Authentication Username: Benutzer mit dem sich am Hostserver angemeldet wird
• SMTP Password: Passwort für den oben genannten Benutzer
• Confirm SMTP Password: siehe oben
• Use SSL/TLS: Auswahl ob und wann eine gesicherte Verbindung zum SMTP Hostserver aufgebaut wird
• Default Email From Address: Eine E-Mail-Adresse die angegeben wird, falls eine E-Mail ohne Absender abgeschickt wird
• Maximum Emails per Workspace: wie viele E-Mail pro Workspace pro Tag abgeschickt werden können

Zusammenfassung

Der APEX Prozess „E-Mail versenden“ ist eine einfachere und verständlichere Methode E-Mails zu verschicken als sich für diesen Zweck eine eigene Prozedur zu programmieren, zumal sie mit E-Mail Template, HTML-fähigkeit und der Möglichkeit zum Anhängen von Dateien genügend praktischen Wert aufweist.