Setup

Questa guida copre la configurazione necessaria prima che Clerk.io possa inviare email per conto tuo.

Si applica a campagne, flow e trigger automatici come il Carrello Abbandonato. Se vuoi solo aggiungere raccomandazioni di prodotto personalizzate alle email inviate da Klaviyo, Mailchimp o un’altra piattaforma, vai invece su Embeds.

Ogni concetto qui sotto spiega cosa fa, quando è necessario e come gestirlo con Clerk.js o l’API dove serve il codice.

Scegli il percorso di configurazione giusto #

Usa la sezione che corrisponde all’attività che devi completare:

• Verifica la configurazione: Apri Setup Status per trovare configurazioni mancanti o monitoraggi interrotti.
• Invia dal tuo dominio: Configura il Sender Domain e verifica i relativi record DNS.
• Prepara i destinatari: Importa gli iscritti esistenti, poi raccogli nuovi iscritti tramite moduli, popup e checkout.
• Configura l’invio delle email: Imposta Store Personalization, Email Designs, Email Identification e Cart Tracking.

La configurazione è basata sulle attività. Ad esempio, Carrello Abbandonato richiede identificazione email e tracciamento del carrello, mentre una campagna una tantum richiede un sender domain, iscritti e un design per la mail.

Setup Status #

La scheda Setup Status ti offre una panoramica in tempo reale della configurazione email.

La trovi in Email > Configuration > Setup Status. Mostra se le parti richieste sono configurate, se il tracciamento funziona e se le email vengono inviate come previsto.

Ogni elemento ha un punto colorato. Verde significa che tutto è in ordine, rosso indica che manca qualcosa o qualcosa non funziona, arancione è un avviso che merita attenzione.

I controlli sono raggruppati in tre aree:

Configuration copre la configurazione di base. Include se l’invio email è abilitato, quale sender domain è configurato, quanti destinatari iscritti sono disponibili e se i flow attivi hanno dei design email.

On-site tracking mostra se il tracciamento dei visitatori è attivo. Indica anche quanti visitatori o carrelli sono stati collegati a un indirizzo email negli ultimi sette giorni.

Flows & sending mostra se i flow attivi sono configurati, quanti eventi dei flow sono in sospeso, quante email sono state inviate di recente e se la coda di invio è in salute.

Inizia da qui quando le email non vengono inviate come previsto. È il cruscotto della configurazione email che controlla silenziosamente l’indicatore del carburante.

Sender Domain #

Il sender domain è il dominio che Clerk.io utilizza per inviare email per il tuo negozio.

Prima che Clerk.io possa inviare da quel dominio, devi autenticarlo con i record DNS. Questi record comunicano ai server di posta in arrivo che Clerk.io è autorizzato a inviare email per conto tuo.

Senza questa prova, le email possono essere rifiutate o finite nello spam. I server di posta sono sospettosi per professione e, francamente, ne hanno viste di tutti i colori.

DNS Records #

Aggiungi i record DNS richiesti nel pannello del tuo host di dominio. Solitamente è dove gestisci il dominio, come Cloudflare, GoDaddy, Route 53 o un provider simile.

Clerk.io utilizza tre tipi di record DNS:

• SPF dichiara quali servizi possono inviare email dal tuo dominio.
• DKIM aggiunge una firma affinché i destinatari possano verificare che l’email provenga davvero da te e non sia stata modificata durante il transito.
• CNAME viene utilizzato per tracciare aperture e click nelle tue campagne.

SPF records: Un dominio può avere solo un record SPF TXT. Se ne hai già uno, unisci la direttiva, ad esempio include:mailgun.org, nel record esistente invece di crearne un secondo.

Per trovare i tuoi record, vai su Email > Configuration > Domain Setup e segui la guida per il tuo provider di hosting.

Dopo aver inserito Sender Email e Sender Name, Clerk.io genera i valori esatti dei record. Aggiungili al tuo provider di dominio, poi torna su Email > Configuration > DNS Records e clicca su Verify Now.

