Überblick

Das Problem

Der Mailversand einer Contao-Installation hängt an einer einzigen Zeile in einer Datei, die im Backend nicht vorkommt: MAILER_DSN in .env.local. Wer den Mailserver wechselt, ein Passwort erneuert oder von Port 587 auf 465 umstellt, arbeitet dafür per SSH oder FTP auf dem Server — und schreibt eine URL, in der Benutzername, Passwort, Host, Port und Verschlüsselung in exakter Reihenfolge und korrekt kodiert stehen müssen.

• Der Fehler zeigt sich erst später. Ein Tippfehler in der Zeile bricht keinen Bildschirm ab. Er fällt auf, wenn ein Formular des Kunden keine Bestätigung mehr verschickt oder die Passwort-vergessen-Mail nicht ankommt — oft Tage danach.
• Sonderzeichen im Passwort brechen die Zeile. Ein @, ein # oder ein / im Passwort muss kodiert werden, sonst zerfällt die URL an der falschen Stelle. Das ist keine seltene Ausnahme, sondern die Regel bei generierten Passwörtern.
• Die Änderung wirkt scheinbar nicht. Der Wert kommt aus einer Datei, die in den Container kompiliert wird. Ohne anschließendes Cache-Leeren bleibt der alte Mailserver aktiv — und der nächste Versuch beginnt mit der falschen Annahme, die neue Zeile sei falsch.
• Es gibt keinen Test vor dem Ernstfall. Ob die Zugangsdaten stimmen, zeigt sich an der ersten echten Mail, die ein Besucher auslöst. Bis dahin steht die Installation auf einer ungeprüften Konfiguration.
• Nur wer Serverzugang hat, kann es tun. Die Person, die den Mailanbieter gewechselt hat, ist selten dieselbe, die SSH-Zugang hat. Jede Anpassung wird zu einem Ticket mit Wartezeit.
• Während der Umstellung läuft die Seite weiter. Das Cache-Leeren geschieht im laufenden Betrieb, mit einem kurzen Zeitfenster, in dem Besucher auf eine halb aufgebaute Anwendung treffen können.

Am stärksten trifft das Agenturen und Betreuer mehrerer Installationen: derselbe Vorgang, mehrfach im Jahr, auf jedem Kundensystem einzeln, jedes Mal ohne Rückmeldung darüber, ob er geglückt ist.

Die Lösung

Das Grundprinzip in einem Satz: Die Mailer-Zugangsdaten werden im Contao-Backend eingegeben, vor dem Speichern mit einer echten Test-Mail geprüft und erst dann geschrieben — eine Konfiguration, die nicht funktioniert, wird gar nicht erst gespeichert.

Der SMTP Konfigurator ergänzt Contao um einen Backend-Bildschirm unter System → SMTP-Konfiguration. Host, Port, Verschlüsselung und Zugangsdaten werden dort als einzelne Felder erfasst; das Paket baut daraus die korrekt kodierte Verbindungszeile, verschickt damit eine Test-Mail an eine angegebene Adresse und schreibt den Wert nur dann nach .env.local. Direkt im Anschluss leert und wärmt es den Cache auf, hinter einer Wartungsseite, die danach wieder verschwindet.

Aufgabe	Manuell auf dem Server	Mit diesem Paket
Zugangsdaten ändern	SSH- oder FTP-Zugang, Datei bearbeiten	Backend-Formular, Administratorrechte genügen
Kodierung des Passworts	von Hand, fehleranfällig	übernimmt das Paket beim Zusammensetzen
Prüfung der Zugangsdaten	keine — erst die nächste echte Mail zeigt es	echte Test-Mail, bevor gespeichert wird
Fehlerhafte Eingabe	landet in der Datei und bricht den Versand	wird abgewiesen, der bisherige Stand bleibt
Cache nach der Änderung	separater Schritt, wird vergessen	läuft automatisch mit
Seite während der Umstellung	läuft ungeschützt weiter	kurze Wartungsseite, danach automatisch entfernt
Mailer wieder abschalten	Zeile manuell entfernen	ein Konsolenbefehl

• Gegen den unbemerkten Fehler: die Test-Mail ist Bedingung für das Speichern, nicht ein optionaler Knopf daneben.
• Gegen die Kodierungsfehler: getrennte Felder für Host, Port, Verschlüsselung, Benutzername und Passwort statt einer zusammengesetzten Zeile.
• Gegen den vergessenen Cache: Cache-Leeren und Aufwärmen als Teil des Speichervorgangs.
• Gegen das Zeitfenster im laufenden Betrieb: eine Wartungsseite, die automatisch angelegt und in jedem Fall wieder entfernt wird.
• Gegen das Ticket mit Wartezeit: Administratoren im Backend erledigen die Umstellung ohne Serverzugang.

Wann das Paket passt

