> ## 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.

# Aggiungi un modulo di iscrizione con double opt-in

> Metti sul tuo sito un modulo di iscrizione che aggiunge gli iscritti a una lista Notifuse solo dopo che hanno confermato il loro indirizzo.

Alla fine avrai sul tuo sito un modulo che iscrive i visitatori a una lista Notifuse, invia loro un'email di conferma e li segna come attivi quando cliccano il link.

## Prima di iniziare

- Un workspace con un provider email impostato per **Email di marketing** in Impostazioni › **Integrazioni**. Le email di conferma partono da quel provider.
- L'ID del tuo workspace. È l'ID che hai scelto quando hai creato il workspace, e compare nell'URL della console dopo `/console/workspace/`.
- L'indirizzo della tua istanza Notifuse, lo stesso da cui apri la console. Gli esempi usano `https://YOUR_NOTIFUSE_HOST`.
- Una pagina del tuo sito in cui puoi aggiungere HTML e JavaScript.

### 1. Crea una lista pubblica con double opt-in

Apri **Contatti** e clicca **Nuova lista** accanto a **Liste** nella colonna di sinistra. Compila:

- **Nome**: per esempio "Newsletter".
- **ID**: ricavato dal nome, oppure clicca **Modifica** per scriverne uno tuo. Solo lettere e cifre, al massimo 32 caratteri. Il tuo modulo invia questo ID, che non si può cambiare dopo la creazione.

In **Subscription**, attiva entrambi gli interruttori:

- **Lista pubblica**: l'endpoint pubblico `/subscribe` accetta solo liste pubbliche.
- **Double opt-in**: i nuovi iscritti ricevono un'email di conferma e restano **In Attesa** finché non cliccano il suo link. Questo interruttore richiede un **Modello di conferma**.

In **Modello di conferma**, scegli un template della categoria **Opt-in**. Se non ne hai uno, clicca **Nuovo modello** nel selettore e parti dal modello **Conferma d'iscrizione**. Si apre nell'editor dei template e torna già selezionato quando lo salvi.

L'email di conferma deve contenere un link a `{{ confirm_subscription_url }}`. Il modello ha già un pulsante che punta lì. Nel tuo template, scrivi:

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

Clicca **Crea la lista**.

