KC-Mail: PHP-Kontaktformular mit Cloudflare Turnstile & SMTP (1-Zeilen-Einbindung)

Github Download: https://github.com/kerimcandan/kc-mail

KC-Mail ist ein leichtgewichtiges, kostenloses Kontaktformular für klassische HTML– und PHP-Websites.
Es bringt eine moderne Admin-Oberfläche, Cloudflare Turnstile (Bot-Schutz), AJAX-Versand ohne Seitenreload, SMTP (inkl. eingebautem Fallback ohne PHPMailer) und 3 responsive Themes mit.

In 1 Zeile einbinden – ideal für kleine Projekte, Landingpages, statische Seiten oder einfache PHP-Sites.

---

Highlights

• 3 fertige, responsive Themes (Hero, Helpdesk Dark, Outline Card)
• AJAX-Formular: Erfolg/Fehler direkt oberhalb des Formulars, kein Redirect
• Cloudflare Turnstile: DSGVO-freundlicher Bot-Schutz, explicit render (funktioniert auch im Shadow-DOM)
• SMTP-Versand: funktioniert mit eigenem Server (wenn erlaubt) oder beliebigem externen SMTP (z. B. Yandex, Gmail Relay, Provider)
• Kein PHPMailer nötig: Falls vendor/autoload.php vorhanden ist, wird PHPMailer genutzt – sonst übernimmt der eingebaute SMTP-Client (TLS/SSL/Auth)
• Installer/Uninstaller, Log-Tabelle, Admin-Login mit Eskalations-Bans
• 1-Zeilen-Embed für jede HTML/PHP-Seite

---

Voraussetzungen

• PHP 8.0+, OpenSSL aktiviert
• MySQL 5.7+ oder MariaDB 10.3+
• Webserver (Apache/Nginx). PHP-FPM muss Schreibrechte im kc-mail/-Pfad haben.
• Ein Cloudflare-Account, um Turnstile Site Key & Secret Key zu erstellen (kostenlos).

---

Installation (5 Schritte)

1. Upload: Das Verzeichnis kc-mail/ in euer Webroot hochladen, z. B.
   /var/www/…/kc-mail
2. Installer starten: https://DEINEDOMAIN/kc-mail/ im Browser aufrufen.
   → Der Installer öffnet sich automatisch.
3. Datenbank eintragen & Admin-Benutzer anlegen.
   Nach Erfolg löscht sich install.php selbst und ihr landet im Admin.
4. Admin-Login → SMTP und Turnstile konfigurieren (siehe Abschnitte unten).
5. Embed-Snippet kopieren und in jede beliebige Seite einfügen:

<div id="contact-form"></div>
<script src="/kc-mail/assets/js/embed.js" defer
        data-mount="auto"
        data-target="#contact-form"
        data-theme="hero"
        data-send-copy-default="0"></script>

Fertig! Das Formular ist responsive und rendert Turnstile programmgesteuert (explicit).

---

Cloudflare Turnstile einrichten

Was ist Turnstile?
Ein leichtgewichtiges, DSGVO-freundliches Captcha-Äquivalent von Cloudflare. Schützt Formulare vor Bots.

Schritte in Kürze:

1. In Cloudflare unter Turnstile eine neue Site anlegen.
2. Site Key & Secret Key kopieren.
3. In KC-Mail Admin → Turnstile beide Keys eintragen und speichern.
4. Mit „Open Test“ den Live-Check öffnen – die JSON-Antwort zeigt success: true, wenn alles passt.

Hinweis: In der öffentlichen Konfiguration wird nur der Site Key bereitgestellt. Der Secret Key bleibt serverseitig.

SMTP konfigurieren

KC-Mail sendet Mails über SMTP – entweder über euren eigenen Mailserver (sofern ausgehend erlaubt) oder über einen externen SMTP-Dienst.

Felder:

• Host: z. B. smtp.yandex.com oder Host eures Providers
• Port: 587 (tls) oder 465 (ssl)
• User: i. d. R. vollständige E-Mail-Adresse
• Password: wird nicht im Klartext angezeigt; „Leave blank to keep current“
• Encryption: tls (587) oder ssl (465)
• From (Email/Name): Absender der Mails
• Recipient (To): Zieladresse für die Kontaktmails

