Kontaktformulare und Nachrichten

Kontaktformular und Kontaktnachrichten sind erstklassige WebBlocks-CMS-Funktionen. Verwenden Sie für Kontaktseiten den nativen contact_form-Block anstelle von Trusted HTML, rohem Formular-Markup oder mailto:-Fallbacks.

Dieser Leitfaden fasst das benutzerorientierte Verhalten von Kontaktformular und Kontaktnachrichten zusammen, das in Blockverträgen, öffentlichen Render-Verträgen, der Internal-Content-API-Dokumentation und der README dokumentiert ist. Er definiert kein neues Laufzeitverhalten.

Der Kontaktformular-Block rendert ein echtes öffentliches Formular und speichert akzeptierte Nachrichten im CMS. Kontaktnachrichten bietet Administratoren einen Prüfbildschirm für diese Einsendungen, einschließlich Status, Spam-Prüfsignalen, Benachrichtigungsstatus und sicheren Details zu Zustellfehlern.

Das CMS behandelt Speicherung und E-Mail-Benachrichtigung als getrennte Anliegen:

• akzeptierte echte Einsendungen werden gespeichert, bevor eine Benachrichtigung versucht wird
• die Benachrichtigung kann erfolgreich sein, fehlschlagen oder übersprungen werden, ohne dass sich daran etwas ändert, dass das CMS die öffentliche Einsendung akzeptiert hat
• öffentliche Besucher sollten generische Erfolgs- oder Validierungsrückmeldungen sehen, keine Spam-Bewertung oder Zustellungsinterna

Fügen Sie den Block über die Blockauswahl des Page Builders hinzu. Das native Block-Handle lautet:

Der Kontaktformular-Block ist kein Kind-Container. Er besitzt die öffentliche Formularfläche und akzeptiert verschachtelte Inhaltsblöcke nicht als sein normales Kompositionsmodell.

Eine typische Kontaktseite verwendet strukturierte Inhalte rund um das native Formular:

KI-/Operator-Tools sollten dieselbe Art von Struktur aufbauen, nachdem die Live-Discovery die verfügbaren Handles bestätigt hat. Sie sollten keine Formulare mit Trusted HTML, rohem <form>-Markup oder mailto:-Links erstellen, wenn contact_form in der Ziel-CMS-Installation vorhanden ist.

Sichtbare Texte sind übersetzbar:

• title oder Überschrift
• content oder Einleitungstext
• submit_label
• success_message

Gemeinsame operative Einstellungen liegen in den Blockeinstellungen:

• recipient_email
• send_email_notification
• store_submissions

Halten Sie redaktionelle Texte und operatives Routing getrennt. Der Formulartext kann je nach Sprache (Locale) variieren, während Empfänger- und Benachrichtigungseinstellungen für den Block gemeinsam bleiben.

Der öffentliche Renderer erzeugt ein natives Browser-Formular, das an folgende Adresse sendet:

Das Formular ist CSRF-geschützt und validiert die normalen Besucherfelder.

Pflichtfelder:

• name
• email
• message

Optionales Feld:

• subject

Vom Renderer generiertes Anti-Spam-Prüffeld:

• _form_check_name signierte Metadaten
• form_check_{token} generiertes Prüffeld

Der Renderer erstellt diese Felder automatisch. Erstellen Sie sie nicht manuell in Inhalten, rohem HTML oder API-Payloads. Das Prüffeld ist nicht Teil der normalen Besuchereingabe, und das alte website-Feld gehört nicht mehr zum öffentlichen Kontaktformular-Vertrag.

Einsendungen mit ausgefülltem Prüffeld erhalten dasselbe generische Erfolgsverhalten wie eine normal akzeptierte Einsendung, werden aber nicht gespeichert und lösen keine Benachrichtigung aus. Sehr schnelle automatisierte Einsendungen werden genauso behandelt. Öffentliche Besucher sollten keine Spam- oder Zustelldiagnosen erhalten.

Akzeptierte echte Einsendungen werden gespeichert, bevor eine E-Mail-Benachrichtigung versucht wird.

Admin-Pfad:

Kontaktnachrichten ist ein Admin-Prüfbildschirm. Es ist keine öffentliche Auflistung und keine öffentliche Zustell-API.

Der Admin-Bildschirm ermöglicht CMS-Benutzern die Prüfung von Einsendungen auf Benutzerhandbuch-Niveau:

• Nachrichtenstatus wie neu, gelesen, beantwortet, archiviert oder Spam
• Kontext der Ursprungsseite, sofern verfügbar
• Spam-Score und Spam-Grund-Labels zur Prüfung
• ob die Benachrichtigung übersprungen, gesendet, fehlgeschlagen oder ausstehend ist
• sichere Fehlerdetails, wenn die Zustellung der Benachrichtigung fehlschlägt

Der E-Mail-Benachrichtigungsstatus betrifft ausschließlich das Benachrichtigungsverhalten:

• Sent bedeutet, dass das CMS die Nachricht ohne Ausnahme an den konfigurierten Mail-Transport übergeben hat. Eine Zustellung ins Postfach ist damit nicht garantiert.
• Failed bedeutet, dass ein echter Benachrichtigungsversand versucht wurde und Laravel eine Ausnahme gemeldet hat. Das gespeicherte Detail ist bereinigt und darf keine Passwörter, Tokens, rohes .env oder Stacktraces enthalten.
• Skipped bedeutet, dass keine Benachrichtigung versucht wurde, in der Regel weil der Block die Benachrichtigung deaktiviert hat.
• Not configured bedeutet, dass keine Benachrichtigung versucht wurde, weil kein Empfänger verfügbar war, der Mailer log, array oder null ist oder die SMTP-Einstellungen so unvollständig sind, dass kein ausgehender Versand möglich ist.
• Pending ist Einträgen vorbehalten, für die noch kein Benachrichtigungsversuch oder keine Auflösung vorliegt.

Bei älteren gespeicherten Nachrichten kann der Benachrichtigungsstatus aus den Legacy-Feldern sent/error abgeleitet sein. Das CMS schreibt diese historischen Einträge nicht automatisch um.

Kontaktnachrichten folgt außerdem dem gemeinsamen Admin-Listenverhalten für die Massenlöschung ausgewählter Einträge, sofern verfügbar. Behandeln Sie die Löschung als administrative Aufräumaktion, nicht als Teil der normalen öffentlichen Formularverarbeitung.

Die Spam-Behandlung hat zwei Ebenen.

Die Ebene des vom Renderer generierten Prüffelds ist das sofortige Verwerfen:

• das versteckte generierte Feld form_check_{token} sollte bei normalen Besuchern leer bleiben
• Einsendungen mit ausgefülltem Prüffeld erhalten eine generische Erfolgsmeldung
• Prüffeld-Einsendungen werden nicht gespeichert
• Prüffeld-Einsendungen lösen keine Benachrichtigung aus

Einsendungen, die das generierte Prüffeld passieren, können dennoch konservativ bewertet werden. Aktuelle Beispiele für Bewertungssignale sind:

• hohe Linkdichte oder mehrere Links
• kommerzielle Ansprache-Sprache
• generische verkaufsartige Betreff- und Nachrichtenkombinationen
• wiederholte Einsendungen von derselben IP-Adresse

Bewerteter Spam wird bewusst mit Spam-Status zur Admin-Prüfung aufbewahrt. Beschreiben Sie eine automatische Spam-Löschung nicht als aktuelles Verhalten. Ein konfigurierbarer Schwellenwert zum automatischen Verwerfen ist nur eine mögliche künftige Richtung nach Beobachtung von Produktionsdaten.

Die Kontaktformular-Benachrichtigung verwendet diese Empfängerreihenfolge:

1. recipient_email auf Blockebene
2. Standard-Kontaktempfänger der aktuellen Site aus Edit Site -> Contact
3. CONTACT_RECIPIENT_EMAIL
4. MAIL_FROM_ADDRESS als letzter sicherer Fallback

Der Speichererfolg ist vom Benachrichtigungserfolg getrennt. Eine öffentliche Erfolgsmeldung bedeutet, dass das CMS den Nachrichtenfluss akzeptiert hat, nicht unbedingt, dass die E-Mail-Zustellung erfolgreich war. Administratoren sollten Kontaktnachrichten auf Benachrichtigungsstatus und sichere Fehlerdetails prüfen.

Kontaktformular-Benachrichtigungen verwenden den Laravel-Mailversand. Typische SMTP-Einstellungen in der .env sind:

MAIL_* steuert den Laravel-Mail-Transport. MAIL_FROM_ADDRESS ist die sichere Fallback-Absenderadresse und der letzte sichere Empfänger-Fallback. CONTACT_RECIPIENT_EMAIL ist optional und wird nur verwendet, wenn Block- und Site-Empfänger leer sind. Bevorzugen Sie für das normale Site-Routing den Kontaktempfänger auf Site-Ebene unter Site -> Edit -> Contact.