![Il pannello Nuova lista con Lista pubblica e Double opt-in attivi e il modello di conferma da scegliere](https://www.notifuse.com/docs/assets/screenshots/list_double_optin.png)

### 2. Aggiungi il modulo al tuo sito

Questa pagina è un esempio completo e funzionante. Sostituisci `YOUR_NOTIFUSE_HOST`, `YOUR_WORKSPACE_ID` e `YOUR_LIST_ID`, poi incollala nel tuo sito o aprila come file per provarla.

```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>
```

Il messaggio di successo chiede al visitatore di controllare la posta: su una lista con double opt-in, non è iscritto finché non clicca il link.

### 3. Come funziona la chiamata di iscrizione

Se costruisci il modulo con il tuo framework, questa è la chiamata da riprodurre. `POST /subscribe` è pubblico: non richiede API Key, quindi puoi chiamarlo dal browser senza rischi.

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

Sono obbligatori `workspace_id`, `contact` con una `email` valida e almeno una voce in `list_ids`. Gli altri campi del contatto, come `first_name` o `last_name`, sono facoltativi.

Le risposte:

| Stato | Corpo                                                | Quando                                                                                                          |
| ----- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `200` | `{"success": true}`                                  | La richiesta è stata accettata.                                                                                 |
| `400` | `{"error": "list is not public"}`                    | Una lista in `list_ids` non è pubblica.                                                                         |
| `400` | `{"error": "invalid contact: invalid email format"}` | L'email non è valida. Un campo mancante ha un messaggio tutto suo, come `workspace_id is required`.             |
| `429` | `{"error": "Too many subscription attempts. …"}`     | È stato superato un limite di frequenza. L'header `Retry-After` indica l'attesa in secondi.                     |
| `500` | `{"error": "Failed to subscribe to lists"}`          | Qualsiasi altro caso, come un ID di lista sconosciuto o un'email di conferma che non è stato possibile inviare. |

Valgono anche alcune altre regole:

- I limiti di frequenza sono 10 richieste al minuto per un indirizzo email e 50 al minuto da un indirizzo IP.
- Gli indirizzi usa e getta vengono scartati senza avviso. La risposta resta `200` e non viene creato alcun contatto.
- Una richiesta anonima non sovrascrive mai i campi di un contatto già presente nel workspace.
- Un contatto in attesa che invia di nuovo il modulo riceve di nuovo l'email di conferma. Un contatto attivo resta attivo e non riceve nulla.

Per il CORS, Notifuse imposta `Access-Control-Allow-Origin` dalla variabile d'ambiente `CORS_ALLOW_ORIGIN`, che per impostazione predefinita vale `*`. Se fai self-hosting e la restringi, aggiungi l'origine del tuo sito. La variabile accetta un elenco separato da virgole.

### 4. Cosa succede dopo l'invio

Su una lista con double opt-in, Notifuse aggiunge il visitatore alla lista come **In Attesa** e invia il modello di conferma.

Il link di quell'email apre il centro notifiche, che conferma l'iscrizione. Il contatto passa da **In Attesa** ad **Attivo** e Notifuse registra un evento `list.confirmed`.

È su quell'evento che conviene costruire. Un'automazione con il trigger **Lista** › **Confermato** raggiunge solo le persone che hanno confermato. Vedi [Crea una sequenza di benvenuto](https://www.notifuse.com/it/docs/guides/welcome-sequence.md).

I contatti che aggiungi dalla console o con una API Key saltano l'email di conferma e passano subito ad **Attivo**. Fa eccezione un contatto che si era disiscritto dalla lista: se lo iscrivi di nuovo dal modulo, dalla console o dall'API, torna **In Attesa** e riceve l'email di conferma.

## Verifica che funzioni

1. Invia il modulo con un indirizzo di cui puoi leggere la posta. Il modulo dovrebbe mostrare il messaggio che invita a controllare la posta.
2. Apri **Contatti**, trova il tuo indirizzo e aprilo. Nel suo pannello **Liste**, la lista è **In Attesa**.
3. Apri l'email di conferma e clicca il suo link. Si apre il centro notifiche, che conferma l'iscrizione.
4. Riapri il tuo contatto: ora la lista è **Attivo**. Nella scheda **Attività**, il filtro **Liste e segmenti** mostra il cambiamento.

L'email di conferma compare anche in **Log**, nella scheda **Messaggi**, con l'origine **Altro**. Vedi [Log](https://www.notifuse.com/it/docs/features/logs.md).

![La scheda di un contatto: la lista Newsletter resta In Attesa finché il contatto non conferma](https://www.notifuse.com/docs/assets/screenshots/contact_pending.png)

## Buone pratiche

- Scrivi sul modulo che invierai un'email di conferma, e fai in modo che il messaggio di successo rimandi alla casella di posta.
- Metti un link alla tua informativa sulla privacy accanto al modulo.
- Tieni corta l'email di conferma, con il link come pulsante principale. Anche la sua versione testo deve contenere `{{ confirm_subscription_url }}`.
- Mostra il campo `error` di una risposta fallita, oppure un tuo messaggio chiaro per ogni stato.
- Prova il modulo su un telefono oltre che su un computer.

## Risoluzione dei problemi

- **`400` "list is not public"**: in **Contatti**, clicca la lista nella colonna, poi **Modifica lista**, e attiva **Lista pubblica**.
- **`400` "invalid contact: invalid email format"**: l'indirizzo non è valido. Controlla il campo che il tuo modulo invia come `contact.email`.
- **`429` "Too many subscription attempts"**: hai superato il limite di 10 per email o 50 per IP al minuto, cosa facile durante i test. Aspetta il tempo indicato da `Retry-After`.
- **`500` "Failed to subscribe to lists"**: controlla l'ID della lista in `list_ids` e che sia impostato un provider email per **Email di marketing**, perché l'email di conferma viene inviata durante la richiesta.
- **`200` ma nessuna email di conferma**: cerca un invio fallito in **Log** › **Messaggi**. Un indirizzo usa e getta riceve `200` e nessuna email, ed è previsto.
- **Il browser blocca la richiesta (CORS)**: controlla che `NOTIFUSE_HOST` sia corretto e raggiungibile. Su un'istanza self-hosted, controlla che `CORS_ALLOW_ORIGIN` includa l'origine del tuo sito.
- **Il contatto resta In Attesa**: non ha ancora cliccato il link. Se invii di nuovo il modulo con lo stesso indirizzo, l'email di conferma parte di nuovo.

## Prossimi passi

- [Crea una sequenza di benvenuto](https://www.notifuse.com/it/docs/guides/welcome-sequence.md) avviata da **Confermato**.
- [Liste](https://www.notifuse.com/it/docs/features/lists.md) descrive le impostazioni delle liste e gli stati di iscrizione.
- [Centro notifiche](https://www.notifuse.com/it/docs/features/notification-center.md) è la pagina che i tuoi iscritti usano per confermare e gestire le loro iscrizioni.