Situation	Einschätzung
Contao 5.3 oder neuer, Versand über einen eigenen oder angemieteten SMTP-Server	Passt genau. Der Regelfall, für den das Paket gebaut ist.
Agentur mit mehreren betreuten Installationen	Passt. Jede Installation wird im eigenen Backend umgestellt, ohne Serverzugang pro Kunde.
Mailanbieter mit SMTP-Zugang (STARTTLS auf 587 oder SSL/TLS auf 465)	Passt. Beide Varianten sind im Formular auswählbar.
Versand über die HTTP-API eines Transaktions-Mail-Dienstes	Nicht dieses Paket. Der Bildschirm erzeugt ausschließlich SMTP- und SMTPS-Verbindungen. Ein API-Transport muss weiterhin von Hand in der Anwendungskonfiguration hinterlegt werden.
Redakteure ohne Administratorrechte sollen den Mailer ändern dürfen	Nicht dieses Paket. Der Bildschirm steht ausschließlich Backend-Administratoren offen; eine feinere Berechtigung gibt es nicht.
Die Absenderadresse soll dauerhaft im Backend hinterlegt werden	Eingeschränkt. Absender und Test-Empfänger dienen nur dem Versand der Test-Mail und werden nicht gespeichert.
Auf dem Server ist kein PHP-CLI-Aufruf möglich	Eingeschränkt. Speichern funktioniert, der automatische Cache-Schritt nicht — er muss dann von Hand nachgeholt werden.

Teil 1 — Einrichtung

Der Weg von der leeren Installation bis zur ersten erfolgreich versendeten Mail besteht aus diesen Stationen:

1. Voraussetzungen prüfen
2. Vorbereitungen treffen
3. Paket über den Contao Manager installieren — oder über Composer
4. Installation überprüfen
5. Lizenz aktivieren
6. Optionale Konfiguration setzen
7. Mailer einrichten und Test-Mail versenden

Voraussetzungen

Anforderung	Version bzw. Bedingung
PHP	^8.2
Contao	contao/core-bundle: ^5.3
Contao Manager Plugin	contao/manager-plugin: ^2.0
Symfony-Komponenten	^6.4 || ^7.0 (Dotenv, Event-Dispatcher, HTTP-Client, HTTP-Foundation, HTTP-Kernel, Mailer, Process)
Doctrine DBAL	^3.6 || ^4.0
PHP-Erweiterung ext-json	erforderlich
PHP-Erweiterung ext-sodium	erforderlich
PHP-Erweiterung ext-intl	erforderlich, wenn die Domain dieser Installation Nicht-ASCII-Zeichen enthält (IDN)
PHP-CLI-Binärdatei	für den Webserver-Benutzer ausführbar — nur für das automatische Cache-Leeren
Ausgehende HTTPS-Verbindung	vom Server aus, für die Lizenzaktivierung
Backend-Konto	Administrator
Datenbank	keine zusätzlichen Tabellen oder Spalten

Vor der Installation

1. Datensicherung anlegen. Dateien und Datenbank, wie vor jeder Paketinstallation.
2. Den bestehenden Mailversand festhalten. Falls in .env.local bereits ein MAILER_DSN-Eintrag steht, diesen Wert notieren. Das Paket überschreibt genau diese Zeile beim ersten Speichern.
3. Die Zugangsdaten des Mailanbieters bereitlegen: Hostname, Port, Verschlüsselungsverfahren, Benutzername, Passwort und eine Absenderadresse, die der Anbieter für dieses Konto akzeptiert.
4. Eine Test-Empfängeradresse wählen, deren Posteingang Sie während der Einrichtung tatsächlich einsehen können.
5. Prüfen, ob der Server ausgehend auf dem Mail-Port senden darf. Manche Hosting-Umgebungen sperren ausgehende Verbindungen auf Port 587 oder 465.
6. Die Lizenz bereithalten — der Schlüssel wird für die Installation unter v-t.one angefordert.

Muss beschreibbar sein	Wofür	Datensicherung
.env.local im Projektverzeichnis	nimmt die Mailer-Verbindung auf	ja — enthält das Mailer-Passwort
ein privates Verzeichnis unterhalb von var/	interner Zustand des Pakets, außerhalb des öffentlichen Web-Roots und nicht über HTTP erreichbar	ja
var/ (für var/maintenance.html)	Wartungsseite während des Cache-Leerens	nein

Installation über den Contao Manager

1. Contao Manager öffnen und anmelden.
2. Bereich Entdecken öffnen. Neue Pakete werden immer dort gesucht und hinzugefügt; der Bereich Pakete daneben zeigt unter Installierte Pakete nur, was bereits vorhanden ist. Entdecken ist zugleich die Startansicht des Managers.
3. Über Pakete suchen nach vtinnovations/smtp-bundle suchen und beim Treffer Paket hinzufügen wählen.
4. Die Änderungen anwenden. Der Contao Manager installiert das Paket und aktualisiert den Autoloader.
5. Bereich Systemwartung → Datenbank-Migrationen und -Backups → Datenbank prüfen. Dieses Paket bringt keine eigenen Tabellen mit; der Schritt ist reine Routine und meldet im Regelfall keine Datenbank-Änderungen für dieses Paket.
6. Unter Systemwartung den Anwendungs-Cache leeren (in der Navigation auch als Cache erneuern geführt).

Installation über Composer

Die Alternative für Installationen, die per Kommandozeile gepflegt werden:

composer require vtinnovations/smtp-bundle

Anschließend den Cache leeren, damit der Container die neuen Services übernimmt:

bin/console cache:clear

In einer Managed Edition führt Contao den eigenen Einrichtungsschritt nach dem Composer-Lauf selbst aus. Wo das nicht der Fall ist, lässt er sich nachholen:

vendor/bin/contao-setup

Für ein Update auf eine neuere Fassung:

composer update vtinnovations/smtp-bundle
bin/console cache:clear

Installation überprüfen

Drei Nachweise, dass die Registrierung geglückt ist:

