Vai al contenuto

Integrazioni

Zapier

Collega Notifuse a Zapier: invia le tue email transazionali da qualsiasi app, avvia Zap dagli eventi di contatti, liste e segmenti, aggiungi contatti o iscrivili a una lista.

Zapier collega Notifuse a migliaia di altre applicazioni senza scrivere codice. Notifuse offre sia trigger sia azioni:

  • I trigger avviano uno Zap quando succede qualcosa in Notifuse: un contatto viene creato o aggiornato, qualcuno si iscrive a una lista o si disiscrive, un contatto entra in un segmento o ne esce. Notifuse invia ogni evento a Zapier nel momento in cui avviene, quindi Zapier non deve interrogarlo a intervalli.
  • Le azioni permettono a un’altra app di agire in Notifuse. La principale è l’invio: uno Zap sceglie una delle tue notifiche transazionali e Notifuse la invia con il tuo template, il tuo mittente e il tuo provider email. Le azioni possono anche creare o aggiornare un contatto, oppure iscriverlo a una lista.

Prima di iniziare

Ti servono una API Key e il tuo URL API di Notifuse. Collegando Zapier da Impostazioni → Integrazioni li ottieni entrambi.

Ti serve anche HTTPS: Zapier chiama solo endpoint serviti in HTTPS con un certificato emesso da un’autorità di certificazione pubblica, e un’istanza self-hosted deve essere raggiungibile da internet.

Passo 1: collega Zapier

Apri Impostazioni → Integrazioni nel workspace in cui vuoi che Zapier lavori. Clicca Aggiungi integrazione, poi scegli Zapier sotto App collegate. Solo il proprietario del workspace può collegarlo.

L’unico campo è un’etichetta. Dà un nome al collegamento in Notifuse e nient’altro dipende da essa. Un workspace può avere più collegamenti Zapier, quindi usa l’etichetta per indicare a cosa serve ciascuno. Il valore predefinito, “Zapier”, va bene se te ne serve uno solo.

Clicca Collega Zapier. Notifuse crea una API Key con i soli permessi che servono a questa integrazione: Transazionale, Subscription Webhook, Contatti e Liste in lettura e scrittura, più Segmenti in lettura. Non devi spuntare nulla.

Prima di collegare, guarda bene Transazionale. Permette a uno Zap di inviare, ma anche di creare, modificare ed eliminare notifiche transazionali, testare template e provider e inoltrare posta tramite il bridge SMTP. Un token trapelato potrebbe inviare posta tramite il tuo provider, a tue spese e a danno della tua reputazione di invio, anche se non può leggere la cronologia dei messaggi. Se un collegamento Zapier non deve inviare, restringi i permessi della chiave (vedi Gestire il collegamento in seguito).

Il token viene mostrato una sola volta, nel pannello che sostituisce il modulo. Copialo prima di premere Fatto: nessuna schermata di Notifuse può mostrarlo di nuovo. Lo stesso pannello riporta l’URL API per il passo 2, con un pulsante per copiarlo.

Nota

Notifuse ricava l’indirizzo della chiave dalla tua etichetta. Lo costruisce come zapier-<label>-<random>: mette l’etichetta in minuscolo e sostituisce con un trattino tutto ciò che non è una lettera, una cifra o un trattino basso. Se hai lasciato il valore predefinito, l’indirizzo è zapier-<random>. Gli indirizzi delle API Key sono unici in tutta l’installazione di Notifuse, non per workspace. La parte casuale permette a due workspace di collegare entrambi uno Zapier “Marketing” senza conflitti, e non devi mai cercare un nome libero. Il pannello di collegamento mostra l’indirizzo ottenuto, e lo mostra anche la scheda del collegamento in seguito: è così che abbini una scheda alla sua riga in Impostazioni → Team e API Key.

Nota

In alternativa, crea la chiave a mano in Impostazioni → Team e API Key → Nuova chiave, dove assegni tu i permessi (la tabella qui sotto indica cosa spuntare). Una chiave così è una normale API Key non legata a nessun collegamento: non compare alcuna scheda in Impostazioni → Integrazioni, e solo eliminando la sua riga da Impostazioni → Team e API Key la revochi. Dai a Zapier una chiave tutta sua invece di riutilizzarne una. Amministratori e API Key contiene il riferimento completo dei permessi.

Cosa può fare la chiave

Collegando Zapier tutti questi permessi vengono assegnati per te. La tabella mostra cosa può raggiungere il token nelle mani di Zapier, e cosa spuntare se crei la chiave a mano in Impostazioni → Team e API Key o se ne restringi una in seguito.

