5. Costruisci il modulo

Ora la parte che vive sul tuo sito: un normale modulo HTML e qualche riga di JavaScript.

Raccogli tre valori

Cosa	Come appare	Dove trovarlo
Chiave pubblica	`pk_…`	Sicurezza → Chiave pubblica (pulsante per copiare), oppure nella scheda Snippet del modello
ID modello	`tpl_…`	Elenco Modelli, colonna ID modello, oppure nella scheda Snippet
ID servizio	`svc_…`	Nella scheda Snippet – oppure omettilo e passa `null` per usare il servizio predefinito

Il modo più semplice è la scheda Snippet del modello Modulo di contatto. Genera codice pronto per HTML / JS, React, Vue, Svelte, Node.js e cURL, con la tua chiave, gli ID e tutti i parametri del modello già compilati.

La scheda Snippet dell’editor dei modelli con la scelta del framework e il codice generato che contiene la chiave pubblica, l’ID servizio e l’ID modello

Gli snippet generati chiamano send() con un oggetto di valori. Per un modulo è più semplice usare sendForm(), che legge i campi direttamente dal <form> – ed è quello che facciamo qui sotto.

Il modulo

Aggiungi il modulo alla pagina. Gli attributi name devono corrispondere ai parametri del modello: name, email e message sono obbligatori, phone e topic facoltativi.
Metti il widget Turnstile dentro il modulo. Aggiunge un campo nascosto cf-turnstile-response che sendForm() invia insieme agli altri. Usa la chiave del sito del tuo widget Turnstile dal passaggio 4. Se per ora hai saltato il CAPTCHA, ometti il widget.
Carica l’SDK dalla CDN. Crea un oggetto globale frontmail.
Chiama frontmail.init() con la tua chiave pubblica e frontmail.sendForm() all’invio.

<form id="contact">
  <label>Nome <input name="name" required maxlength="200" /></label>
  <label>Email <input name="email" type="email" required /></label>
  <label>Messaggio <textarea name="message" required></textarea></label>

  <!-- Turnstile aggiunge il campo nascosto cf-turnstile-response -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>

  <button type="submit">Invia</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 = 'Invio in corso…';
    try {
      // null = servizio predefinito; oppure incolla l’ID svc_… dalla scheda Snippet
      const result = await frontmail.sendForm(null, 'tpl_…', form);
      // result.status è "queued" (in viaggio) o "held" (accettato, parte quando tornano i crediti)
      status.textContent = 'Grazie! Ti risponderemo presto.';
      form.reset();
    } catch (err) {
      status.textContent = 'Spiacenti, qualcosa è andato storto: ' + err.message;
    } finally {
      window.turnstile?.reset(); // un token Turnstile vale una sola volta
    }
  });
</script>

Cosa succede all’invio:

sendForm() invia a Frontmail i campi del modulo, la tua chiave pubblica e il token Turnstile.
Frontmail controlla l’origin, il CAPTCHA e i parametri e risponde in un attimo con { messageId, status }. L’email vera e propria viene inviata in background.
Sia queued sia held significano successo – il messaggio è stato accettato ed è al sicuro. In entrambi i casi mostra al visitatore un normale ringraziamento.
In caso di problemi la promise viene rifiutata con un errore che ha un code e un message leggibile, ad es. invalid_template_params quando l’indirizzo email non è valido o manca un campo obbligatorio. Gli errori di rete e i problemi temporanei del server vengono ritentati automaticamente, senza inviare due volte.

Usi un framework?

I pacchetti per i framework includono un componente modulo pronto che mostra il widget Turnstile e gestisce per te lo stato dell’invio:

React

Vue

Svelte

React NativeApp mobile: un hook per l’invio e Turnstile in una WebView.

Altri esempiProgetti di esempio completi per ogni SDK.