1. Auf der Kommandozeile:

   bin/console list vtinnovations

   In der Ausgabe muss vtinnovations:smtp:disable stehen. Erscheint der Befehl nicht, ist das Bundle nicht geladen — dann den Cache leeren und die Installation wiederholen.
2. Im Backend erscheint in der Navigationsgruppe System der neue Eintrag SMTP-Konfiguration.
3. Unter Einstellungen erscheint ganz oben der Abschnitt V-T.ONE Licence management mit dem Block SMTP Konfigurator.

Solange keine Lizenz aktiviert ist, zeigt der Bildschirm SMTP-Konfiguration statt des Formulars einen Hinweis und verweist auf die Einstellungen. Das ist der erwartete Zustand unmittelbar nach der Installation.

Lizenz aktivieren

Für dieses Paket ist eine aktivierte Lizenz erforderlich. Dieses Produkt wird unter dem Modell Lifetime Free ausgeliefert: ein gültiger Schlüssel aktiviert das Paket dauerhaft, ohne Ablaufdatum. Es gibt für dieses Produkt keine kostenpflichtige Stufe, auf die aufgerüstet werden könnte, und keine Testphase.

So aktivieren Sie die Lizenz

1. Den Lizenzschlüssel für diese Installation unter v-t.one anfordern. Er wird für die Domain oder die Domains ausgestellt, unter denen die Installation erreichbar ist.
2. Im Contao-Backend als Administrator anmelden und Einstellungen öffnen.
3. Ganz oben den Abschnitt V-T.ONE Licence management aufsuchen, darin den Block SMTP Konfigurator. Vor der Aktivierung steht dort „Nicht lizenziert. Keine geschützte Funktion läuft." und darunter „Keine Lizenz. Schlüssel unter v-t.one anfordern und unten eintragen."
4. Den Schlüssel in das Feld Lizenzschlüssel eintragen. Das Feld zeigt als Platzhalter die Form XXXXX-XXXXX-XXXXX-XXXXX.
5. Lizenz prüfen und aktivieren drücken. Der Server nimmt dafür eine ausgehende HTTPS-Verbindung auf — nicht der Browser.
6. Nach der Rückkehr auf die Einstellungen erscheint die Bestätigung „Lizenz aktiviert.", und der Abschnitt zeigt „Lizenz aktiv. Alle Funktionen freigeschaltet." mit einer Detailzeile aus Schlüssel:, Paket:, Gültig ab:, Gültig bis: (hier unbegrenzt) und Zuletzt geprüft:.
7. System → SMTP-Konfiguration öffnen. Statt des Hinweises erscheint jetzt das Formular.

Der hinterlegte Schlüssel wird im Abschnitt nie vollständig angezeigt.

Konfiguration in config.yaml

Das Paket läuft ohne Konfiguration. Drei Einstellungen stehen für Sonderfälle bereit, alle unter dem Schlüssel vtinnovations_smtp in config/config.yaml:

# config/config.yaml
vtinnovations_smtp:
    php_binary: '/usr/bin/php8.3'
    process_timeout: 120
    domains:
        - 'example.com'
        - 'www.example.com'

• php_binary wird nur benötigt, wenn das automatische Cache-Leeren meldet, die PHP-CLI-Binärdatei sei nicht auffindbar. Gemeint ist die Kommandozeilen-Binärdatei, nicht die PHP-FPM- oder Webserver-Variante.
• process_timeout begrenzt, wie lange ein Cache-Vorgang laufen darf.
• domains wird nur gebraucht, wenn die Startseiten kein DNS-Feld tragen — siehe Domain-Bindung.

Nach jeder Änderung an dieser Datei den Cache leeren:

bin/console cache:clear

Erste Nutzung

1. Als Administrator anmelden und System → SMTP-Konfiguration öffnen. Die Überschrift lautet SMTP-Konfiguration und trägt rechts eine Zustandsanzeige: ✗ Nicht konfiguriert vor dem ersten Speichern, danach ✓ Aktiv, gefolgt von der Lizenzkennzeichnung in Klammern.
2. Im Abschnitt Server SMTP-Host eintragen (Pflichtfeld, Beispiel mail.example.com), Port und Verschlüsselung wählen, bei Bedarf Benutzername und Passwort.
3. Im Abschnitt E-Mail Absender-E-Mail und Test-Empfänger eintragen — beides Pflichtfelder.
4. Testen & Speichern drücken und das Browser-Fenster geöffnet lassen, bis die Antwort kommt.
5. Bei Erfolg erscheint „Test-Mail erfolgreich gesendet (…s). Konfiguration gespeichert, Cache geleert." und im Posteingang des Test-Empfängers eine Mail mit dem Betreff SMTP Test — vtinnovations/smtp-bundle.
6. Zur Gegenprobe eine Contao-eigene Mail auslösen, etwa über ein Formular mit E-Mail-Benachrichtigung.

Teil 2 — Funktionen im Detail

Alle Funktionen dieses Abschnitts setzen eine aktivierte Lizenz voraus. Ohne sie zeigt der Bildschirm SMTP-Konfiguration statt des Formulars einen Hinweis, und der Konsolenbefehl verweigert die Ausführung.

Mailer konfigurieren

Der Bildschirm liegt unter Contao → System → SMTP-Konfiguration und steht ausschließlich Backend-Administratoren offen. Jeder andere Benutzer erhält „Zugriff verweigert. Nur Administratoren." Das Formular ist in die Abschnitte Server und E-Mail geteilt.

