> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ajouter un formulaire d'inscription avec double opt-in

> Placez sur votre site un formulaire qui ajoute les inscrits à une liste Notifuse seulement après qu'ils ont confirmé leur adresse.

Au terme de ce tutoriel, votre site aura un formulaire qui inscrit les visiteurs à une liste Notifuse, leur envoie un email de confirmation et les passe à l'état actif dès qu'ils cliquent sur le lien.

## Avant de commencer

- Un espace de travail dont un fournisseur d'email est défini pour les **Emails marketing** dans Paramètres › **Intégrations**. Les emails de confirmation partent par ce fournisseur.
- L'ID de votre espace de travail. C'est l'ID choisi à la création de l'espace de travail, et il figure dans l'URL de la console après `/console/workspace/`.
- L'adresse de votre instance Notifuse, celle sur laquelle vous ouvrez la console. Les exemples utilisent `https://YOUR_NOTIFUSE_HOST`.
- Une page de votre site où vous pouvez ajouter du HTML et du JavaScript.

### 1. Créer une liste publique avec double opt-in

Ouvrez **Contacts** et cliquez sur **Nouvelle liste** à côté de **Listes**, dans le panneau de gauche. Renseignez :

- **Nom** : par exemple « Newsletter ».
- **ID** : déduit du nom, ou cliquez sur **Modifier** pour saisir le vôtre. Lettres et chiffres uniquement, 32 caractères au plus. Votre formulaire envoie cet ID, qui ne peut plus changer après la création.

Sous **Abonnement**, activez les deux interrupteurs :

- **Liste publique** : le point d'accès public `/subscribe` n'accepte que les listes publiques.
- **Double opt-in** : les nouveaux inscrits reçoivent un email de confirmation et restent **En attente** jusqu'à ce qu'ils cliquent sur son lien. Cette option exige un **Modèle de confirmation**.

Dans **Modèle de confirmation**, choisissez un modèle de la catégorie **Opt-in**. Si vous n'en avez pas, cliquez sur **Nouveau modèle** dans le sélecteur et partez du modèle **Confirmation d'inscription**. Il s'ouvre dans l'éditeur de modèles et revient sélectionné une fois enregistré.

L'email de confirmation doit pointer vers `{{ confirm_subscription_url }}`. Le modèle fourni contient déjà un bouton qui y mène. Dans votre propre modèle, écrivez :

```html
<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>
```

Cliquez sur **Créer la liste**.

