E-Mail-Verwaltung¶
Unter Administration > E-Mail (/v2/admin/email) wird das E-Mail-System von calServer v2 konfiguriert. Das Mailmanagement ist vollständig aus v1 übernommen und in sechs Bereiche gegliedert: Konfigurationen, Vorlagen, Aktionen (zeitgesteuerte Massenmails an Empfängergruppen), Mail schreiben (manueller Sofortversand), Warteschlange und Protokoll. Vorlagen können Berichte aus dem Berichtsmanagement als Anhang generieren.
Hauptschalter: Versand anhalten¶
Ganz oben auf der Seite steht, ob überhaupt Mails rausgehen — mit dem Knopf, der es ändert. Versand anhalten stoppt sofort jeden Versand, ohne dass eine Konfiguration angefasst oder eine Aktion abgeschaltet werden muss.
Das ist der Notaus für den Fall, dass etwas schiefläuft: eine Aktion, die an den falschen Verteiler geht, ein Mailserver, der Bounces produziert, ein Import, der tausend Erinnerungen ausgelöst hat. Bisher hätte man dafür den Container anfassen oder jede Konfiguration einzeln kaputtmachen müssen — beides Wege, die ein Betreiber ohne Servicevereinbarung nicht hat.
Was ein angehaltener Versand tut:
- Neue Mails werden nicht verschickt. Sie landen im Protokoll mit Status „nicht gesendet" und der Begründung „Der Mailversand ist in der Verwaltung abgeschaltet". Kein Eintrag behauptet einen Versand, den es nicht gab.
- Es wird nichts nachgeholt. Wer wieder einschaltet, bekommt keine Nachzustellung der in der Zwischenzeit unterdrückten Mails; die stehen im Protokoll und müssen bei Bedarf von Hand erneut gesendet werden.
- Bereits in der Warteschlange stehende Einträge bleiben stehen und werden nach dem Einschalten normal abgearbeitet.
Der Zustand liegt in der Datenbank und überlebt Neustart und cache:clear. Vorgabe ist
eingeschaltet — ein Update schaltet niemandem den Versand ab.
Ändern darf das email_management_edit, sehen email_management_view.
Bereiche¶
Konfigurationen¶
SMTP-Konfigurationen (mehrere möglich, genau eine Standard-Konfiguration):
| Einstellung | Beschreibung |
|---|---|
| Versandweg | SMTP, PHP mail() oder Sendmail |
| SMTP-Host / Port | Mailserver (25, 465, 587) |
| Verschlüsselung | TLS / STARTTLS / SSL / keine |
| Benutzername / Passwort | SMTP-Authentifizierung |
| Sendmail-Pfad | Pfad zur Sendmail-Binary (nur bei Versandweg Sendmail) |
| Standard | Als Standard-Konfiguration verwenden |
Die Standard-Konfiguration führt die Auswahllisten (Aktionen, Mail schreiben) an. Ist keine Konfiguration als Standard markiert, verwendet der Versand die älteste Konfiguration (kleinste ID, wie V1) — nicht die alphabetisch erste der Liste.
Versandweg im Container
Der Versand läuft über genau diese Konfiguration — Umgebungsvariablen
(MAIL_*) sind nicht nötig. Zwei Versandwege brauchen allerdings etwas,
das der API-Container nicht mitbringt: Sendmail erwartet die
sendmail-Binary im Container, und PHP mail() übergibt an den
Plattform-Transport des Deployments (MAIL_MAILER; steht der auf log,
wird nichts zugestellt). Empfohlen ist SMTP — der funktioniert ohne
weitere Voraussetzungen. Fehlversuche stehen mit der echten Fehlermeldung
im Protokoll.
Anders als V1 prüft V2 das TLS-Zertifikat des Mailservers. Ein
interner Relay mit selbstsigniertem Zertifikat, der unter V1 funktioniert
hat, scheitert dann mit einem Zertifikatsfehler im Protokoll —
MAILER_VERIFY_PEER=false in der Server-Umgebung stellt das alte
Verhalten her (gilt für die ganze Installation).
Vorlagen¶
Vorlagen definieren Absender, Betreff und HTML-Inhalt — mit Platzhaltern ([FULLNAME], [FIRSTNAME], [LASTNAME], [EMAIL], [FIRM], [DOMAIN], jeweils auch kleingeschrieben), die je Empfänger aufgelöst werden.
| Feld | Bedeutung |
|---|---|
| Absender-Name / -E-Mail | Überschreibt Absenderangaben der Konfiguration |
| Cc / Bcc (Standard) | Kommagetrennte Adressen, die bei jedem Versand dieser Vorlage mitlaufen |
| Anhang / Anhang-Typ | Master-Report als Datei oder als Download-Link im Text |
| Weitere Berichte | Zusätzliche Berichte, die neben dem Master-Report angehängt werden |
| Auch bei leerem Bericht senden | Versand auch dann, wenn der Bericht keine Datensätze enthält |
Über die Zeilenaktion Duplizieren wird eine Vorlage inklusive aller Felder und der zugeordneten Berichte kopiert (Name mit Suffix „(Kopie)").
Systemvorlagen und Aktionsvorlagen¶
Es gibt zwei Sorten Vorlagen, und der Unterschied ist nicht kosmetisch:
Systemvorlagen tragen einen festen Schlüssel (hide_name) und werden vom Programm nachgeschlagen, wenn ein bestimmtes Ereignis eintritt. Ihre Platzhalter liefert der jeweilige Auslöser — eine Aufgaben-Vorlage bekommt [TASK_URL], eine Ticket-Vorlage [TICKET_ID]. In einer Mailer-Aktion sind sie deshalb nicht sinnvoll einsetzbar.
| Schlüssel | Wann | Platzhalter |
|---|---|---|
task_create |
Aufgabe angelegt | [TITLE] [DESCRIPTION] [SUBJECT] [INFO] [CREATOR] [TASK_URL] |
task_update |
Aufgabe geändert | [TITLE] [DESCRIPTION] [SUBJECT] [CHANGES] [UPDATER] [TASK_URL] |
reminder_repair |
Wartungstermin verstrichen | [TITLE] [SUBJECT] [DESCRIPTION] [CREATOR] [TASK_URL] |
location_create |
Leiheintrag angelegt (Leihschein) | [TITLE] [DESCRIPTION] [SUBJECT] [INFO] [CREATOR] [LOCATION_URL] |
location_update |
Leiheintrag geändert | [TITLE] [DESCRIPTION] [SUBJECT] [CHANGES] [UPDATER] [LOCATION_URL] |
support_create_ticket |
Ticket angelegt | [TICKET_ID] [TITLE] [DESCRIPTION] [CREATOR] [ASSIGNEE] [PRIORITY] |
support_update_ticket |
Ticket geändert | [TICKET_ID] [TITLE] [DESCRIPTION] [UPDATER] [ASSIGNEE] [PRIORITY] |
support_comment_ticket |
Ticket kommentiert | [TICKET_ID] [TITLE] [COMMENT] [UPDATER] |
password_reset |
Passwort-Zurücksetzung angefordert | [FULLNAME] [FIRSTNAME] [LASTNAME] [EMAIL] [RESET_URL] [VALID_HOURS] [DOMAIN] |
Fehlt eine Systemvorlage, wird die zugehörige Mail still übersprungen — die Benachrichtigung sieht dann aus wie abgeschaltet. php artisan mailer:seed-templates legt fehlende Vorlagen nach (siehe unten).
Aktionsvorlagen haben keinen Schlüssel und sind frei in einer Aktion oder unter „Mail schreiben" wählbar. Ihre Platzhalter kommen aus der Empfängerauflösung: [FULLNAME], [FIRSTNAME], [LASTNAME], [EMAIL], [FIRM], [DOMAIN] — jeweils auch kleingeschrieben. Mitgeliefert werden „Kalibrierung fällig", „Kalibrierung überfällig" und „Geräteübersicht"; ein Berichts-Anhang muss noch zugeordnet werden.
Sprachvarianten¶
Systemvorlagen gibt es in zwei Fassungen: die Basiszeile ist deutsch, die englische liegt unter dem Schlüssel {hide_name}.en (Name mit Suffix „(EN)"). Welche verwendet wird, entscheidet die Standardsprache aus den Grundeinstellungen — fehlt die Variante, gilt die Basiszeile.
Beide Fassungen lassen sich in der Vorlagenliste ganz normal bearbeiten. Der Schlüssel selbst ist nicht editierbar: er ist der Kontrakt zum aufrufenden Programmteil, und ein Tippfehler darin würde die Benachrichtigung stillschweigend abschalten. Eine dritte Sprache braucht deshalb heute einen Eintrag im Katalog (MailerTemplateCatalog), nicht nur einen Klick in der Oberfläche.
Für Aktionsvorlagen greift das nicht: sie haben keinen Schlüssel und damit keine Variante. Dort wählt man die Sprache, indem man die Vorlage dieser Sprache in der Aktion einträgt. Das Feld Sprache an der Aktion ist eine Beschriftung, keine Umschaltung.
Berichts-Anhang (Berichtsmanagement): Eine Vorlage kann einen Master-Report als Anhang konfigurieren. Beim Versand wird der Bericht je Empfänger über die Report-Engine generiert (inkl. Briefpapier-Overlay) und als PDF angehängt. Der Fälligkeits-Filter (fällig, überfällig, kritisch 1–3) parametriert den Bericht mit den Zeiträumen aus den Regeln (due_date_period, critical_date_period_1..3).
Aktionen¶
Zeitgesteuerte Massenmails (v1 Mailer-Actions):
| Feld | Bedeutung |
|---|---|
| Vorlage / Konfiguration | Welche Vorlage über welchen SMTP-Weg |
| Empfängergruppe | Benutzer der Gruppe (mit Abo-Opt-out je Benutzer) und Kunden der Gruppe über das konfigurierte Kunden-E-Mail-Feld |
| Start / Ende | Zeitfenster, in dem die Aktion aktiv ist |
| Wochentage / Monate / Monatstage | Crontab-artige Feinsteuerung (Komma-Listen, leer = alle) |
| Auch ohne Anhang senden | Versand auch ohne generierten Bericht |
| Anhänge archivieren | Generierte Berichte dauerhaft aufbewahren |
Die Empfängergruppe steht als eigene Spalte in der Liste — mit ihrem Namen, nicht mit
einer id. Die Zelle ist zugleich der Knopf dazu: ein Klick öffnet einen kleinen Dialog, der
nur diese eine Auswahl enthält, und hängt die Aktion an eine andere Gruppe. Aktionen ohne
Gruppe stehen mit Gruppe wählen da; sie versenden nichts, weil es niemanden gibt, an den
sie versenden könnten. Geschrieben wird über dieselbe Route und dasselbe Feld wie im vollen
Bearbeiten-Formular; es gilt deshalb auch dasselbe Recht (email_management_edit) — ohne das
weist die API das Speichern ab.
Zeilen-Aktionen: Testversand an die Systemadresse (Schild-Symbol), Jetzt an die Empfängergruppe senden und Duplizieren. Ein Duplikatschutz verhindert beim automatischen Lauf mehr als einen erfolgreichen Versand pro Aktion, Empfänger und Tag. Ob eine Aktion ohne Anhang versendet, entscheidet die Kombination aus dem Aktions-Flag „Auch ohne Anhang senden" und dem Vorlagen-Flag „Auch bei leerem Bericht senden".
Mail schreiben¶
Der Bereich Mail schreiben versendet eine einzelne E-Mail sofort (ohne Warteschlange, ohne Zeitplan) — das v2-Pendant zu v1 „Mail schreiben":
| Feld | Bedeutung |
|---|---|
| Mail-Konfiguration | SMTP-Weg (vorbelegt mit der Standard-Konfiguration) |
| Vorlage (optional) | Lädt Betreff, Inhalt und CC der gewählten Vorlage in das Formular |
| Empfänger / Cc | Zieladresse und optionale, kommagetrennte CC-Adressen |
| Betreff / Inhalt | Betreff und HTML-Inhalt (WYSIWYG); Platzhalter [EMAIL], [DOMAIN] werden aufgelöst |
| Anhänge | Beliebige Dateien vom lokalen Rechner |
Jeder Versand wird — wie der automatische — im Protokoll (mailer_message) festgehalten.
Warteschlange¶
Die Warteschlange zeigt jede erzeugte E-Mail mit Status:
| Status | Beschreibung |
|---|---|
| Pending | Wartet auf den nächsten Verarbeitungslauf |
| Sending | Wird gerade versendet |
| Sent | Erfolgreich zugestellt |
| Failed | Zustellung fehlgeschlagen (mit Fehlermeldung) |
| Not_Send | Kein Anhang erzeugt und „ohne Anhang senden" deaktiviert |
Zeilen-Aktion Details öffnet Inhalt, CC/BCC, Anhänge und Fehlermeldung einer Zeile. Fehlgeschlagene (Failed) und nicht gesendete (Not_Send) Einträge lassen sich per Erneut senden einzeln erneut zustellen; die Kopfleiste bietet Fehlgeschlagene erneut senden, um alle betroffenen Einträge in einem Schritt wieder einzureihen.
Protokoll¶
Jeder Versand (Erfolg wie Fehler) wird im Sendeprotokoll (mailer_message) mit Empfänger, Betreff, Fehlermeldung und Datensatz-Bezug festgehalten. Die Zeilen-Aktion Inhalt anzeigen öffnet den vollständigen (sanitisierten) HTML-Inhalt der versendeten E-Mail samt CC/BCC, Status und Datensatz-Bezug (link_table / link_id).
Auch die Mails rund um die Anmeldung stehen hier — Passwort zurücksetzen, Registrierungsbestätigung, Willkommensmail, jeweils mit link_table = user. Das ist die Stelle, an der sich die häufigste Rückfrage beantworten lässt („ich habe keinen Passwort-Link bekommen").
Verarbeitung¶
Der Lauf php artisan mailer:process (Scheduler: alle 5 Minuten) führt fällige Aktionen aus und arbeitet die Warteschlange in Batches ab — das v2-Pendant zu den vier v1-Crons (Mailer, ExportReport, SendEmailQueue, DeleteReport). Temporäre Berichts-Anhänge werden nach dem Versand gelöscht, archivierte bleiben unter storage/app/mailer/archive/ erhalten.
Vorlagen nachziehen¶
Seit 5.65 legt der Start des Containers an, was fehlt. Ein Update bringt die Werksvorgabe also von selbst mit, auch auf eine Bestandsinstallation, und auch dann, wenn der Migrationslauf desselben Starts scheitert.
Bis 5.64: Bestandsinstallationen bekamen keine Vorlagen
Vorher schrieb die Werksvorgabe nur php artisan db:install — also der Einrichtungslauf einer frischen Installation. Wer per migrate aktualisierte, sah in der Vorlagenliste dauerhaft „0 Vorlagen", und jede Funktion, die eine Systemvorlage nachschlägt, fiel auf ihren fest eingebauten Text zurück.
Bleibt die Liste nach einem Update auf 5.65 leer, steht der Grund im Startprotokoll (docker logs calserver-api-v2, Zeile Ensuring factory mail templates). Fehlt dort auch die Tabelle, ist das Schema unvollständig — siehe Betrieb → Datenbankstand.
Von Hand nachziehen geht weiterhin:
Das Kommando legt nur an, was fehlt — vorhandene Vorlagen bleiben unberührt, auch die aus v1 übernommenen und die vom Betrieb angepassten. Systemvorlagen werden über ihren Schlüssel erkannt, Aktionsvorlagen über ihren Namen.
Mit --update-existing werden zusätzlich Betreff, Inhalt und Beschreibung vorhandener Vorlagen auf die Werksvorgabe zurückgesetzt — angepasste Texte gehen dabei verloren, deshalb fragt das Kommando nach. Name, Absender, Cc/Bcc und die Anhangs-Konfiguration bleiben auch dann stehen; das ist Einrichtung des Betriebs, keine Werksvorgabe.
Berechtigungen¶
Lesen (inkl. Protokoll-Detailansicht) erfordert email_management_view; Ändern, Duplizieren, manuelles Ausführen, „Mail schreiben" und erneutes Senden email_management_edit. Löschen email_management_delete.