So richten Sie die Verbindung ein

1. System → SMTP-Konfiguration öffnen.
2. SMTP-Host eintragen — ein Hostname oder eine IP-Adresse, ohne Protokoll, ohne Port und ohne Pfad. Eine IPv6-Adresse gehört in eckige Klammern.
3. Port setzen. Vorbelegt ist 587; erlaubt ist der Bereich 1 bis 65535.
4. Verschlüsselung wählen. Vorbelegt ist STARTTLS (Port 587).
5. Benutzername und Passwort eintragen, sofern der Anbieter eine Anmeldung verlangt. Bleibt der Benutzername leer, wird die Verbindung ohne Anmeldedaten aufgebaut.
6. Im Abschnitt E-Mail die Absender-E-Mail eintragen. Sie muss eine gültige Adresse sein, die der Mailanbieter für dieses Konto als Absender akzeptiert.
7. Einen Test-Empfänger eintragen, dessen Posteingang Sie einsehen können.
8. Testen & Speichern drücken und warten, bis die Seite antwortet.

Feld	Vorgabe	Verhalten und Hilfetext
SMTP-Host	leer, Platzhalter mail.example.com	Pflichtfeld. Nur Hostnamen und IP-Adressen; Zeichen wie @, /, ? oder Leerzeichen werden abgewiesen.
Port	587	Ganzzahl von 1 bis 65535.
Verschlüsselung	STARTTLS (Port 587)	Auswahl aus Keine, STARTTLS (Port 587) und SSL/TLS (Port 465). Die Auswahl bestimmt das Verbindungsverfahren, nicht den Port — dieser wird separat gesetzt.
Benutzername	leer	Optional. Leer bedeutet: Verbindung ohne Anmeldung.
Passwort	leer, wird nie vorausgefüllt	„Leer lassen, um das bestehende Passwort beizubehalten."
Absender-E-Mail	leer	Pflichtfeld. Wird nur für die Test-Mail verwendet und nicht gespeichert.
Test-Empfänger	leer	Pflichtfeld. „Vor dem Speichern wird eine Test-Mail an diese Adresse gesendet."

Test-Mail vor dem Speichern

Der Kern des Pakets: Jedes Speichern ist zuerst ein echter Versandversuch. Erst wenn die Test-Mail durchgeht, wird die Verbindung nach .env.local geschrieben — schlägt sie fehl, bleibt der bisherige Stand unangetastet.

So verläuft ein Speichervorgang

1. Die Eingaben werden geprüft: Host vorhanden, Absenderadresse gültig, Test-Empfängeradresse gültig.
2. Aus den Feldern wird die Verbindungszeile zusammengesetzt. Benutzername und Passwort werden dabei korrekt kodiert — Sonderzeichen im Passwort brauchen keine Vorbehandlung.
3. Über genau diese Verbindung wird eine Mail mit dem Betreff SMTP Test — vtinnovations/smtp-bundle an den Test-Empfänger gesendet.
4. Scheitert der Versand, erscheint „Test-Mail fehlgeschlagen (…s): …" mit der Meldung, die der Mailserver zurückgegeben hat. Es wurde nichts gespeichert.
5. Bei Erfolg wird MAILER_DSN in .env.local geschrieben — eine bestehende Zeile wird ersetzt, sonst eine neue angehängt.
6. Anschließend läuft das Cache-Leeren.
7. Die Erfolgsmeldung nennt die Dauer des Versands: „Test-Mail erfolgreich gesendet (…s). Konfiguration gespeichert, Cache geleert."

Passwort bei Änderungen beibehalten

Das Passwortfeld wird nie vorausgefüllt. Damit eine spätere Änderung an Host, Port oder Verschlüsselung nicht daran scheitert, dass niemand mehr das Mailserver-Passwort zur Hand hat, gilt: ein leeres Passwortfeld bedeutet das bisherige Passwort weiterverwenden — nicht das Passwort löschen.

So ändern Sie Host, Port oder Verschlüsselung ohne das Passwort

1. System → SMTP-Konfiguration öffnen. Host, Port, Verschlüsselung und Benutzername sind aus der gespeicherten Verbindung vorausgefüllt.
2. Die gewünschten Felder ändern. Den Benutzernamen dabei stehen lassen — ohne ihn kann das bisherige Passwort nicht übernommen werden.
3. Das Feld Passwort leer lassen.
4. Absender-E-Mail und Test-Empfänger erneut eintragen; diese beiden Felder sind nach jedem Aufruf wieder leer.
5. Testen & Speichern drücken. Die Test-Mail läuft über das bisherige Passwort und die neuen übrigen Werte.

Um das Passwort zu wechseln, tragen Sie es einfach ein — jeder nicht leere Wert im Passwortfeld ersetzt den bisherigen.

Cache-Leeren mit Wartungsseite

Ein geschriebener MAILER_DSN-Eintrag wirkt erst, wenn der Anwendungs-Cache erneuert wurde. Das Paket übernimmt diesen Schritt unmittelbar nach dem Speichern — und blendet währenddessen eine Wartungsseite ein, damit Besucher nicht auf eine halb aufgebaute Anwendung treffen.

Ausgeführt werden zwei Vorgänge, in dieser Reihenfolge:

bin/console cache:clear --no-warmup --env=prod --no-interaction
bin/console cache:warmup --env=prod --no-interaction

