5. Formular bauen

Jetzt kommt der Teil, der auf Ihrer Website lebt: ein ganz normales HTML-Formular und ein paar Zeilen JavaScript.

Drei Werte bereitlegen

Was	Sieht so aus	Wo Sie es finden
Öffentlicher Schlüssel	pk_…	Sicherheit → Öffentlicher Schlüssel (Kopierschaltfläche) oder auf dem Tab Snippets der Vorlage
Vorlagen-ID	tpl_…	Liste Vorlagen, Spalte Vorlagen-ID, oder auf dem Tab Snippets
Dienst-ID	svc_…	Auf dem Tab Snippets – oder Sie lassen sie weg und übergeben null, dann wird Ihr Standarddienst verwendet

Am einfachsten geht es über den Tab Snippets der Vorlage Kontaktformular. Er erzeugt fertigen Code für HTML / JS, React, Vue, Svelte, Node.js und cURL – mit Ihrem Schlüssel, Ihren IDs und allen Parametern der Vorlage bereits ausgefüllt.

Die generierten Snippets rufen send() mit einem Objekt aus Werten auf. Für ein Formular ist sendForm() einfacher, das die Felder direkt aus dem <form> liest – genau das machen wir unten.

Das Formular

1. Fügen Sie das Formular in Ihre Seite ein. Die name-Attribute müssen den Parametern der Vorlage entsprechen: name, email und message sind Pflicht, phone und topic optional.

2. Setzen Sie das Turnstile-Widget innerhalb des Formulars ein. Es fügt ein verstecktes Feld cf-turnstile-response hinzu, das sendForm() mitsendet. Verwenden Sie den Site Key Ihres eigenen Turnstile-Widgets aus Schritt 4. Wenn Sie das CAPTCHA vorerst übersprungen haben, lassen Sie das Widget weg.

3. Laden Sie das SDK aus dem CDN. Es legt ein globales Objekt frontmail an.

4. Rufen Sie frontmail.init() mit Ihrem öffentlichen Schlüssel auf und beim Absenden frontmail.sendForm().

<form id="contact">
  <label>Name <input name="name" required maxlength="200" /></label>
  <label>E-Mail <input name="email" type="email" required /></label>
  <label>Nachricht <textarea name="message" required></textarea></label>

  <!-- Turnstile fügt das versteckte Feld cf-turnstile-response hinzu -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>

  <button type="submit">Senden</button>
  <p id="form-status" role="status"></p>
</form>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<script
  src="https://cdn.jsdelivr.net/npm/@frontmail/browser@0.1.0/dist/frontmail.umd.js"
  integrity="sha384-g2Rxznkz2yb/YYSdVTkXLxZFZ2Nh2+XdhPStxh0stydXFF3gYjDuyHimWIZLJDCc"
  crossorigin="anonymous"></script>
<script>
  frontmail.init({ publicKey: 'pk_…' });

  const form = document.getElementById('contact');
  const status = document.getElementById('form-status');

  form.addEventListener('submit', async (event) => {
    event.preventDefault();
    status.textContent = 'Wird gesendet …';
    try {
      // null = Ihr Standarddienst; oder fügen Sie die ID svc_… aus dem Tab Snippets ein
      const result = await frontmail.sendForm(null, 'tpl_…', form);
      // result.status ist "queued" (unterwegs) oder "held" (angenommen, wird gesendet, sobald wieder Credits da sind)
      status.textContent = 'Vielen Dank! Wir melden uns bald bei Ihnen.';
      form.reset();
    } catch (err) {
      status.textContent = 'Das hat leider nicht geklappt: ' + err.message;
    } finally {
      window.turnstile?.reset(); // ein Turnstile-Token gilt nur einmal
    }
  });
</script>

Was beim Absenden passiert:

• sendForm() schickt die Formularfelder, Ihren öffentlichen Schlüssel und das Turnstile-Token an Frontmail.
• Frontmail prüft Herkunft, CAPTCHA und Parameter und antwortet innerhalb eines Augenblicks mit { messageId, status }. Die eigentliche E-Mail wird im Hintergrund gesendet.
• Sowohl queued als auch held bedeuten Erfolg – die Nachricht ist sicher angenommen. Zeigen Sie dem Besucher in beiden Fällen ein normales Dankeschön.
• Bei einem Problem wird das Promise mit einem Fehler abgelehnt, der einen code und eine lesbare message hat, z. B. invalid_template_params, wenn die E-Mail-Adresse ungültig ist oder ein Pflichtfeld fehlt. Netzwerkfehler und kurzzeitige Serverprobleme werden automatisch wiederholt, ohne doppelt zu senden.

Achtung

Auf Ihre Website gehört nur der öffentliche Schlüssel (pk_…). Private Schlüssel (sk_…) sind für Server – bauen Sie sie nie in Frontend-Code ein. Siehe Öffentliche und private Schlüssel.

Tipp

Lieber npm? npm install @frontmail/browser und import { init, sendForm } from '@frontmail/browser' – die Funktionen sind dieselben. Weitere Optionen unter Vanilla JavaScript.

Sie verwenden ein Framework?

Die Framework-Pakete enthalten eine fertige Formularkomponente, die das Turnstile-Widget rendert und sich um den Sendestatus kümmert:

React

Vue

Svelte

React NativeMobile Apps: ein Hook zum Senden und Turnstile in einer WebView.

Weitere BeispieleVollständige Beispielprojekte für jedes SDK.