5. Créer le formulaire

Passons à la partie qui vit sur votre site web : un formulaire HTML ordinaire et quelques lignes de JavaScript.

Réunir trois valeurs

Quoi	Aspect	Où la trouver
Clé publique	pk_…	Sécurité → Clé publique (bouton de copie), ou dans l’onglet Extraits de code du modèle
ID du modèle	tpl_…	Liste Modèles, colonne ID du modèle, ou dans l’onglet Extraits de code
ID du service	svc_…	Dans l’onglet Extraits de code – ou omettez-le et passez null pour utiliser votre service par défaut

Le plus simple est l’onglet Extraits de code du modèle Formulaire de contact. Il génère du code prêt à l’emploi pour HTML / JS, React, Vue, Svelte, Node.js et cURL, avec votre clé, vos identifiants et tous les paramètres du modèle déjà renseignés.

Les extraits générés appellent send() avec un objet de valeurs. Pour un formulaire, il est plus simple d’utiliser sendForm(), qui lit les champs directement depuis le <form> – c’est ce que nous faisons ci-dessous.

Le formulaire

1. Ajoutez le formulaire à votre page. Les attributs name doivent correspondre aux paramètres du modèle : name, email et message sont obligatoires, phone et topic facultatifs.

2. Placez le widget Turnstile à l’intérieur du formulaire. Il ajoute un champ caché cf-turnstile-response que sendForm() transmet avec le reste. Utilisez la clé de site de votre propre widget Turnstile de l’étape 4. Si vous avez laissé le CAPTCHA de côté pour l’instant, omettez le widget.

3. Chargez le SDK depuis le CDN. Il crée un objet global frontmail.

4. Appelez frontmail.init() avec votre clé publique, et frontmail.sendForm() à la soumission.

<form id="contact">
  <label>Nom <input name="name" required maxlength="200" /></label>
  <label>E-mail <input name="email" type="email" required /></label>
  <label>Message <textarea name="message" required></textarea></label>

  <!-- Turnstile ajoute le champ caché cf-turnstile-response -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>

  <button type="submit">Envoyer</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 = 'Envoi en cours…';
    try {
      // null = votre service par défaut ; ou collez l’ID svc_… de l’onglet Extraits de code
      const result = await frontmail.sendForm(null, 'tpl_…', form);
      // result.status vaut "queued" (en route) ou "held" (accepté, envoyé dès le retour des crédits)
      status.textContent = 'Merci ! Nous vous répondrons très vite.';
      form.reset();
    } catch (err) {
      status.textContent = 'Désolé, l’envoi a échoué : ' + err.message;
    } finally {
      window.turnstile?.reset(); // un jeton Turnstile ne sert qu’une fois
    }
  });
</script>

Ce qui se passe à la soumission :

• sendForm() envoie à Frontmail les champs du formulaire, votre clé publique et le jeton Turnstile.
• Frontmail vérifie l’origine, le CAPTCHA et les paramètres, et répond en un instant avec { messageId, status }. L’e-mail lui-même est envoyé en arrière-plan.
• queued comme held signifient succès – le message est accepté en toute sécurité. Affichez au visiteur un remerciement normal dans les deux cas.
• En cas de problème, la promesse est rejetée avec une erreur qui possède un code et un message lisible, p. ex. invalid_template_params quand l’adresse e-mail est invalide ou qu’un champ obligatoire manque. Les erreurs réseau et les incidents serveur passagers sont retentés automatiquement, sans double envoi.

Attention

Seule la clé publique (pk_…) a sa place sur votre site web. Les clés privées (sk_…) sont destinées aux serveurs – ne les mettez jamais dans du code frontend. Voir Clés publiques et privées.

Astuce

Vous préférez npm ? npm install @frontmail/browser et import { init, sendForm } from '@frontmail/browser' – les fonctions sont les mêmes. Plus d’options dans JavaScript natif.

Vous utilisez un framework ?

Les paquets pour frameworks incluent un composant de formulaire prêt à l’emploi qui affiche le widget Turnstile et gère l’état d’envoi pour vous :

React

Vue

Svelte

React NativeApplications mobiles : un hook d’envoi et Turnstile dans une WebView.

Plus d’exemplesDes projets d’exemple complets pour chaque SDK.