Cosa vuoi usarePermessi necessari alla chiave
Il collegamento dell’account, la scelta del workspace e le etichette dei campi personalizzati in un’azioneNessuno: qualsiasi chiave può farlo
Qualsiasi trigger (attivare e disattivare uno Zap)Subscription Webhook in lettura e scrittura
I dati di esempio di qualsiasi trigger (quelli che Zapier ti mostra mentre costruisci uno Zap)Contatti in lettura
Trigger sui contattiContatti in lettura
Trigger sulle liste e scelta della listaListe in lettura e Contatti in lettura
Trigger sui segmenti e scelta del segmentoSegmenti in lettura e Contatti in lettura
L’azione Send Transactional Email e la scelta della notificaTransazionale in lettura e scrittura
Salvataggio sul contatto dei campi compilati in un invioContatti in scrittura. Senza questo permesso l’invio funziona lo stesso, ma viene registrato solo l’indirizzo
CC o BCC in un invioAnche Contatti in lettura, perché l’oggetto viene renderizzato con i dati del contatto
L’azione Create or Update ContactContatti in scrittura
L’azione Subscribe Contact to ListListe in lettura e scrittura

Nota

La lettura riempie i menu a tendina, la scrittura esegue il passo. Ogni menu di scelta legge gli elementi tra cui scegli, quindi con la sola scrittura un’azione non si può configurare. Con Liste in scrittura ma senza Liste in lettura, il passo Subscribe Contact to List non si può salvare: la scelta della lista restituisce un errore di permessi, e la lista è un campo obbligatorio.

Ogni trigger richiede Contatti in lettura, non solo quelli sui contatti: i record di esempio che Zapier mostra mentre costruisci uno Zap provengono dai tuoi contatti, qualunque trigger tu abbia scelto. Una chiave senza questo permesso riempie i menu a tendina ma fallisce su Test trigger.

Attenzione

La scrittura su Transazionale, Subscription Webhook e Liste va più lontano di quanto suggeriscano i nomi. La scrittura su Transazionale invia posta tramite il tuo provider e permette anche di modificare ed eliminare le notifiche transazionali, testare i provider e usare il bridge SMTP. Un trigger si iscrive agli eventi e fa recapitare a Zapier i loro payload. Iscrivere un indirizzo a una lista crea o sovrascrive la scheda di quel contatto, e lo stesso vale per un invio a quell’indirizzo. Proteggi questa chiave come proteggeresti il tuo database di contatti e le tue credenziali di invio.

Passo 2: il tuo URL API

Il modulo di collegamento di Zapier ha un campo API URL. Il pannello Collega Zapier ne riporta il valore, prima del collegamento e, dopo, accanto al token.

  • Notifuse Cloud: il campo arriva già compilato con l’API Cloud, https://v3.notifuse.com. Lascialo così.
  • Self-hosted: incolla l’indirizzo riportato dal pannello. È l’indirizzo da cui apri la console di Notifuse, solo schema e dominio, senza nulla dopo il dominio e senza barra finale. Non svuotare il campo: un URL API vuoto indica Notifuse Cloud, non “questa istanza”.

La tua istanza deve essere raggiungibile da internet, in HTTPS, con un certificato emesso da un’autorità di certificazione pubblica. Let’s Encrypt va bene.

Attenzione

http:// semplice, certificati autofirmati e autorità di certificazione interne non sono supportati, e nemmeno un’istanza raggiungibile solo dall’interno della tua rete. Zapier richiede HTTPS con un certificato riconosciuto pubblicamente. Se la tua istanza è dietro un firewall, tieni presente che Zapier pubblica un insieme fisso di indirizzi IP in uscita da autorizzare solo nei suoi piani a pagamento.

Passo 3: collega il tuo workspace

In Zapier, crea uno Zap, cerca Notifuse e scegli un trigger o un’azione. Quando Zapier ti chiede di collegare un account, incolla la API Key e, se usi un’istanza self-hosted, il tuo URL API.

Ogni trigger e azione di Notifuse ti chiede poi quale workspace usare, da un menu a tendina.

Nota

Un collegamento Zapier copre un solo workspace. Una API Key di Notifuse appartiene a un solo workspace, quindi il menu a tendina offre solo quello e lo seleziona per te. Se hai più workspace, collega Zapier da Impostazioni → Integrazioni in ciascuno e aggiungi in Zapier un collegamento separato per ognuno. Zapier etichetta i collegamenti con il nome del workspace e l’host, quindi è facile distinguerli.