Subscribers #

Un subscriber è un indirizzo email che ha accettato di ricevere email di marketing.

Clerk.io ha bisogno di subscribers prima di poter inviare campagne. Un flow può identificare un visitatore e sapere esattamente cosa ha visto, ma non può comunque inviare email di marketing a chi non si è iscritto.

Configura i subscribers in due passaggi:

1. Importa i subscribers esistenti dal tuo webshop o dal fornitore di email, così porti chi ha già accettato.
2. Raccogli le nuove iscrizioni direttamente in Clerk.io attraverso i punti di iscrizione sul tuo sito web.

L’identificazione e l’iscrizione all’email sono separate. collect_email e log/email collegano un visitatore a un indirizzo email; non iscrivono quell’indirizzo alle email di marketing. Un’iscrizione sul sito deve chiamare subscriber/subscribe dopo che il visitatore ha dato consenso.

Importa esistenti #

Individua tutti i luoghi in cui sono memorizzati i subscribers esistenti. Il tuo webshop può contenere iscrizioni tramite checkout, mentre un provider email come Klaviyo o Mailchimp ha subscribers raccolti tramite form e popup.

Usa l’integrazione del webshop per importare lo stato di iscrizione dove supportato. Controlla la guida Sync Data relativa e verifica che i clienti importati includano lo stato di iscrizione corretto.

Prima, collega la tua piattaforma email in Settings > Integrations. Poi vai su Email > Configuration > Sync Subscribers e attiva l’integrazione tramite il relativo toggle.

Per trovare la guida specifica per una piattaforma email, usa il menu delle integrazioni nella sidebar e segui la guida Sync Data.

Se la tua fonte non può essere collegata direttamente, usa un CSV import o includi i subscribers nel tuo data feed usando subscribed: true nei record cliente.

Importa chi si è effettivamente iscritto, invece di segnare ogni cliente come iscritto. Controlla il risultato in Email > Subscribers prima di passare alla raccolta dal sito.

Se invierai email solo tramite Clerk.io, si consiglia di interrompere la sincronizzazione degli iscritti dal webshop o dal precedente fornitore email dopo l’import iniziale. Prima, verifica che i subscribers siano stati importati e che tutti i punti di iscrizione del sito indirizzino i nuovi iscritti direttamente a Clerk.io.

Quindi disattiva la sincronizzazione relativa e affidati alla raccolta frontend: form incorporati, popup email e opt-in dal checkout. Eviti così conflitti tra Clerk.io e l’altra piattaforma, come una successiva sincronizzazione che sovrascrive un’iscrizione o una disiscrizione.

Interrompi la sincronizzazione dello stato subscribers ma mantieni quella di prodotti, categorie, ordini o altri dati cliente se ti serve ancora. Vedi subscriber syncing.

Double opt-in #

Il double opt-in richiede ai nuovi subscribers di confermare il proprio indirizzo email prima che Clerk.io invii loro newsletter. È utile quando la tua azienda opera in Germania o in un altro mercato che richiede il consenso confermato.

Per abilitarlo, vai su Email > Configuration > Sync Subscribers, attiva Double opt-in e salva le modifiche.

Dopo che un visitatore si iscrive, Clerk.io invia una email di conferma. L’iscritto non riceve newsletter finché non clicca sul link di conferma.

L’email di conferma include un’anteprima live durante la modifica. Puoi personalizzare Subject, Heading, Message e Button text. L’email usa di default il tuo dominio verificato ed aggiunge automaticamente il link sicuro di conferma.

Lascia un campo vuoto per usare il valore sicuro di default per quella parte dell’email di conferma.

Raccogli subscribers #

Dopo l’import iniziale, collega ogni punto iscrizione in modo che i futuri iscritti arrivino a Clerk.io. Un negozio può aver bisogno di tutti e tre i metodi seguenti.

