React (@frontmail/react)

npm install @frontmail/react

Funktioniert mit React 18 und 19, auch mit Next.js (in Client Components).

Provider

Umschließen Sie Ihre App (oder nur den Teil mit Formularen) mit FrontmailProvider. Halten Sie das Optionsobjekt stabil – definieren Sie es auf Modulebene oder mit useMemo:

import { FrontmailProvider } from '@frontmail/react';

const frontmailOptions = { publicKey: 'pk_4f2a…', blockHeadless: true };

export function App() {
  return (
    <FrontmailProvider options={frontmailOptions}>
      <Routes />
    </FrontmailProvider>
  );
}

options akzeptiert alles, was auch init() akzeptiert. Alternativ übergeben Sie einen vorhandenen Client: <FrontmailProvider client={client}>.

FrontmailForm

Der schnellste Weg zu einem funktionierenden Formular – es sendet über sendForm, rendert Turnstile, wenn Sie einen Site-Key übergeben, und stellt den Sendestatus bereit:

import { FrontmailForm } from '@frontmail/react';

export function ContactForm() {
  return (
    <FrontmailForm
      serviceId="svc_01J9…"
      templateId="tpl_contact"
      turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY"
      onSuccess={(result) => console.log(result.status)}
      onError={(error) => console.error(error.code)}
    >
      {({ status, error }) => (
        <>
          <input name="name" required />
          <input name="email" type="email" required />
          <textarea name="message" required />
          <button disabled={status === 'sending'}>Senden</button>
          {status === 'sent' && <p>Vielen Dank!</p>}
          {status === 'held' && <p>Erhalten – wird in Kürze zugestellt.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props: serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (Standard true), onSuccess, onError sowie beliebige <form>-Attribute. Children können Knoten oder eine Funktion des Zustands { status, error, result } sein.

locale (z. B. "de") versendet die E-Mail in dieser Sprache der Vorlage (als Formularfeld fm_locale; ein Feld fm_locale im Formular hat Vorrang). result.locale ist die verwendete Sprache.

turnstileSiteKey ist der Site-Key Ihres eigenen Turnstile-Widgets (im Dashboard unter Sicherheit → Bot-Schutz (Turnstile)) – siehe Cloudflare Turnstile. Lassen Sie ihn weg, wenn die Vorlage kein CAPTCHA verlangt.

useSendEmail

Für eigene Oberflächen und kontrollierte Formulare:

import { useState } from 'react';
import { useSendEmail } from '@frontmail/react';

function Newsletter() {
  const { send, status, error, reset } = useSendEmail('svc_01J9…', 'tpl_newsletter');
  const [email, setEmail] = useState('');

  return (
    <form onSubmit={async (e) => { e.preventDefault(); await send({ email }); }}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <button disabled={status === 'sending'}>Abonnieren</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status durchläuft idle → sending → sent | held | error. send() und sendForm() liefern das Ergebnis oder bei einem Fehler undefined (der Fehler steht in error), Sie brauchen also kein try/catch. Beide nehmen Optionen als zweites Argument, z. B. send({ email }, { locale: 'de' }).

useFrontmail

Gibt den Client aus dem Provider für alles Weitere zurück, z. B. getStatus:

import { useFrontmail } from '@frontmail/react';

const client = useFrontmail();
const status = await client.getStatus(messageId, { token });

Typisierte Parameter

Mit generierten Typen prüft useSendEmail('svc_…', 'tpl_contact').send({...}) die Parameter dieser Vorlage auf Typfehler.

Beispielprojekt: examples/react.