Gestire il collegamento in seguito

Il collegamento compare come scheda in Impostazioni → Integrazioni, con la tua etichetta, l’indirizzo della chiave creata e la data del collegamento. Puoi rinominarlo o eliminarlo, con effetti molto diversi:

  • Rinominarlo cambia solo l’etichetta sulla scheda. La chiave mantiene l’indirizzo con cui è stata creata, quindi nome e indirizzo possono poi differire, ed è per questo che la scheda li mostra entrambi. In Zapier non devi reinserire nulla.
  • Eliminarlo revoca la chiave. Ogni Zap che usa quella chiave smette di funzionare appena confermi. Una chiave revocata non si può ripristinare, e ricollegando ne crei una nuova da incollare in Zapier. Anche eliminare il workspace revoca le sue chiavi Zapier allo stesso modo.

I permessi di una chiave si modificano in Impostazioni → Team e API Key. Lì puoi ampliare o restringere la chiave Zapier: la modifica vale dalla sua richiesta successiva e il token non cambia, quindi in Zapier non c’è nulla da reinserire. Eliminare lì la riga della chiave la revoca, come eliminare la scheda, ma lascia la scheda collegata a una chiave che non esiste più.

Trigger

TriggerSi attiva quando
New ContactUn contatto viene aggiunto al workspace
Updated ContactI dati di un contatto esistente cambiano
New List SubscriberUn contatto diventa iscritto attivo di una lista
Contact Unsubscribed from ListUn contatto si disiscrive da una lista
Contact Joined SegmentUn contatto inizia a corrispondere a un segmento
Contact Left SegmentUn contatto smette di corrispondere a un segmento

I trigger su liste e segmenti ti permettono di scegliere una lista o un segmento specifico. Scegline uno: Notifuse invierà a Zapier solo gli eventi di quella lista o di quel segmento invece di quelli di tutte le liste del workspace, il che riduce le attività consumate dal tuo Zap e il carico sulla tua istanza.

New List Subscriber copre tre modi di entrare

Un contatto può diventare iscritto attivo di una lista in tre modi, e solo il primo è una nuova iscrizione:

  • Si iscrive per la prima volta.
  • Conferma un’iscrizione in double opt-in che era in attesa di conferma.
  • Si iscrive di nuovo dopo essersi disiscritto, aver generato un bounce o aver segnalato spam.

New List Subscriber si attiva in tutti e tre i casi. Un contatto che ritorna non produce mai un evento di prima iscrizione, quindi uno Zap che osservasse solo quell’evento perderebbe ogni iscritto di ritorno senza alcun errore. Ogni esecuzione porta l’evento specifico, così in Zapier puoi creare percorsi diversi per i nuovi iscritti e per quelli di ritorno.

Updated Contact ignora i salvataggi senza modifiche

Updated Contact si attiva solo quando i dati di un contatto cambiano. Salvare un contatto senza modifiche, o un processo in background che tocca un record, non produce alcun evento, quindi gli aggiornamenti interni di routine non avviano i tuoi Zap.

Zapier gestisce le proprie subscription webhook

Attivare uno Zap di Notifuse crea una subscription in Impostazioni → Webhook, indicata come creata da Zapier. Disattivare lo Zap la rimuove.

Attenzione

Non eliminare a mano una subscription webhook creata da Zapier. Lo Zap che la possiede smette di ricevere eventi e non ricrea la subscription da solo: devi disattivare e riattivare lo Zap in Zapier, cosa che funziona anche se la subscription non c’è più. Elimina invece lo Zap e lascia che faccia pulizia.

Una consegna fallita viene ritentata, quindi uno Zap può a volte essere eseguito due volte per lo stesso evento. Se il tuo Zap fa qualcosa che non deve succedere due volte, come addebitare una carta o inviare un messaggio, aggiungi un filtro Zapier o un passo di deduplicazione.

Azioni

AzioneCosa fa
Send Transactional EmailInvia una delle tue notifiche transazionali a un contatto, compilando le variabili del template con i dati dello Zap
Create or Update ContactCrea il contatto se l’indirizzo email è nuovo, altrimenti lo aggiorna
Subscribe Contact to ListCrea o aggiorna il contatto e lo iscrive alle liste che scegli, in un solo passo

Tutte e tre le azioni cercano il contatto tramite l’indirizzo email, quindi rieseguirle con lo stesso indirizzo aggiorna lo stesso contatto invece di crearne un duplicato.