• Form incorporato: Inserisci un modulo di iscrizione HTML nel footer o in fondo alla pagina.
• Popup email: Configura un popup su my.clerk.io che appaia dopo un ritardo temporale o a una profondità di scroll scelta.
• Opt-in checkout: Collega la checkbox newsletter esistente nel checkout e il campo email a Clerk.io tramite JavaScript.

Sostituire un formulario nel footer non aggiorna popup o checkout. Controlla ogni punto iscrizione in modo indipendente, inclusi quelli che inviano ancora subscribers al tuo precedente fornitore email.

Form incorporato #

Un form incorporato permette ai visitatori di iscriversi direttamente dal sito. Installa e configura Clerk.js prima di aggiungere il modulo.

L’esempio seguente iscrive globalmente la email inserita. Inseriscilo nel footer, sulla homepage o in un’altra sezione, poi personalizza il testo e lo stile secondo il negozio.

<div class="clerk-sign-up">
   <h2 class="clerk-sign-up-headline">Iscriviti ora!</h2>
   <div class="clerk-sign-up-subtitle">Ricevi offerte personali e resta aggiornato sulle tendenze.</div>
   <div class="clerk-input-wrapper">
      <input type="email" id="clerk-add-subscriber-input" placeholder="Inserisci la tua email" aria-label="Email address" required>
      <button type="button" id="clerk-add-subscriber-btn" onclick="add_subscriber()">Iscriviti</button>
   </div>
   <div id="clerk-subscribe-message"></div>
</div>

<script>
   function add_subscriber() {
      var clerk_btn = document.getElementById("clerk-add-subscriber-btn");
      var clerk_input = document.getElementById("clerk-add-subscriber-input");
      var clerk_message = document.getElementById("clerk-subscribe-message");
      if (!clerk_input.reportValidity()) return;
      Clerk("call", "subscriber/subscribe", {
         email: clerk_input.value.trim(),
         redirect: false
      },
      function(response) {
         clerk_message.style.color = "#008001";
         clerk_message.innerText = "Iscrizione ricevuta. Se è richiesta la conferma, controlla la tua email.";
         clerk_btn.innerText = "Iscrizione ricevuta!";
         clerk_btn.style.opacity = "0.5";
         clerk_btn.disabled = true;
      },
      function(response) {
         clerk_message.style.color = "#EE360E";
         clerk_message.innerText = "Impossibile iscriversi. Riprova.";
      });
   }
</script>

<style>
   .clerk-sign-up {
      width: 50%;
      padding: 60px 0;
      max-width: 800px;
      min-width: 500px;
      margin: 40px auto;
      background-color: #FEFAF4;
   }
   .clerk-sign-up-headline {
      margin: 0 14px 14px;
      text-align: center;
   }
   .clerk-sign-up-subtitle {
      margin: 14px 14px 28px;
      text-align: center;
      color: #808080;
   }
   .clerk-input-wrapper {
      margin: 10px auto;
      text-align: center;
   }
   #clerk-add-subscriber-input {
      height: 28px;
      width: 50%;
      padding: 0 0 0 6px;
      border: 1px solid #D3D3D3;
   }
   #clerk-add-subscriber-btn {
      height: 30px;
      background-color: #008001;
      border: 1px solid #008001;
      color: white;
      cursor: pointer;
   }
   #clerk-subscribe-message {
      height: 20px;
      margin: auto;
      text-align: center;
   }
</style>

Per iscrivere a una lista specifica, aggiungi list_id. Trovi gli ID nelle liste in Email > Subscribers > Lists.

Clerk("call", "subscriber/subscribe", {
  email: "customer@example.com",
  list_id: "FSY27248"
});

Approfondisci su Subscribers.

Popup email #

Vai su Email > Popups in my.clerk.io per raccogliere subscribers tramite popup. Scegli tutti gli iscritti o una lista specifica, personalizza il design e imposta il momento di visualizzazione.