![Le panneau Nouvelle liste avec Liste publique et Double opt-in activés, et le modèle de confirmation à choisir](https://www.notifuse.com/docs/assets/screenshots/list_double_optin.png)

### 2. Ajouter le formulaire à votre site

Cette page est un exemple complet et fonctionnel. Remplacez `YOUR_NOTIFUSE_HOST`, `YOUR_WORKSPACE_ID` et `YOUR_LIST_ID`, puis collez-la dans votre site ou ouvrez-la comme fichier pour l'essayer.

```html signup-form.html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Subscribe to our newsletter</title>
  <style>
    .signup { max-width: 420px; margin: 2rem auto; font-family: system-ui, sans-serif; }
    .signup label { display: block; margin: 0.75rem 0 0.25rem; font-size: 0.9rem; }
    .signup input { width: 100%; padding: 0.6rem; border: 1px solid #ccc; border-radius: 6px; box-sizing: border-box; }
    .signup button { margin-top: 1rem; width: 100%; padding: 0.7rem; border: 0; border-radius: 6px; background: #4f46e5; color: #fff; font-size: 1rem; cursor: pointer; }
    .signup button:disabled { opacity: 0.6; cursor: wait; }
    .signup .message { margin-top: 1rem; font-size: 0.9rem; }
    .signup .message.error { color: #b91c1c; }
    .signup .message.success { color: #15803d; }
  </style>
</head>
<body>
  <form class="signup" id="signup-form" novalidate>
    <h2>Subscribe to our newsletter</h2>

    <label for="first-name">First name (optional)</label>
    <input id="first-name" name="first_name" type="text" autocomplete="given-name" />

    <label for="email">Email</label>
    <input id="email" name="email" type="email" autocomplete="email" required />

    <button type="submit">Subscribe</button>
    <p class="message" id="signup-message" role="status" aria-live="polite"></p>
  </form>

  <script>
    const NOTIFUSE_HOST = 'https://YOUR_NOTIFUSE_HOST'
    const WORKSPACE_ID = 'YOUR_WORKSPACE_ID'
    const LIST_ID = 'YOUR_LIST_ID'

    const form = document.getElementById('signup-form')
    const button = form.querySelector('button')
    const message = document.getElementById('signup-message')

    function show(text, kind) {
      message.textContent = text
      message.className = 'message ' + kind
    }

    form.addEventListener('submit', async (event) => {
      event.preventDefault()

      const email = form.email.value.trim()
      const firstName = form.first_name.value.trim()

      if (!form.email.checkValidity() || email === '') {
        show('Please enter a valid email address.', 'error')
        return
      }

      const contact = { email }
      if (firstName) contact.first_name = firstName

      button.disabled = true
      show('Subscribing…', '')

      try {
        const response = await fetch(NOTIFUSE_HOST + '/subscribe', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            workspace_id: WORKSPACE_ID,
            contact,
            list_ids: [LIST_ID]
          })
        })

        if (response.ok) {
          form.reset()
          show('Almost done: check your inbox and click the link to confirm your subscription.', 'success')
        } else if (response.status === 429) {
          show('Too many attempts. Please try again in a few minutes.', 'error')
        } else {
          const result = await response.json().catch(() => ({}))
          show(result.error || 'Something went wrong. Please try again.', 'error')
        }
      } catch (error) {
        show('Network error. Please check your connection and try again.', 'error')
      } finally {
        button.disabled = false
      }
    })
  </script>
</body>
</html>
```

Le message de réussite invite le visiteur à consulter sa boîte de réception : sur une liste en double opt-in, il n'est inscrit qu'après avoir cliqué sur le lien.

### 3. Comment fonctionne l'appel d'inscription

Si vous construisez le formulaire dans votre propre framework, voici l'appel à reproduire. `POST /subscribe` est public : il ne demande pas de clé API, vous pouvez donc l'appeler depuis le navigateur sans risque.

```json
{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "contact": {
    "email": "visitor@example.com",
    "first_name": "Ada"
  },
  "list_ids": ["YOUR_LIST_ID"]
}
```

`workspace_id`, `contact` avec un `email` valide et au moins une entrée dans `list_ids` sont obligatoires. Les autres champs du contact, comme `first_name` ou `last_name`, sont facultatifs.

Les réponses :

| Statut | Corps                                                | Quand                                                                                                  |
| ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `200`  | `{"success": true}`                                  | La requête a été acceptée.                                                                             |
| `400`  | `{"error": "list is not public"}`                    | Une liste de `list_ids` n'est pas publique.                                                            |
| `400`  | `{"error": "invalid contact: invalid email format"}` | L'email est mal formé. Un champ manquant a son propre message, par exemple `workspace_id is required`. |
| `429`  | `{"error": "Too many subscription attempts. …"}`     | Une limite de débit a été atteinte. L'en-tête `Retry-After` donne le délai d'attente en secondes.      |
| `500`  | `{"error": "Failed to subscribe to lists"}`          | Tout autre cas, par exemple un ID de liste inconnu ou un email de confirmation qui n'a pas pu partir.  |

Quelques règles s'ajoutent :

- Les limites de débit sont de 10 requêtes par minute pour une même adresse email et de 50 par minute depuis une même adresse IP.
- Les adresses jetables sont ignorées sans message. La réponse reste `200`, et aucun contact n'est créé.
- Une requête anonyme n'écrase jamais les champs d'un contact déjà présent dans l'espace de travail.
- Un contact en attente qui soumet à nouveau le formulaire reçoit à nouveau l'email de confirmation. Un contact actif reste actif et ne reçoit rien.

Pour CORS, Notifuse définit `Access-Control-Allow-Origin` à partir de la variable d'environnement `CORS_ALLOW_ORIGIN`, qui vaut `*` par défaut. Si vous auto-hébergez Notifuse et restreignez cette variable, ajoutez-y l'origine de votre site. Elle accepte une liste séparée par des virgules.

### 4. Ce qui se passe après l'envoi du formulaire

Sur une liste en double opt-in, Notifuse ajoute le visiteur à la liste à l'état **En attente** et envoie le modèle de confirmation.

Le lien de cet email ouvre le centre de notifications, qui confirme l'abonnement. Le contact passe de **En attente** à **Actif**, et Notifuse enregistre un événement `list.confirmed`.

C'est sur cet événement qu'il faut s'appuyer. Une automation dont le déclencheur est **Liste** › **Confirmé** ne touche que les personnes qui ont confirmé. Voir [Créer une séquence de bienvenue](https://www.notifuse.com/fr/docs/guides/welcome-sequence.md).

Les contacts ajoutés depuis la console ou avec une clé API ne reçoivent pas d'email de confirmation et passent directement à **Actif**. Exception : un contact qui s'était désabonné de la liste. L'inscrire à nouveau, depuis le formulaire, la console ou l'API, le remet **En attente** et lui envoie l'email de confirmation.

## Vérifier que tout fonctionne

1. Soumettez le formulaire avec une adresse que vous pouvez consulter. Le formulaire doit afficher le message qui invite à consulter la boîte de réception.
2. Ouvrez **Contacts**, trouvez votre adresse et ouvrez-la. Dans son panneau **Listes**, la liste affiche **En attente**.
3. Ouvrez l'email de confirmation et cliquez sur son lien. Le centre de notifications s'ouvre et confirme l'abonnement.
4. Rouvrez votre contact : la liste affiche maintenant **Actif**. Dans l'onglet **Activité**, le filtre **Listes et segments** montre le changement.

L'email de confirmation apparaît aussi dans **Logs**, onglet **Messages**, avec l'origine **Autre**. Voir [Logs](https://www.notifuse.com/fr/docs/features/logs.md).

![Une fiche contact : la liste Newsletter affiche En attente jusqu'à la confirmation du contact](https://www.notifuse.com/docs/assets/screenshots/contact_pending.png)

## Bonnes pratiques

- Indiquez sur le formulaire que vous enverrez un email de confirmation, et gardez un message de réussite qui renvoie vers la boîte de réception.
- Placez un lien vers votre politique de confidentialité à côté du formulaire.
- Gardez l'email de confirmation court, avec le lien comme bouton principal. Sa version texte doit elle aussi contenir `{{ confirm_subscription_url }}`.
- Affichez le champ `error` d'une réponse en échec, ou un message clair de votre cru pour chaque statut.
- Testez le formulaire sur téléphone autant que sur ordinateur.

## Dépannage

- **`400` "list is not public"** : dans **Contacts**, cliquez sur la liste dans le panneau de gauche, puis sur **Modifier la liste**, et activez **Liste publique**.
- **`400` "invalid contact: invalid email format"** : l'adresse est mal formée. Vérifiez le champ que votre formulaire envoie en tant que `contact.email`.
- **`429` "Too many subscription attempts"** : vous avez atteint la limite de 10 par email ou de 50 par IP et par minute, ce qui arrive vite pendant les tests. Attendez le délai indiqué par `Retry-After`.
- **`500` "Failed to subscribe to lists"** : vérifiez l'ID de liste dans `list_ids`, et qu'un fournisseur d'email est défini pour les **Emails marketing**, puisque l'email de confirmation part pendant la requête.
- **`200` mais aucun email de confirmation** : cherchez un envoi en échec dans **Logs** › **Messages**. Une adresse jetable reçoit `200` et aucun email, c'est voulu.
- **Le navigateur bloque la requête (CORS)** : vérifiez que `NOTIFUSE_HOST` est correct et joignable. Sur une instance auto-hébergée, vérifiez que `CORS_ALLOW_ORIGIN` contient l'origine de votre site.
- **Le contact reste En attente** : il n'a pas cliqué sur le lien. Soumettre à nouveau le formulaire avec la même adresse renvoie l'email de confirmation.

## Étapes suivantes

- [Créer une séquence de bienvenue](https://www.notifuse.com/fr/docs/guides/welcome-sequence.md) déclenchée par **Confirmé**.
- [Listes](https://www.notifuse.com/fr/docs/features/lists.md) décrit les réglages des listes et les statuts d'abonnement.
- [Centre de notifications](https://www.notifuse.com/fr/docs/features/notification-center.md) est la page où vos abonnés confirment et gèrent leurs abonnements.