I campi personalizzati dei contatti compaiono in queste azioni con le etichette che hai dato loro. Assegnale prima in Impostazioni → Campi personalizzati: i campi senza etichetta sono nascosti, quindi un campo che manca in Zapier di solito non ha ancora un’etichetta.

Inviare significa scegliere, non comporre

Send Transactional Email non contiene l’email stessa. Template, mittente, tracciamento e gestione della disiscrizione restano in Notifuse. Lo Zap sceglie quale notifica inviare, chi la riceve e i valori con cui il template viene renderizzato.

Nel passo, scegli una Notification dal menu a tendina, mappa un’Email per il destinatario e compila Template Data con una riga per ogni {{ variable }} usata dal tuo template. Una variabile che non fornisci viene renderizzata vuota senza errori, quindi se un’email arriva con un buco, controlla prima che il nome di quella riga corrisponda al template.

Due dettagli su Template Data:

  • I valori arrivano come testo. Stampare un valore funziona. Un confronto come {% if total > 100 %} non corrisponderà, perché confronta con il testo "120", non con il numero.
  • contact e notification_center_url sono impostati da Notifuse e non si possono sovrascrivere dallo Zap. Le righe con questi nomi vengono ignorate.

Le notifiche senza canale email non compaiono nel menu a tendina, perché inviarle potrebbe solo fallire.

L’invio scrive anche il contatto

Un invio crea il contatto se l’indirizzo è nuovo, così puoi scrivere a qualcuno al suo primo ordine senza un passo separato.

Ogni campo del contatto che compili sovrascrive il valore salvato. Se mappi First Name da una fonte che a volte è vuota, quelle esecuzioni svuotano il nome salvato. Un campo lasciato vuoto nello Zap non tocca il valore salvato, mentre un campo mappato ha la precedenza. Per inviare e basta, compila solo l’indirizzo email.

Usa Message External ID per tutto ciò che non deve partire due volte

Zapier ritenta un passo fallito, e un nuovo tentativo esegue di nuovo l’intera azione. Una notifica di spedizione duplicata è un piccolo fastidio, mentre un reset della password o una conferma d’ordine duplicati sono un problema vero.

Compila Message External ID con un valore stabile preso dal trigger, come un numero d’ordine, l’id di una fattura o l’id del record di origine. Un invio con un valore che Notifuse ha già visto restituisce il messaggio originale invece di inviare una seconda email. Se lo lasci vuoto, ogni esecuzione invia.

Il passo non può dirti quale dei due casi si è verificato: un invio deduplicato e un invio nuovo appaiono identici in Zap History, entrambi riusciti con lo stesso id di messaggio.

Attenzione

Testare il passo invia un’email vera. Il pulsante Test action di Zapier invia davvero, come ogni esecuzione reale, e non fa una simulazione. Mentre costruisci lo Zap, usa un indirizzo che ti appartiene.

Lo stato dell’iscrizione non è sempre attivo

Subscribe Contact to List restituisce lo stato risultante per ogni lista. Non è sempre active, e questo può sembrare un bug:

  • Un contatto che si era disiscritto torna come pending, non active, e riceve l’email di conferma della lista. Notifuse impone il double opt-in a chiunque si sia già disiscritto in passato, qualunque siano le impostazioni della lista. Questa regola di conformità non si può disattivare. Lo Zap non è fallito: il contatto deve confermare prima di ricevere qualcosa. Una lista senza template di double opt-in non ha un’email di conferma da inviare, quindi quei contatti restano pending a tempo indeterminato. Configurane uno prima di puntare uno Zap di riattivazione su una lista.
  • Un contatto del tutto nuovo arriva active anche su una lista in double opt-in, e non riceve alcuna email di conferma, perché la richiesta proviene da una API Key autenticata e non da un modulo di iscrizione pubblico.

Attenzione

Prima di puntare uno Zap di acquisizione lead su una lista in double opt-in, tieni presente che i nuovi indirizzi saltano il passo di conferma. Aggiungi persone a una lista tramite Zapier solo con il loro consenso, come faresti importando un file.