Für die Dauer beider Vorgänge liegt var/maintenance.html vor und zeigt Besuchern die Seite „Kurze Wartungspause — Die Seite wird in Kürze wieder verfügbar sein.", die sich alle zehn Sekunden selbst neu lädt. Die Datei wird anschließend wieder entfernt, auch wenn das Cache-Leeren fehlschlägt.

So gehen Sie vor, wenn das Cache-Leeren fehlschlägt

1. Die Meldung lesen: „Konfiguration gespeichert, aber Cache-Clear fehlgeschlagen. Bitte manuell leeren. Fehler: …" Die Mailer-Konfiguration ist zu diesem Zeitpunkt bereits gespeichert — nur der Cache-Schritt ist offen.
2. Den Cache von Hand leeren:

   bin/console cache:clear

3. Nennt die Meldung, dass die PHP-CLI-Binärdatei nicht gefunden wurde, deren Pfad in config/config.yaml hinterlegen:

   vtinnovations_smtp:
       php_binary: '/pfad/zu/php'

4. Üblich sind /usr/bin/php, ein versionsbezogener Pfad wie /usr/bin/php8.3 oder ein kontrollpanel-eigener Pfad unter /opt/plesk/php/… beziehungsweise /opt/cpanel/ea-php…/root/usr/bin/php. Im Zweifel beim Hosting-Anbieter erfragen.
5. Bricht der Vorgang wegen Zeitüberschreitung ab, process_timeout erhöhen (Sekunden, Minimum 30, Vorgabe 120).

Mailer wieder deaktivieren

Um den Versand wieder Contao selbst zu überlassen, wird der MAILER_DSN-Eintrag aus .env.local entfernt. Dafür gibt es einen Konsolenbefehl — im Backend gibt es für diesen Schritt keine Schaltfläche.

So deaktivieren Sie den konfigurierten Mailer

1. Auf dem Server im Projektverzeichnis anmelden.
2. Den Befehl ausführen:

   bin/console vtinnovations:smtp:disable --clear-cache

3. Die Bestätigung lautet „MAILER_DSN removed from .env.local. Contao will use default mailer.", gefolgt von „Cache cleared and warmed up."
4. War kein Eintrag vorhanden, meldet der Befehl „MAILER_DSN not set in .env.local — nothing to remove." und beendet sich erfolgreich.
5. Ohne --clear-cache weist der Befehl darauf hin, dass bin/console cache:clear noch auszuführen ist. Bis dahin bleibt die alte Verbindung aktiv.
6. Im Backend zeigt System → SMTP-Konfiguration anschließend wieder ✗ Nicht konfiguriert.

Lizenz verwalten

Die Lizenzverwaltung liegt unter Contao → Einstellungen im Abschnitt V-T.ONE Licence management, Block SMTP Konfigurator — nicht im SMTP-Modul selbst, damit mehrere gemeinsam installierte V-T.ONE-Pakete an einer Stelle verwaltet werden können. Die drei Schaltflächen dort sind Administratoren vorbehalten.

Schaltfläche	Wann sie erscheint	Was sie bewirkt
Lizenz prüfen und aktivieren	immer	Aktiviert den im Feld Lizenzschlüssel eingetragenen Schlüssel für diese Installation. Erfolgsmeldung: „Lizenz aktiviert."
Lizenz aktualisieren	nur bei aktiver Lizenz	Holt den aktuellen Stand der bereits hinterlegten Lizenz. Der Schlüssel muss dafür nicht erneut eingegeben werden. Erfolgsmeldung: „Lizenz aktualisiert."
Lizenz entfernen	nur bei aktiver Lizenz	Entfernt die Lizenz von dieser Installation. Erfolgsmeldung: „Lizenz entfernt. SMTP Konfigurator verhält sich wieder wie im unlizenzierten Standard."

Das Feld darüber trägt die Beschriftung Lizenzschlüssel und den Hilfetext: „Schlüssel eintragen und aktivieren. Bereits lizenziert? Nach einer Verlängerung oder Domain-Änderung genügt ‚Lizenz aktualisieren' — der Schlüssel muss nicht erneut eingegeben werden."

So aktualisieren Sie eine Lizenz nach einer Domain-Änderung

1. Die neue Domain bei V-T.ONE für den bestehenden Schlüssel eintragen lassen.
2. Sicherstellen, dass die Installation diese Domain auch selbst kennt — siehe Domain-Bindung.
3. Als Administrator Einstellungen öffnen und zum Block SMTP Konfigurator gehen.
4. Lizenz aktualisieren drücken. Das Schlüsselfeld bleibt dabei leer.
5. Die Meldung „Lizenz aktualisiert." abwarten und die Detailzeile prüfen — Zuletzt geprüft: trägt nun den aktuellen Zeitpunkt.

So entfernen Sie eine Lizenz

1. Falls der Mailer weiterhin laufen soll: vorher klären, dass der Eintrag in .env.local bestehen bleiben darf — er wird durch das Entfernen der Lizenz nicht angetastet.
2. Im Block SMTP Konfigurator auf Lizenz entfernen drücken.
3. Die Rückfrage bestätigen: „Aktivierte Lizenz entfernen? Diese Installation kehrt sofort zu ihrem unlizenzierten Standardverhalten zurück."
4. Die Bestätigung „Lizenz entfernt. …" erscheint; die Schaltflächen Lizenz aktualisieren und Lizenz entfernen verschwinden.

Domain-Bindung

