React (@frontmail/react)

npm install @frontmail/react

Funziona con React 18 e 19, incluso Next.js (usalo nei client component).

Provider

Avvolgi la tua app (o solo la parte con i moduli) in FrontmailProvider. Mantieni stabile l’oggetto delle opzioni – definiscilo a livello di modulo o con useMemo:

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

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

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

options accetta tutto ciò che accetta init(). In alternativa, passa un client esistente: <FrontmailProvider client={client}>.

FrontmailForm

Il modo più rapido per avere un modulo funzionante: invia tramite sendForm, mostra Turnstile quando passi una chiave del sito ed espone lo stato dell’invio:

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'}>Invia</button>
          {status === 'sent' && <p>Grazie!</p>}
          {status === 'held' && <p>Ricevuto – verrà recapitato a breve.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props: serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (predefinito true), onSuccess, onError, più qualsiasi attributo di <form>. I children possono essere nodi o una funzione dello stato { status, error, result }.

locale (ad es. "de") invia l’email in quella lingua del modello (come campo del modulo fm_locale; un campo fm_locale dentro il modulo ha la precedenza). result.locale è la lingua usata.

turnstileSiteKey è la chiave del sito del tuo widget Turnstile (Sicurezza → Protezione dai bot (Turnstile) nella dashboard) – vedi Cloudflare Turnstile. Omettila se il modello non richiede un CAPTCHA.

useSendEmail

Per UI personalizzate e moduli controllati:

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

status è idle → sending → sent | held | error. send() e sendForm() si risolvono con il risultato oppure con undefined in caso di errore (l’errore è in error), quindi non ti serve try/catch. Entrambe accettano le opzioni come secondo argomento, ad es. send({ email }, { locale: 'de' }).

useFrontmail

Restituisce il client del provider per tutto il resto, ad es. getStatus:

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

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

Parametri tipizzati

Con i tipi generati, useSendEmail('svc_…', 'tpl_contact').send({...}) controlla i tipi dei parametri di quel modello.

Progetto di esempio: examples/react.