Vai al contenuto

Fai crescere il tuo pubblico

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:

    <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
    Il pannello Nuova lista con Lista pubblica e Double opt-in attivi e il modello di conferma da scegliere
  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.

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

    {
      "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:

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

    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.

La scheda di un contatto: la lista Newsletter resta In Attesa finché il contatto non conferma
La scheda di un contatto: la lista Newsletter resta In Attesa finché il contatto non conferma

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