Verwenden Sie für Produktionsbenachrichtigungen einen echten ausgehenden Mailer wie SMTP. MAIL_MAILER=log, MAIL_MAILER=array und MAIL_MAILER=null sind für Entwicklung oder Tests nützlich, aber Kontaktnachrichten zeigt diese als nicht konfiguriert statt als gesendet an, weil kein echter ausgehender Benachrichtigungsversuch stattfand.

Leeren Sie nach dem Bearbeiten der .env-Mail-Einstellungen auf einer Produktions- oder Paketinstallation die zwischengespeicherte Konfiguration, wenn Config-Caching aktiv sein könnte:

Verwenden Sie für die lokale Entwicklung einen lokalen SMTP-Catcher oder ein vertrauenswürdiges SMTP-Testkonto. Vermeiden Sie es, die Kontaktzustellung gegen persönliche oder Produktionspostfächer zu testen, es sei denn, der Operator hat diese Umgebung absichtlich so konfiguriert.

Der Diagnosebefehl lautet:

Verwenden Sie eine bestimmte Kontaktformular-Block-ID, um den Empfänger-Fallback für diesen Block zu prüfen:

Verwenden Sie eine kontrollierte SMTP-Versandprüfung nur, wenn die Ziel-Testadresse beabsichtigt ist:

Diagnosen dürfen keine Passwörter, Tokens, Mail-Geheimnisse oder rohe sensible Konfiguration ausgeben. Fehlgeschlagene, übersprungene und nicht konfigurierte Benachrichtigungsdetails können in Kontaktnachrichten eingesehen werden. Behandeln Sie Kontaktnachrichten als maßgebliche Quelle für gespeicherte Einsendungen und deren Benachrichtigungsstatus.

Vor dem Veröffentlichen oder Ankündigen einer öffentlichen Kontaktseite:

1. Bestätigen Sie, dass der Admin-Login funktioniert.
2. Bestätigen Sie, dass Site-Identität und Domain-Einstellungen korrekt sind.
3. Konfigurieren Sie den MAIL_*-Versand oder genehmigte System-Mail-Einstellungen.
4. Konfigurieren Sie den Kontaktempfänger, vorzugsweise unter Site -> Edit -> Contact.
5. Führen Sie php artisan contact:mail-diagnose aus.
6. Zeigen Sie eine Seite mit dem nativen contact_form-Block in der Vorschau an oder veröffentlichen Sie sie.
7. Senden Sie eine Testnachricht mit Name, E-Mail, Betreff und Nachricht.
8. Bestätigen Sie, dass /webadmin/contact-messages die gespeicherte Nachricht anzeigt.
9. Prüfen Sie den Benachrichtigungsstatus und etwaige sichere Fehlerdetails.

Wenn die Benachrichtigung fehlschlägt, die Nachricht aber gespeichert wurde, behandeln Sie dies als Mail-Zustellungsproblem, nicht als fehlgeschlagene öffentliche Formulareinsendung.

Die Internal Content API ist für vertrauenswürdige KI-/Operator-Tools gedacht. Sie ist keine öffentliche Zustell-API und keine Integration eines KI-Anbieters.

KI-/Operator-Tools sollten mit einer Live-Discovery beginnen:

Verwenden Sie dann die entdeckten Links für die aktuellen Verträge:

GET /webadmin/api/examples/contact-page demonstriert die native Verwendung von contact_form. KI-/Operator-Tools dürfen keine Handles raten und keine Kontaktformulare mit Trusted HTML, rohem Formular-Markup oder mailto:-Links erstellen, wenn der native Kontaktformular-Block verfügbar ist.

Das Anwenden von Inhalten bleibt Entwurf-zuerst und veröffentlicht standardmäßig nicht. Operatoren sollten Pläne validieren, erst nach ausdrücklicher Genehmigung anwenden, die Entwurfsseite in der Vorschau prüfen und das Veröffentlichen einem Menschen oder einem ausdrücklich genehmigten Workflow überlassen.

• Blocktyp-Verträge
• Öffentliches Block-Render-Markup
• Renderer-Verträge
• Internal Content API
• API-Discovery
• Leitfaden für KI-Seitenerstellung
• Funktionsinventar