Eine Lizenz gilt für einen oder mehrere exakte Hostnamen. example.com, www.example.com und shop.example.com sind drei verschiedene Identitäten; eine für eine davon ausgestellte Lizenz deckt die anderen nicht ab. Es gibt keinen Abgleich über Suffixe, keine Zusammenfassung auf die übergeordnete Domain und keine Gleichsetzung von www. mit der Domain ohne Präfix.

Mehrere Domains auf einer Installation werden unterstützt: Eine Übereinstimmung zwischen den Hostnamen, die die Installation für sich beansprucht, und den in der Lizenz eingetragenen genügt zur Aktivierung.

Die Hostnamen der Installation stammen ausschließlich aus Ihrer eigenen Konfiguration, in dieser Reihenfolge:

1. das Feld DNS der Startseiten im Seitenbaum,
2. die Liste vtinnovations_smtp.domains in config/config.yaml,
3. als letzte Möglichkeit der im Router hinterlegte Standard-Host.

So hinterlegen Sie die Domains ausdrücklich

1. Prüfen, ob die Startseiten ein gefülltes DNS-Feld haben (Seitenstruktur → Startseite bearbeiten). Auf Installationen mit nur einer Domain ist dieses Feld häufig leer.
2. Ist es leer, die Hostnamen in config/config.yaml eintragen:

   vtinnovations_smtp:
       domains:
           - 'example.com'
           - 'www.example.com'

3. Jede Schreibweise einzeln aufführen, unter der die Seite erreichbar ist — mit und ohne www., sofern beides genutzt wird.
4. Cache leeren:

   bin/console cache:clear

5. Im Backend unter Einstellungen die Lizenz aktivieren oder über Lizenz aktualisieren neu abgleichen.

Teil 3 — Für Entwickler

Konsolenbefehl

Das Paket bringt genau einen Konsolenbefehl mit:

bin/console vtinnovations:smtp:disable [--clear-cache]

Eigenschaft	Wert
Name	vtinnovations:smtp:disable
Beschreibung	Remove MAILER_DSN from .env.local so Contao falls back to default mailer.
Option --clear-cache	ohne Wert, standardmäßig nicht gesetzt. Also clear and warmup the Symfony cache after disabling.
Rückgabewert 0	Eintrag entfernt, oder es war keiner vorhanden
Rückgabewert 1	Installation nicht lizenziert, oder das Cache-Leeren ist fehlgeschlagen

Die Ausgaben des Befehls sind englischsprachig; der Bildschirm im Backend ist es nicht.

Konfigurationsreferenz

Wurzelschlüssel vtinnovations_smtp, gesetzt in config/config.yaml:

Schlüssel	Typ	Standard	Bedeutung
php_binary	Zeichenkette	''	Pfad zur PHP-Binärdatei für den Cache-Unterprozess. Leer bedeutet automatische Erkennung.
process_timeout	Ganzzahl	120, Minimum 30	Sekunden, nach denen der Cache-Unterprozess abgebrochen wird.
domains	Liste von Zeichenketten	[]	Hostnamen, die diese Installation bedient, genutzt, wenn Startseiten kein DNS-Feld tragen. Ausschließlich exakte Hostnamen: example.com deckt weder www.example.com noch eine Subdomain ab.

Dateien und Verzeichnisse

Ort	Zweck	Lebensdauer
.env.local	trägt den Schlüssel MAILER_DSN, sobald der Mailer konfiguriert ist	dauerhaft
var/maintenance.html	Wartungsseite während eines ausgelösten Cache-Vorgangs	nur für dessen Dauer
ein privates Verzeichnis unterhalb von var/	interner Zustand des Pakets; außerhalb des öffentlichen Web-Roots und nicht über HTTP erreichbar. Muss für den Webserver beschreibbar sein und gehört in die Datensicherung.	dauerhaft

Datenbank: Das Paket legt keine Tabellen und keine Spalten an. Eine Schema-Migration ist durch dieses Paket allein nicht erforderlich. Gelesen wird lediglich das DNS-Feld der Startseiten.

Backend-Registrierung: Das Modul liegt in der Navigationsgruppe system unter dem Schlüssel vtinnovations_smtp. Der Abschnitt in den Einstellungen wird als eigenes Feld in tl_settings gerendert und schreibt nichts in die lokale Konfiguration zurück.

Integration und Erweiterbarkeit

Das Paket ist bewusst schmal. Was es nicht mitbringt, ist genauso wichtig wie das, was es kann:

Integrationspunkt	Stand
Contao-Hooks	Keine. Das Paket registriert keinen Hook und ruft keinen eigenen auf.
Frontend-Module, Inhaltselemente, Seitentypen	Keine. Das Paket ist ausschließlich für das Backend.
Eigene Events	Keine öffentlichen Events, auf die sich eine Erweiterung registrieren könnte.
Öffentliche Service-Schnittstellen	Keine zugesicherten. Die internen Services sind kein dokumentierter Erweiterungspunkt und können sich zwischen Versionen ändern.
Twig-Templates	Keine. Beide Bildschirme werden direkt gerendert und sind nicht per Template überschreibbar.
Berechtigungen	Keine feinere Abstufung. Der SMTP-Bildschirm und die Lizenzaktionen sind Administratoren vorbehalten.

Protokollierung: Der Konfigurationsweg — Test-Mail, Speichern, Cache — schreibt nichts in das Anwendungs-Log. Jede Rückmeldung erscheint unmittelbar auf dem Bildschirm, einschließlich der Originalmeldung des Mailservers. Für die Fehlersuche ist damit der Bildschirm selbst die Quelle, nicht die Logdatei.

