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.

Überblick

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

Einen Kontaktformular-Block hinzufügen

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

contact_form

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:

main slot
  section
    container
      content_header or hero
      contact_form

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.

Felder des Kontaktformular-Blocks

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.

Öffentliches Absendeverhalten

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

POST /contact-messages

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.

Speicherung und Kontaktnachrichten-Verwaltung

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

Admin-Pfad:

/webadmin/contact-messages

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.

Spam-Behandlung

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.

Fallback-Kette der E-Mail-Benachrichtigung

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.

E-Mail-Einrichtung

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

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Site Name"

CONTACT_RECIPIENT_EMAIL=contact@example.com

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:

php artisan optimize:clear

Fehlerbehebung und Diagnose

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:

php artisan contact:mail-diagnose

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

php artisan contact:mail-diagnose --block=ID

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

php artisan contact:mail-diagnose --send-test=address@example.com

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.

Checkliste zur Veröffentlichungsbereitschaft

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.

Internal Content API und KI-Operator-Unterstützung

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:

GET /webadmin/api

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

GET /webadmin/api/content-contract
GET /webadmin/api/block-types
GET /webadmin/api/examples/contact-page

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.

Verwandte Dokumente