Speichern → mit „Send Test“ eine Testmail schicken.
Fehler (Auth, Verschlüsselung, Netzwerk) werden als Meldung angezeigt. Bei vorhandenem PHPMailer wird dieser genutzt; andernfalls greift der eingebaute SMTP-Client.

Lieferbarkeit: Für eure Domain SPF/DKIM/DMARC korrekt setzen. Externe SMTP-Dienste bieten i. d. R. Anleitungen.

---

Formular einbinden (1-Zeile)

Minimaler Embed in jeder HTML/PHP-Seite:

<div id="contact-form"></div>
<script src="/kc-mail/assets/js/embed.js" defer
        data-mount="auto"
        data-target="#contact-form"
        data-theme="hero"
        data-send-copy-default="0"></script>

Optionen (data-Attribute):

• data-theme: hero | helpdeskDark | outlineCard
• data-send-copy-default: 0 oder 1 → „Email me a copy“ vorselektieren
• data-shadow: 1 (optional) → rendert im Shadow-DOM (stärker gegen globale CSS-Konflikte)

Tipp: Stellt sicher, dass die Seite <meta name="viewport" content="width=device-width, initial-scale=1"> hat – dann ist alles mobil optimiert.

---

Benutzer-Erlebnis (AJAX)

Beim Senden bleibt die Seite stehen; direkt über dem Formular erscheint die grüne Erfolgsmeldung bzw. rote Fehlermeldung.
Turnstile wird nach erfolgreichem Versand automatisch zurückgesetzt.

Optional kann der Nutzer ein Häkchen setzen: „Email me a copy“ → er erhält eine Kopie seiner Nachricht (mit Hinweis in der E-Mail: „This is a copy of your original message“).

---

Sicherheit & Datenschutz

• Admin-Login: Passwörter mit password_hash(); Eskalations-Bans (z. B. 15 → 30 Min).
• Turnstile: Secret bleibt serverseitig; die Verifikation erfolgt serverseitig via siteverify.
• Konfig-Datei: kc-mail-config.php wird beim Installern erzeugt und ist .gitignore’d.
• E-Mail-Kopien: Optional und bewusst opt-in (Checkbox).
• Shadow-DOM-Option: verhindert Konflikte mit aggressiven globalen Styles.
• Kein Redirect: Weniger Angriffsfläche für Referrer-Leaks; Feedback direkt in der Seite.

---

Fehlerbehebung (kurz)

• Turnstile wird nicht angezeigt
  → Site-Key prüfen, keine zweite Turnstile-Script-Einbindung im Host-Dokument.
• „2 Captchas“ sichtbar
  → Keine zusätzliche <script … turnstile …> im Host laden; KC-Mail rendert explicit.
• SMTP Fehler (Auth/Encrypt)
  → Port/Encryption prüfen (587/tls, 465/ssl). Testmail-Fehlertext lesen.
• Formular „zerreißt“ im Layout
  → Host-Seite mit aggressivem globalem CSS? data-shadow="1" nutzen oder die mitgelieferten „Compat Fixes“ CSS-Regeln aktiv lassen.

---

Deinstallation

/kc-mail/uninstall.php (Admin-Login erforderlich) →
Droppt alle KC-Mail-Tabellen; optional kann kc-mail-config.php gelöscht werden.

---

Lizenz & Quelle

• Lizenz: KC-Mail Free License (privat + kommerziell erlaubt; kein Resale/Rebranding; Copyright-Hinweis beibehalten)
• Autor: Kerim Candan — kerimcandan.com
• Quellcode / README / Changelog: (GitHub-Repo einfügen)

---

FAQ (Kurz)

Funktioniert das ohne PHPMailer?
Ja. Es gibt einen eingebauten SMTP-Client (TLS/SSL/Auth). Wenn PHPMailer vorhanden ist, wird er bevorzugt.

Kann ich eigene Styles nutzen?
Ja. Entweder die bestehenden Themes überschreiben oder per data-shadow="1" isoliert rendern und nur den umgebenden Container gestalten.

Kann ich mehrere Formulare auf einer Seite haben?
Ja – mehrere Targets mit jeweils eigener <div id="…"> und passender data-target-Angabe.