In altri tre casi l’azione segnala un successo senza aggiungere un nuovo iscritto. Nel risultato non appaiono tutti allo stesso modo, e la differenza conta se filtri sul risultato:

  • Un indirizzo che ha generato un bounce o segnalato spam non viene reiscritto. Torna con il suo stato definitivo, bounced o complained, che un passo Filter basato su Status vede.
  • Un contatto già attivo sulla lista resta com’è. Rieseguire lo Zap non cambia nulla, e l’iscrizione torna come active.
  • Un indirizzo di un dominio email usa e getta viene scartato in silenzio. È l’unico caso in cui non c’è nulla da segnalare: il passo riesce senza alcuna iscrizione e con Status vuoto. Non vengono scritti né l’iscrizione né il contatto.

Nota

Filtra sul valore dello stato, non sulla sua presenza. Continue if Status exists lascia passare un indirizzo in bounce come uno attivo, perché entrambi hanno uno stato, e blocca solo il caso del dominio usa e getta. Per verificare che “il contatto ora è iscritto”, controlla che Status sia active, oppure che Memberships non sia vuoto se iscrivi a più liste alla volta.

Risoluzione dei problemi

Il test del collegamento fallisce

  • Controlla l’URL API: deve iniziare con https:// e non avere alcun percorso dopo il dominio. Il pannello di collegamento ha riportato il valore esatto, e riaprendo la scheda vedi solo l’etichetta. Se non lo hai più, usa schema e dominio dell’indirizzo da cui apri la console di Notifuse.
  • Apri https://your-domain/api/workspaces.list in un browser. Un errore di autenticazione è la risposta prevista e dimostra che l’indirizzo è raggiungibile. Un timeout, un errore di connessione o un avviso sul certificato significano che nemmeno Zapier riesce a raggiungerlo.
  • Verifica che il certificato sia emesso da un’autorità di certificazione pubblica, e non sia autofirmato o interno.
  • Se la chiave è stata revocata in Notifuse (eliminando il collegamento Zapier o rimuovendo la sua riga da Impostazioni → Team e API Key), il collegamento smette subito di funzionare. Zapier segnala un errore di autenticazione e propone di ricollegare l’account: collega di nuovo Zapier e incolla il nuovo token.

Un passo fallisce con un errore di permessi

Il messaggio indica il permesso mancante. Aggiungilo alla chiave da Impostazioni → Team e API Key: la modifica vale dalla richiesta successiva e il token resta lo stesso. Non ricollegare Zapier per risolvere: un nuovo collegamento crea una chiave con gli stessi permessi standard, e il passo fallisce nello stesso punto.

Se Send Transactional Email fallisce su Transazionale, o la sua scelta della notifica è vuota e segnala un errore di permessi, il collegamento è precedente a Notifuse 39.1, la versione che ha aggiunto l’invio ai permessi standard. Spunta Transazionale in lettura e scrittura sulla chiave in Impostazioni → Team e API Key e il passo funzionerà alla prossima esecuzione, senza ricollegare né cambiare il token.

Uno Zap non riceve più eventi

Apri Impostazioni → Webhook in Notifuse e guarda la subscription di quello Zap:

  • Disattivata con un motivo indicato. Notifuse disattiva automaticamente una subscription dopo una lunga serie di consegne fallite e ne registra il motivo. Riattivala una volta risolta la causa, oppure disattiva e riattiva lo Zap in Zapier per ricrearla.
  • Del tutto assente. Qualcuno l’ha eliminata a mano, oppure lo Zap è stato disattivato. Disattiva e riattiva lo Zap.

Il log di consegna di ogni subscription mostra ogni evento inviato, la risposta di Zapier e il payload. È il modo più rapido per capire se Notifuse ha inviato un evento oppure no.

Il test del trigger non trova dati

Zapier cerca attività recenti corrispondenti per costruire il suo esempio. Se una lista non ha avuto iscritti di recente, o un segmento nuovi membri, non c’è nulla da mostrare. Crea un contatto di prova, iscrivilo alla lista e ripeti il test.

Limitazioni

  • Un collegamento copre un solo workspace. Più workspace richiedono più collegamenti.
  • L’eliminazione di un contatto non avvia uno Zap, e nemmeno gli eventi di broadcast o di automazione.
  • Non esiste ancora un passo di ricerca: non puoi cercare un contatto a metà Zap senza un’azione che scrive.
  • I campi personalizzati devono avere un’etichetta per comparire in un’azione.
  • Un invio non può contenere allegati. L’API li accetta, ma Zapier passa a un passo un riferimento al file e non il file stesso, quindi non c’è nulla da allegare.
  • Un invio non può comporre un’email. Invia una notifica che hai configurato in Notifuse e non può fornire un proprio corpo. Puoi sovrascrivere oggetto, testo di anteprima, nome del mittente e reply-to per un singolo messaggio.