Il popup appare dopo un ritardo temporale o quando il visitatore scrolla una certa percentuale di pagina. Vedi Email Popups per dettagli.

Opt-in checkout #

Se il checkout offre una casella newsletter, collega quel controllo già presente a Clerk.io. Mantieni intatti i campi nativi e i gestori ordine del checkout; aggiungi un listener che osserva le azioni del cliente.

Il listener ha bisogno di due cose: un indirizzo valido nel campo email del checkout e la selezione consapevole della casella newsletter. Digitare l’indirizzo per un ordine, caricare una casella già selezionata o impostarla con JavaScript non deve avviare l’iscrizione.

Il flusso base è:

1. Trova il form di checkout, il campo email e la casella newsletter.
2. Registra quando il cliente seleziona attivamente la casella.
3. Chiama subscriber/subscribe quando ci sono consenso ed email valida.

Assicurati che l’installazione di Clerk.js sia caricata e configurata sul checkout. Clerk("call", ...) usa in automatico la chiave store configurata.

L’esempio sotto mostra il concetto. Sostituisci i selettori con quelli del tuo checkout e carica lo script dopo che i relativi campi esistono. Limita i selettori al form di checkout in modo che campi in footer o login non possano attivare l’iscrizione.

<script>
(function () {
  var form = document.querySelector("form.checkout-form");
  if (!form) return;

  var email = form.querySelector('input[name="email"][type="email"]');
  var newsletter = form.querySelector('input[name="newsletter"][type="checkbox"]');
  if (!email || !newsletter) return;

  var optedIn = false;

  function subscribe() {
    if (!optedIn || !newsletter.checked) return;
    if (!email.value.trim() || !email.checkValidity()) return;

    Clerk("call", "subscriber/subscribe", {
      email: email.value.trim(),
      redirect: false
    });
  }

  newsletter.addEventListener("change", function (event) {
    if (!newsletter.checked) optedIn = false;
    if (!event.isTrusted) return;
    optedIn = newsletter.checked;
    subscribe();
  });

  // Also handle customers who select the checkbox before entering an email.
  email.addEventListener("blur", function (event) {
    if (event.isTrusted) subscribe();
  });
})();
</script>

Incolla questo come un unico blocco HTML script, fuori da altri <script>. Se la piattaforma si aspetta JavaScript puro, ometti i tag di apertura e chiusura.

Per un’implementazione completa, aggiungi la gestione delle richieste duplicate e callback di successo/errore con feedback inline e possibilità di riprovare. Se il checkout sostituisce i suoi campi in modo dinamico, adatta i listener agli eventi della piattaforma o usa la delega degli eventi.

Una richiesta eseguita con successo significa che Clerk.io ha accettato l’iscrizione. Con il double opt-in, il visitatore deve comunque confermare la propria email prima di ricevere newsletter.

Questo esempio iscrive prima del completamento ordine e mantiene intatti i gestori nativi del checkout. Deselezionare la casella in seguito non annulla una richiesta già inviata né disiscrive un indirizzo già accettato.

Se l’iscrizione deve avvenire solo dopo un ordine completato, usa l’evento di ordine riuscito o il backend della piattaforma. Controlla come il webshop memorizza e sincronizza il flag newsletter in modo che sincronizzazioni successive mantengano lo stato desiderato.

Testa entrambi gli ordini dei campi, email non valide, consensi non dati o checkbox preselezionate, errori di iscrizione. Controlla il risultato in Email > Subscribers e verifica che gli errori di iscrizione non blocchino il checkout.

Usare l’API #

Usa l’API quando il tuo modulo di iscrizione o backend deve gestire direttamente i subscribers.

Chiama subscriber/subscribe per aggiungere un indirizzo email come subscriber:

curl -X POST https://api.clerk.io/v2/subscriber/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com"
  }'

Per iscrivere a una lista specifica, includi list_id:

curl -X POST https://api.clerk.io/v2/subscriber/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "list_id": "FSY27248"
  }'