Deployment und Cache

Über den üblichen Contao-Schritt hinaus gibt es kein paketspezifisches Deployment:

composer require vtinnovations/smtp-bundle
bin/console cache:clear

Zu beachten bei mehrstufigen Umgebungen:

• .env.local gehört nicht in die Versionsverwaltung und wird typischerweise nicht mit ausgerollt. Der Mailer wird je Umgebung einmal eingerichtet.
• Eine Lizenz ist an Hostnamen gebunden. Eine Staging-Domain ist ein eigener Hostname und braucht einen eigenen Eintrag in der Lizenz, sonst bleibt das Paket dort ohne Funktion.
• Der private Zustand des Pakets unterhalb von var/ wird bei einem Deployment, das var/ neu anlegt, nicht automatisch übernommen. Entweder wird er mit übernommen, oder die Lizenz wird auf dem Zielsystem erneut aktiviert.
• Das automatische Cache-Leeren startet einen PHP-Unterprozess. In Umgebungen, die das unterbinden, bleibt das Speichern funktionsfähig — der Cache muss dann im Deployment-Skript erneuert werden.

Fehlerbehebung

Symptom	Ursache und Prüfung
„Zugriff verweigert. Nur Administratoren."	Das Backend-Konto ist kein Administrator. Der Bildschirm kennt keine feinere Berechtigung — das Konto muss zum Administrator gemacht werden oder die Aufgabe an einen Administrator gehen.
„Keine Lizenz. Schlüssel unter v-t.one anfordern und unten eintragen."	Es ist keine Lizenz aktiviert. Schlüssel unter Einstellungen eintragen und Lizenz prüfen und aktivieren drücken — siehe Lizenz aktivieren.
„Es wurde kein Lizenzschlüssel eingegeben."	Die Schaltfläche wurde bei leerem Feld gedrückt. Schlüssel eintragen und erneut aktivieren.
„Dieser Lizenzschlüssel wurde für diese Installation nicht akzeptiert."	Schlüssel auf Tippfehler prüfen und abgleichen, ob er für dieses Produkt und für diese Installation ausgestellt wurde. Bleibt es dabei, bei V-T.ONE nachfragen.
„Der Lizenzdienst war nicht erreichbar. Es wurde nichts geändert — bitte später erneut versuchen."	Die Aktivierung braucht eine ausgehende HTTPS-Verbindung vom Server, nicht vom Browser. Ausgehende Verbindungen und eine etwaige Firewall prüfen, danach erneut versuchen. Der gespeicherte Zustand ist unverändert.
„Diese Lizenz ist für keine der auf dieser Installation konfigurierten Domains ausgestellt."	Das DNS-Feld der Startseiten und vtinnovations_smtp.domains gegen die Domains abgleichen, für die die Lizenz ausgestellt wurde. Abweichung korrigieren, dann Lizenz aktualisieren — siehe Domain-Bindung.
„Für diese Installation ist keine Domain konfiguriert. Bitte das DNS-Feld einer Startseite setzen oder vtinnovations_smtp.domains in der Konfiguration."	Genau das tun: DNS-Feld einer Startseite füllen oder die Hostnamen in config/config.yaml eintragen, Cache leeren, erneut aktivieren.
„Dieser Lizenzschlüssel ist für den Free-Plan dieses Produkts nicht gültig."	Prüfen, ob der Schlüssel für dieses Produkt bestimmt ist. Bei V-T.ONE nachfragen, falls das unerwartet ist.
„Diese Lizenz ist für diese Installation nicht mehr aktiv."	Bei V-T.ONE den Stand dieser Lizenz erfragen. Nach der Klärung holt Lizenz aktualisieren den berichtigten Zustand.
„Die gespeicherte Lizenz konnte nicht geprüft werden. Bitte den Lizenzschlüssel erneut eintragen."	Den Schlüssel erneut in das Feld eintragen und Lizenz prüfen und aktivieren drücken.
„Diese Lizenz stammt aus einem älteren Format. Schlüssel erneut eintragen, um eine aktualisierte Fassung abzurufen."	Denselben Schlüssel erneut eintragen und aktivieren. Weitere Schritte sind nicht nötig.
„Diese Installation kann Lizenzen nicht prüfen: Es ist kein Prüfschlüssel vorhanden. Bitte aus einem offiziellen Release neu installieren."	Ein Problem der installierten Fassung, das kein Lizenzschlüssel löst. Das Paket über den Contao Manager oder Composer aus einer offiziellen Veröffentlichung neu installieren.
„Die Lizenz konnte nicht gespeichert werden. Bitte prüfen, ob var/ beschreibbar ist."	Schreibrechte des Webserver-Benutzers auf var/ prüfen und den Vorgang wiederholen.
„Zugriff verweigert" oder „Ungültiges Sicherheitstoken" beim Drücken einer Lizenz-Schaltfläche	Entweder ist das Konto kein Administrator, oder die Backend-Sitzung ist abgelaufen. Neu anmelden, die Einstellungen frisch laden und die Schaltfläche erneut drücken.
„SMTP-Host ist erforderlich." / „Gültige Absender-E-Mail-Adresse ist erforderlich." / „Gültige Test-Empfänger-Adresse ist erforderlich."	Eines der drei Pflichtfelder ist leer oder keine gültige Adresse. Absender und Test-Empfänger sind nach jedem Aufruf des Bildschirms wieder leer und müssen jedes Mal neu eingetragen werden.
„Ungültige Konfiguration: Invalid host. Only hostnames and IP addresses are allowed."	Im Feld SMTP-Host steht mehr als ein Hostname — etwa smtp://, ein Doppelpunkt mit Port, ein Pfad, ein @ oder ein Leerzeichen. Nur den reinen Hostnamen eintragen; eine IPv6-Adresse in eckige Klammern setzen.
„Test-Mail fehlgeschlagen (…s): …"	Die angehängte Meldung stammt vom Mailserver und ist der direkteste Hinweis. Prüfen: Passen Port und Verschlüsselung zusammen (STARTTLS meist 587, SSL/TLS meist 465)? Erreicht der Server den Mail-Host auf diesem Port? Stimmen Benutzername und Passwort? Wird die Absenderadresse von diesem Konto akzeptiert? Es wurde nichts gespeichert.
„Fehler beim Speichern: Cannot write to …/.env.local"	Der Webserver-Benutzer darf .env.local nicht schreiben. Rechte und Eigentümer der Datei im Projektverzeichnis prüfen.
„Konfiguration gespeichert, aber Cache-Clear fehlgeschlagen. Bitte manuell leeren. Fehler: …"	Die Mailer-Konfiguration steht bereits. bin/console cache:clear von Hand ausführen; bei Meldungen zur PHP-Binärdatei php_binary setzen — siehe Cache-Leeren.
Die Änderung wirkt nicht, obwohl gespeichert wurde	Der Cache trägt noch die alte Verbindung. Prüfen, ob die Erfolgsmeldung tatsächlich „Cache geleert" enthielt; andernfalls den Cache von Hand leeren.
Besucher sehen „Kurze Wartungspause"	Ein Cache-Vorgang läuft gerade; die Seite lädt sich alle zehn Sekunden selbst neu. Bleibt der Zustand nach Abschluss bestehen, var/maintenance.html löschen.
„This command is not available for this installation." auf der Konsole	Der Konsolenbefehl setzt eine aktivierte Lizenz voraus. Erst den Lizenzstatus klären, dann den Befehl erneut ausführen.
Eine Domain mit Umlauten oder anderen Nicht-ASCII-Zeichen lässt sich nicht aktivieren	ext-intl auf dem Server installieren oder aktivieren und die Aktivierung wiederholen.

