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.
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
/subscribeaccetta 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 Aggiungi il modulo al tuo sito
Questa pagina è un esempio completo e funzionante. Sostituisci
YOUR_NOTIFUSE_HOST,YOUR_WORKSPACE_IDeYOUR_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.
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,contactcon unaemailvalida e almeno una voce inlist_ids. Gli altri campi del contatto, comefirst_nameolast_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_idsnon è 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-Afterindica 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
200e 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-Origindalla variabile d’ambienteCORS_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.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
- Invia il modulo con un indirizzo di cui puoi leggere la posta. Il modulo dovrebbe mostrare il messaggio che invita a controllare la posta.
- Apri Contatti, trova il tuo indirizzo e aprilo. Nel suo pannello Liste, la lista è In Attesa.
- Apri l’email di conferma e clicca il suo link. Si apre il centro notifiche, che conferma l’iscrizione.
- 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.
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
errordi 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 comecontact.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 daRetry-After.500“Failed to subscribe to lists”: controlla l’ID della lista inlist_idse che sia impostato un provider email per Email di marketing, perché l’email di conferma viene inviata durante la richiesta.200ma nessuna email di conferma: cerca un invio fallito in Log › Messaggi. Un indirizzo usa e getta riceve200e nessuna email, ed è previsto.- Il browser blocca la richiesta (CORS): controlla che
NOTIFUSE_HOSTsia corretto e raggiungibile. Su un’istanza self-hosted, controlla cheCORS_ALLOW_ORIGINincluda 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 avviata da Confermato.
- Liste descrive le impostazioni delle liste e gli stati di iscrizione.
- Centro notifiche è la pagina che i tuoi iscritti usano per confermare e gestire le loro iscrizioni.
