React (@frontmail/react)

npm install @frontmail/react

Fonctionne avec React 18 et 19, y compris Next.js (à utiliser dans des composants client).

Provider

Enveloppez votre application (ou seulement la partie qui contient des formulaires) dans FrontmailProvider. Gardez l’objet d’options stable – définissez-le au niveau du module ou avec useMemo :

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

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

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

options accepte tout ce qu’accepte init(). Vous pouvez aussi passer un client existant : <FrontmailProvider client={client}>.

FrontmailForm

Le moyen le plus rapide d’obtenir un formulaire fonctionnel – il envoie via sendForm, affiche Turnstile si vous passez une clé de site et expose l’état de l’envoi :

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'}>Envoyer</button>
          {status === 'sent' && <p>Merci !</p>}
          {status === 'held' && <p>Bien reçu – il sera transmis sous peu.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props : serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (par défaut true), onSuccess, onError, ainsi que n’importe quel attribut de <form>. Les enfants peuvent être des nœuds ou une fonction de l’état { status, error, result }.

locale (p. ex. "de") envoie l’e-mail dans cette langue du modèle (sous la forme du champ de formulaire fm_locale ; un champ fm_locale dans le formulaire est prioritaire). result.locale est la langue utilisée.

turnstileSiteKey est la clé de site de votre propre widget Turnstile (Sécurité → Protection contre les bots (Turnstile) dans le tableau de bord) – voir Cloudflare Turnstile. Omettez-la si le modèle n’exige pas de CAPTCHA.

useSendEmail

Pour les interfaces personnalisées et les formulaires contrôlés :

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'}>S’abonner</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status passe de idle → sending → sent | held | error. send() et sendForm() se résolvent avec le résultat, ou avec undefined en cas d’erreur (l’erreur est dans error) : vous n’avez donc pas besoin de try/catch. Les deux acceptent des options en second argument, p. ex. send({ email }, { locale: 'de' }).

useFrontmail

Renvoie le client du provider pour tout le reste, p. ex. getStatus :

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

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

Paramètres typés

Avec les types générés, useSendEmail('svc_…', 'tpl_contact').send({...}) vérifie le type des paramètres de ce modèle.

Projet d’exemple : examples/react.