Leggi il riferimento completo su docs.clerk.io/reference/subscriberssubscribe.

Disiscrizione #

La disiscrizione è il modo in cui i destinatari rinunciano alle email di marketing.

Ogni email di marketing deve includere un modo per disiscriversi. La gestione cambia a seconda che il destinatario clicchi sul link nell’email o che il backend gestisca la revoca dell’opt-in.

Se usi una piattaforma esterna — Continua a usare il link di disiscrizione della piattaforma esistente. Klaviyo, Mailchimp o la tua piattaforma si occupano del processo e tengono la lista iscritti sincronizzata.

Se invii tramite Clerk.io — Aggiungi il link di disiscrizione di Clerk.io al design. Se usi Ask Clerk.io, chiedigli di includere il link di disiscrizione e lo aggiungerà per te.

Usare i link di disiscrizione #

Per i design creati manualmente, usa il link seguente.

La variabile {{ email }} viene sostituita con l’indirizzo del destinatario all’invio. Sostituisci YOUR_PUBLIC_API_KEY con la Public Key che trovi su Developers > API Keys.

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&redirect=true">Disiscriviti</a>

Per disiscrivere solo da una lista specifica, aggiungi list_id:

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&list_id=FSY27248&redirect=true">Disiscriviti da questa lista</a>

Per reindirizzare a una pagina di conferma dopo la disiscrizione, aggiungi redirect_url:

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&redirect=true&redirect_url=https://yoursite.com/unsubscribed">Disiscriviti</a>

Usare l’API #

Usa subscriber/unsubscribe per disiscrivere un indirizzo email in modo programmato.

Utile per pagine personalizzate di disiscrizione o flussi backend.

curl -X POST https://api.clerk.io/v2/subscriber/unsubscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com"
  }'

Questo disiscrive globalmente. Per disiscrivere solo da una lista specifica, aggiungi list_id:

curl -X POST https://api.clerk.io/v2/subscriber/unsubscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "list_id": "FSY27248"
  }'

Leggi il riferimento completo su docs.clerk.io/reference/subscribersunsubscribe.

Store Personalization #

La personalizzazione del negozio controlla i brand asset predefiniti che Clerk.io usa nei design email.

Vai su Email > Configuration > Personalization per impostare il logo del negozio. Puoi caricare manualmente un’immagine o usare Auto-detect from website per far sì che Clerk.io la individui dal sito.

Il logo impostato qui viene usato come predefinito nei design email realizzati con Clerk.io. Se crei i design manualmente, puoi comunque usare la URL del logo direttamente nel markup del template.

Email Designs #

Un design email è il template visivo che Clerk.io usa per comporre la mail da inviare.

Ogni campagna e ogni flow automatico necessita di un design. Il design controlla layout, colori, testi, blocchi prodotti, link disiscrizione e tutto ciò che vede il destinatario.

Con Ask Clerk.io #

Il modo più semplice per creare un design è con Ask Clerk.io Design Studio.

Descrivi cosa vuoi con linguaggio naturale: layout, colori, quali prodotti mostrare, come devono apparire i prezzi in saldo. Design Studio genera un’anteprima inline nella chat, pronta da rivedere e affinare.

Puoi anche fornirgli il link del tuo sito o allegare uno screenshot. Lo userà come riferimento visivo, molto più veloce che spiegare la tua sfumatura di verde come se fosse un sospetto davanti alla polizia.

Approfondisci con la guida Design Studio.

Con MJML #

Usa l’editor MJML integrato se vuoi controllo completo sul markup.

MJML compila in HTML che rende in maniera coerente su Gmail, Outlook, Apple Mail e altri client. Vedi la guida MJML Designs per schema completo ed esempi.

Tutti i design email in Clerk.io sono responsive. Si adattano automaticamente a desktop, tablet e mobile.

Immagini statiche #

Usa la Media Library per immagini statiche come banner, loghi o intestazioni stagionali.