Bekannte Einschränkungen

• Absender und Test-Empfänger werden nicht gespeichert. Beide Felder dienen nur der Test-Mail und sind bei jedem Aufruf des Bildschirms wieder leer.
• Nur SMTP und SMTPS. Der Bildschirm erzeugt ausschließlich SMTP-Verbindungen. Für API-basierte Transaktions-Mail-Dienste gibt es hier keine Oberfläche; solche Dienste lassen sich weiterhin von Hand über die Mailer-Konfiguration von Contao einbinden.
• Nur Administratoren. Es gibt keine Berechtigung, die den Bildschirm für Backend-Benutzer ohne Administratorrechte öffnet.
• Kein Backend-Weg zum Deaktivieren. Das Entfernen der Mailer-Verbindung läuft ausschließlich über den Konsolenbefehl — im Backend gibt es dafür keine Schaltfläche.
• Das Cache-Leeren braucht einen PHP-CLI-Aufruf. Wo der Webserver keine Unterprozesse starten darf, schlägt dieser Schritt fehl; die Konfiguration selbst ist dann bereits gespeichert.
• Der Speichervorgang läuft synchron und kann je nach Mailserver und Installationsgröße deutlich über eine Minute dauern.
• Ohne ext-intl lässt sich eine Domain mit Nicht-ASCII-Zeichen nicht aktivieren.
• Eine Lizenzstufe. Für dieses Produkt gibt es ausschließlich Lifetime Free. Die Oberfläche zeigt aus Gründen der Einheitlichkeit innerhalb der Produktfamilie eine Free-/Pro-Kennzeichnung; eine kostenpflichtige Stufe ist für dieses Produkt nicht vorgesehen.
• Keine Erweiterungspunkte. Keine Hooks, keine öffentlichen Events, keine überschreibbaren Templates.

Deinstallation

In dieser Reihenfolge, damit nichts von Hand nachgeholt werden muss:

1. Den Mailer deaktivieren, solange die Lizenz noch aktiv ist:

   bin/console vtinnovations:smtp:disable --clear-cache

   Soll der bisherige Mailserver dagegen weiter genutzt werden, diesen Schritt überspringen — der Eintrag in .env.local bleibt dann bestehen und funktioniert ohne das Paket weiter.
2. Die Lizenz entfernen: Einstellungen → Block SMTP Konfigurator → Lizenz entfernen, Rückfrage bestätigen.
3. Das Paket entfernen — im Contao Manager unter Pakete über Installierte Pakete, oder auf der Konsole:

   composer remove vtinnovations/smtp-bundle

4. Die Laufzeitdaten des Pakets löschen. Das Verzeichnis var/vtinnovations-smtp/ bleibt bei einer Paketentfernung stehen und kann anschließend gelöscht werden.
5. Cache leeren:

   bin/console cache:clear

Datenbanktabellen oder -spalten sind nicht zu entfernen: Das Paket hat keine angelegt. Inhalte, Seiten und Einstellungen von Contao bleiben in jedem Fall unberührt.