Le immagini caricate qui ottengono un riferimento tipo {{ media.your-image }}, da usare in qualsiasi design.

Puoi anche allegare direttamente un’immagine in Ask Clerk.io e chiedergli di caricarla e inserirla nel design.

Email Identification #

L’identificazione email collega la sessione di un visitatore a un indirizzo email.

È richiesta per flow automatici come recupero navigazione, serie di benvenuto e Carrello Abbandonato. Senza di essa, Clerk.io può sapere cosa ha fatto un visitatore, ma non a chi inviare l’email.

Ogni visitatore del sito riceve un visitor ID. Inizialmente l’ID è anonimo. L’identificazione email lo collega a un indirizzo quando il visitatore scrive la mail o rientra già loggato.

Con Clerk.js #

Usa collect_email perché Clerk.js rilevi automaticamente i campi email.

Se usi uno dei plugin installabili di Clerk.io, attiva collect_email dalle impostazioni del plugin. Valido per DanDomain Classic, Magento 1, Magento 2, PrestaShop, Shopware 6, VTEX e WooCommerce.

Per altre integrazioni, abilitalo nel config di Clerk.js:

Clerk('config', {
  key: 'your-public-api-key',
  collect_email: true
});

Clerk.js monitorerà i campi input email e registrerà l’indirizzo quando un visitatore lo inserisce.

Funziona per campi checkout, iscrizioni newsletter, login e altri <input type="email">.

Questo identifica il visitatore; non lo iscrive alle email marketing. Per raccogliere l’opt-in dal checkout, usa il checkout listener per chiamare separatamente subscriber/subscribe.

Se il cliente è già loggato, registra la mail una volta per sessione con Clerk('call', 'log/email').

if (!sessionStorage.getItem('clerk_email_logged')) {
  Clerk('call', 'log/email', {
    email: 'CUSTOMER_EMAIL'
  });
  sessionStorage.setItem('clerk_email_logged', '1');
}

Sostituisci CUSTOMER_EMAIL con la vera email prelevata dalla piattaforma. Esegui lo script solo se hai già la mail.

Con l’API #

Usa log/email per associare un visitor ID a un indirizzo email.

Chiamalo una volta per sessione quando l’email diventa disponibile. Vale per i login e per chi torna già loggato.

curl -X POST https://api.clerk.io/v2/log/email \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "visitor": "SESSION_VISITOR_ID"
  }'

Sostituisci SESSION_VISITOR_ID con il visitor ID attuale della sessione.

Se usi l’API, sei responsabile di generare e mantenere il visitor ID. Consulta la guida Tracking per dettagli.

Cart Tracking #

Il tracciamento del carrello informa Clerk.io su cosa c’è attualmente nel carrello di un visitatore.

È necessario per le email Carrello Abbandonato. Se il visitatore esce senza acquistare, Clerk.io può inviare il contenuto solo se il carrello è stato tracciato.

Richiama il tracciamento ogni volta che il carrello cambia: quando aggiungi o rimuovi prodotti, o aggiorni il carrello.

Con Clerk.js #

Se usi i plugin Magento 1, Magento 2, PrestaShop o WooCommerce, il tracciamento del carrello è automatico.

Per altre situazioni, notifica a Clerk.io il contenuto attuale del carrello con il metodo set. Ogni chiamata è legata alla sessione visitatore.

Clerk('cart', 'set', [1234, 5678, 42]);

Approfondisci in Shopping Cart integration.

Con l’API #

Usa log/cart/update per impostare lo stato attuale del carrello.

Chiamalo ogni volta che il carrello cambia, passando l’intera lista prodotti nel carrello.

curl -X POST https://api.clerk.io/v2/log/cart/update \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "visitor": "SESSION_VISITOR_ID",
    "products": [
      {"id": 1234, "quantity": 2},
      {"id": 5678, "quantity": 1}
    ]
  }'

Puoi anche passare email invece di, o insieme a, visitor se conosci già l’indirizzo email.