Menu della documentazione

Risposte e webhook

Tutto ciò che i destinatari inviano indietro — voti nei sondaggi, invii di moduli, valutazioni, giri della ruota — viene raccolto per progetto. Torna a te in due modi: una vista delle risposte per destinatario nella dashboard, e un webhook facoltativo che invia ogni interazione al tuo endpoint nel momento in cui arriva.

Video in inglese

Risposte per destinatario nella dashboard

Apri Dashboard → la tua email → Risposte. Ogni interazione raccolta dall'email viene raggruppata per destinatario e unita alla fonte dati del progetto. Ogni gruppo mostra chi ha risposto — il suo indirizzo email e gli altri campi della sua riga — insieme a cosa ha fatto: quale blocco, quale azione, i valori inviati e quando.

L'attribuzione funziona tramite gli stessi token firmati che proteggono i link della vista live. Quando un'email è personalizzata a partire da una fonte dati, i link di ogni destinatario portano un token vincolato alla sua riga, e le interazioni che arrivano con un token valido vengono attribuite a quella riga. Le interazioni che arrivano senza token (ad esempio un voto in un sondaggio da un'email inviata senza personalizzazione) contano comunque — vengono elencate in un gruppo separato Anonimo.

L'elenco grezzo degli eventi è paginato (i più recenti per primi): una volta caricata la pagina più recente, un'azione Carica altro recupera gli eventi più vecchi. Tutto ciò che segue — riepiloghi, istogrammi, il funnel e il trend — non è influenzato da questa paginazione; è precalcolato e copre sempre la cronologia completa del progetto.

Ordini, fulfillment e rimborsi

Ogni progetto con un blocco prodotto ottiene una tabella Ordini sulla propria pagina Risposte — una riga per checkout, con acquirente, importo, stato e orario dell'ordine.

  • Nel momento in cui un pagamento va a buon fine, all'acquirente viene inviata automaticamente un'email: il contenuto di consegna di un prodotto digitale, oppure una conferma che un ordine fisico è avviato al fulfillment.
  • Per gli ordini fisici, clicca Contrassegna come evaso una volta spedito — MailInApp non gestisce direttamente la spedizione, ma invia comunque all'acquirente un avviso di spedizione nel momento in cui attivi l'interruttore.
  • Clicca Rimborsa su qualsiasi ordine pagato per annullare l'addebito tramite il tuo account Stripe collegato; all'acquirente viene inviata un'email di conferma del rimborso. La stessa email viene inviata automaticamente se una vendita si conclude proprio mentre si esaurisce l'ultima unità — MailInApp rimborsa l'acquirente invece di vendere in eccesso silenziosamente.
  • Contatta l'acquirente apre un ticket di supporto precompilato con il contesto di quell'ordine — il modo più rapido per chiedere qualcosa direttamente a un acquirente.

Metrica principale guidata dallo scopo

Se un progetto ha uno scopo impostato (sondaggio, promozione, newsletter o evento), la pagina Risposte apre con l'unico numero a cui quello scopo tiene di più: tasso di risposta per i sondaggi, destinatari coinvolti per le promozioni, e aperture tracciate per newsletter ed eventi. I progetti transazionali e quelli senza uno scopo impostato passano direttamente al funnel e ai riepiloghi sottostanti. Cambia o cancella lo scopo in qualsiasi momento dal menu a tendina accanto al titolo della pagina; influisce solo su quale numero viene messo in evidenza, mai su cosa viene registrato.

Tasso di completamento

Quando un'email chiede risposte in due o più blocchi (sondaggi, valutazioni, quiz, RSVP e moduli), Insights tiene traccia di chi ha risposto a tutti. Il pannello Risposte dello studio stabilisce quali blocchi contano (Blocchi che contano, tutti per impostazione predefinita). Se Ringrazia i destinatari è impostato su Dopo una risposta qualsiasi, o contano meno di due blocchi, non c'è un tasso di completamento.

  • La Panoramica ha un riquadro Tasso di completamento: le persone che hanno completato, come quota di tutte quelle che hanno risposto ad almeno un blocco contato, con il suo intervallo al 95%. Fai clic per vedere chi ha completato.
  • Dove si sono fermate le persone aggiunge una barra Completato e, sotto, un link alle persone che hanno iniziato senza finire.
  • In Destinatari, la colonna Completato mostra quando ogni persona ha finito, e Aggiungi condizione offre Ha iniziato a rispondere e Ha completato la risposta, entrambe invertibili («Non ha completato la risposta»). L'esportazione CSV estesa ha una colonna completed_at.
  • Il report PDF e Spiega questa pagina includono il tasso, e Cosa è cambiato può segnalarne una variazione.

Con un intervallo di date, il tasso conta le persone che hanno iniziato al suo interno e quante di loro hanno completato entro la sua fine. Una risposta si completa una sola volta, la prima volta che ogni blocco contato che le è stato mostrato ha una risposta, quindi cambiare una risposta in seguito non cambia il conteggio. Contano solo i completamenti registrati da MailInApp: un'email a cui si è risposto per intero prima che venissero registrati non mostra completamenti per quelle persone.

Riepiloghi CSAT, CES e NPS

Ogni blocco di valutazione ottiene un riepilogo sopra l'elenco dei destinatari: numero di risposte, media, e un istogramma (la distribuzione dietro la media — una media di 4,1 nasconde se si tratta di tutti 4 o di una divisione tra 5 e 1). I blocchi in stile NPS mostrano i conteggi di promotori/neutri/detrattori e il punteggio da −100 a 100 invece di una semplice media. Una ripartizione della distribuzione delle risposte fa lo stesso per i blocchi sondaggio, per opzione.

Riepiloghi delle domande del sondaggio

Ogni blocco modulo ottiene un riepilogo per domanda, allo stesso modo dei blocchi di valutazione e sondaggio. Le domande a scelta multipla, caselle di controllo, scala lineare e valutazione a stelle ottengono un grafico a barre dei conteggi delle opzioni; le domande a testo libero (testo breve, testo lungo, email, numero, telefono, data) ottengono un conteggio delle risposte più una manciata di risposte di esempio. I sondaggi multi-pagina vengono riepilogati in modo identico a quelli a pagina singola — un invio conta solo una volta completate tutte le pagine, così un sondaggio abbandonato non compare mai come risposta parziale.

Questi risultati di sondaggi, valutazioni e domande del sondaggio non sono un vicolo cieco — ognuno di essi può essere rappresentato graficamente direttamente all'interno di una futura email associando un blocco grafico a "risposta della campagna", senza bisogno di reinserimento manuale. Consulta Associare grafici a dati reali.

Compiti e registro dei voti

Ogni blocco Compito ha la sua scheda negli Insights dell'email, in Blocchi: quante delle persone che hanno aperto o interagito l'hanno consegnato e, se ha una scadenza, quante in tempo o in ritardo. Destinatari elenca ogni studente con una colonna per compito (fatto, in tempo o in ritardo). Apri uno studente per leggere cosa ha consegnato, nella sua cronologia, pronto da valutare. L'esportazione CSV estesa ha le stesse colonne, e l'esportazione degli eventi contiene ogni consegna con la sua risposta.

Mappa di calore dei clic

Sotto i riepiloghi, una Mappa di calore dei clic classifica ogni blocco con semplici link — pulsanti, immagini con link, icone social, link premio di gratta e vinci e ruota della fortuna — per numero di clic, con lunghezza e intensità della barra proporzionate al volume relativo. Consulta come vengono tracciati i clic per sapere cosa conta e cosa no.

Funnel di profondità di scorrimento

Un funnel di profondità di scorrimento mostra quale quota di visitatori della vista live ha raggiunto ciascun traguardo del 25/50/75/100% della pagina, così puoi capire se le persone abbandonano presto o leggono fino alla fine. Riflette solo le visite alla vista live ospitata, non l'email inviata stessa — consulta Profondità di scorrimento per capire il perché.

Test A/B e vincitori automatici

Inviare con più di una variante (consulta Invio) aggiunge una scheda Test A/B agli Insights dell'email, in Invii. Scegli l'invio in Invio A/B per vedere i tassi di apertura, di clic e di risposta di ogni variante per quell'invio. Ogni tasso conta una persona una volta sola, sul totale delle persone a cui è stata inviata quella variante. Dal piano Pro in su, Confronto con la variante A aggiunge la differenza di ogni variante rispetto alla variante A, con un intervallo al 95%.

Una variante non si limita al testo dell'oggetto; può anche cambiare l'identità del mittente, o l'intera email. Una variante che ha inviato un'altra email viene conteggiata in quell'email, sotto lo stesso invio, e la scheda rimanda agli Insights di quell'email.

Scegli automaticamente il vincitore invia prima a una parte di prova. Scegli una frazione di test (ad es. il 20% della lista, divisa tra le varianti), quanto tempo attendere prima di decidere, e quale metrica usare per decidere: apertura, clic, risposta all'interno dell'email, o ricavo. La risposta all'interno dell'email (completamento di sondaggio, quiz o RSVP) è l'opzione predefinita consigliata, perché la Protezione della privacy di Mail di Apple gonfia le aperture. Decidere in base ai ricavi richiede il piano Pro o superiore.

Trascorsa l'attesa, MailInApp invia a tutti quelli trattenuti la variante con il miglior tasso per destinatario, mai quella con il totale grezzo più alto. Un pareggio, o un campione sotto i 5 invii per variante, ricade sulla prima variante, e lo dice. Il banner della scheda mostra in quale stato si trova un test, e se la variante in testa è avanti di più del rumore registrato finora.

Leggere i risultati A/B con cautela

Un semplice invio A/B non fissa nulla in anticipo: né la metrica, né la dimensione del campione, né quando fermarsi. Leggi la sua scheda come un confronto semplice, come dice la sua etichetta, non come la prova che una variante sia migliore. Per una risposta su cui agire, esegui un esperimento, che gestisce ciascuno di questi punti:

  • I campioni piccoli sono rumorosi. Con qualche centinaio di destinatari per variante, uno scarto di uno o due punti percentuali è spesso dovuto al caso. Il vincitore automatico decide già da 5 invii per variante, troppo pochi per escludere il caso. Un esperimento dimensiona il campione prima dell'invio con il pianificatore della dimensione del campione, e i suoi risultati indicano la minima differenza che poteva rilevare.
  • Ogni test ridistribuisce la lista. La variante di un contatto dipende dal suo indirizzo email e dall'invio, quindi due test sulla stessa lista mettono contatti diversi nella variante A. Un esperimento estrae il campione una sola volta, dà a ogni contatto una sola variante e lo esclude dagli altri invii dell'email.
  • Il tasso di clic conta persone, non clic. Ogni destinatario conta una volta nel tasso di clic, per quante volte clicchi, come per i tassi di apertura e di risposta. Il tasso di clic unici di un esperimento conta allo stesso modo, sulle email consegnate.
  • I ricavi sono quelli del checkout nell'email. La metrica dei ricavi conta solo gli acquisti del blocco Prodotto. Gli ordini su un negozio Shopify o WooCommerce collegato non contano per una variante. Un esperimento collega gli ordini del negozio alle sue varianti tramite codice sconto, link tracciato o indirizzo email.
  • Le aperture sono il segnale più debole. La Protezione della privacy di Mail di Apple e i proxy delle immagini caricano il pixel di apertura automaticamente, quindi i tassi di apertura risultano alti e variano in base all'app di posta. Un esperimento mostra le aperture solo come contesto, mai come metrica che decide.
  • Un invio raggiunge al massimo 200 destinatari. Un test più grande va diviso su più invii, e i risultati sono puliti solo quanto le tempistiche. Un esperimento invia tutto il campione in un unico processo, con tutte le varianti alternate negli stessi minuti.

Ottimizzazione dell'orario di invio

Disponibile da Pro in su. Invece di far uscire tutti in un invio contemporaneamente, Invia all'orario migliore di ciascun destinatario analizza la cronologia degli orari di apertura di ogni contatto — a quale ora del giorno, in UTC, ha effettivamente aperto più spesso la posta da te. Trattiene il suo messaggio fino a quell'ora. Chiunque non abbia ancora una cronologia di apertura sufficiente per avere un segnale affidabile passa direttamente a un normale invio immediato.

Si applica allo stesso modo a un invio manuale, a una pianificazione ricorrente e al passaggio di invio di un percorso automatizzato; una pianificazione invia comunque a tutti quelli senza segnale al proprio orario configurato, in linea con il comportamento precedente all'ottimizzazione. Al momento non può essere combinata con un test di vincitore automatico nello stesso invio, poiché un destinatario differito non verrebbe conteggiato al momento in cui viene deciso un vincitore.

Suddivisione per campo

Usa Suddividi per per raggruppare gli stessi riepiloghi per qualsiasi campo della tua fonte dati — CSAT medio per agente, NPS per piano, e così via. I destinatari la cui riga è stata eliminata o ridotta dopo l'invio vengono raggruppati sotto (sconosciuto); se un campo a testo libero produce più di 20 valori distinti, i gruppi più piccoli confluiscono in un gruppo finale Altro così la vista non esplode.

Esportazione CSV

Scarica CSV sulla pagina Risposte esporta un file ampio, con una riga per destinatario: ogni campo della fonte dati, l'orario della prima apertura, e una colonna per ciascun blocco interattivo (intestata con la sua domanda). Le risposte di follow-up ottengono una propria colonna <question> — follow-up. Una seconda esportazione di eventi grezzi fornisce invece una riga per evento (destinatario, blocco, azione, valore, timestamp) per gli analisti che preferiscono il formato lungo.

Ciclo di vita del sondaggio

Un progetto può avere una data di chiusura e/o un limite di risposte (maxResponses). Una volta raggiunto uno dei due, i nuovi eventi di interazione vengono rifiutati — la vista live mostra un avviso di chiusura al posto dei blocchi interattivi, sebbene il contenuto statico continui a essere visualizzato — e la pagina Risposte mostra se il sondaggio è attualmente chiuso. Nulla viene filtrato retroattivamente: le risposte già registrate restano nei tuoi dati.

Avvisi in-app per punteggi bassi

Oltre al flag lowScore del webhook (sotto), un progetto può elencare fino a una manciata di indirizzi email da notificare direttamente — senza bisogno di un passaggio Zapier/Make. Ogni volta che una risposta di valutazione supera la soglia configurata del suo blocco, MailInApp invia un'email a quegli indirizzi (tramite le tue stesse impostazioni SMTP) con la domanda, il punteggio, l'identità del destinatario quando nota, e un link diretto alla pagina Risposte. Se non è configurato alcun relay SMTP, l'avviso viene saltato silenziosamente — il webhook si attiva comunque. Gli avvisi sono limitati per progetto per ora, così un'ondata di punteggi bassi non può inondare il tuo relay.

Ricostruzione degli aggregati

I riepiloghi, il funnel e il trend vengono serviti da un aggregato precalcolato per progetto, aggiornato man mano che arrivano gli eventi — così restano rapidi indipendentemente dalla quantità di cronologia di un progetto. Se un progetto mostra totali inaspettatamente bassi o pari a zero, probabilmente ha raccolto risposte prima che questo aggregato esistesse per esso; clicca Ricostruisci aggregati sulla sua pagina Risposte una volta per riprodurre l'intera cronologia degli eventi nell'aggregato. I progetti nuovi non ne hanno mai bisogno.

Webhook

Se preferisci che i dati arrivino nei tuoi sistemi — un CRM, un foglio di calcolo, uno strumento di automazione — configura un webhook sulla stessa pagina Risposte: inserisci un URL HTTPS e clicca Attiva.

Questo webhook copre una sola email. Per ricevere in un unico punto le interazioni di tutte le tue email, più gli eventi dell'account come nuovi lead, prenotazioni e movimenti delle trattative, usa invece un webhook dell'account. È firmato allo stesso modo.

Accadono due cose:

  1. Ti viene mostrato un segreto di firma (whsec_…) — copialo immediatamente, viene mostrato solo questa volta. Viene memorizzato lato server e mascherato ovunque in seguito, come tutte le credenziali in MailInApp.
  2. Da quel momento, ogni interazione viene inviata (POST) al tuo URL come JSON, subito dopo essere stata registrata.

Puoi ruotare il segreto (ne viene generato uno nuovo e mostrato una sola volta) o rimuovere il webhook in qualsiasi momento.

Payload

{
  "type": "interaction.received",
  "projectId": "abc123",
  "event": {
    "campaignId": "abc123",
    "blockId": "poll-1",
    "blockType": "poll",
    "action": "vote",
    "value": { "option": "Blue" },
    "recipient": "row:3",
    "projectId": "abc123",
    "receivedAt": 1752480000000
  },
  "recipient": {
    "key": "row:3",
    "row": { "email": "[email protected]", "first_name": "Ada" }
  },
  "lowScore": false
}
  • event.value è il dato raccolto stesso — l'opzione scelta nel sondaggio, i valori dei campi del modulo, il numero di stelle.
  • recipient è null per le interazioni anonime. Per quelle attribuite, key è l'indice di riga del destinatario nella tua fonte dati ("row:3" = quarta riga).
  • recipient.row — la riga di dati completa del destinatario — è inclusa per le fonti dati ospitate. Per le fonti di tipo API non chiamiamo il tuo endpoint a ogni interazione; esegui il join sull'indice di riga dal tuo lato.
  • lowScore è true quando l'evento è un'azione rate su un blocco di valutazione il cui valore è pari o inferiore alla soglia di avviso configurata di quel blocco — il segnale su cui un'automazione Zapier/Make (o il tuo stesso avviso in-app) filtra per avvisare un responsabile del supporto. Viene omesso interamente sugli eventi che non sono di valutazione, o quando il blocco non ha una soglia configurata.

Risposte complete

Quando un destinatario ha risposto a ogni blocco contato dall'email (impostato nel pannello Risposte dello Studio), il webhook riceve anche una consegna response.completed per lui, firmata allo stesso modo. Il suo data è quello dell'evento del webhook dell'account:

{
  "type": "response.completed",
  "projectId": "abc123",
  "data": {
    "projectId": "abc123",
    "projectName": "Customer survey",
    "recipient": "row:3",
    "contact": { "listId": "list_abc123", "rowId": "3", "email": "[email protected]" },
    "sendId": "send_abc123",
    "variant": null,
    "blockIds": ["poll-1", "rating-1"],
    "answers": {
      "poll-1": { "option": "Weekly" },
      "rating-1": { "rating": "9" }
    },
    "firstAnsweredAt": 1752480000000,
    "completedAt": 1752480060000
  }
}

Viene inviata una volta per destinatario: cambiare una risposta in seguito non la reinvia. Questa consegna non ha event, quindi controlla prima type.

Verifica delle firme

Ogni consegna è firmata così il tuo endpoint può confermare che proviene davvero da MailInApp. Vengono inviati due header:

HeaderContenuto
X-MailInApp-TimestampQuando la consegna è stata firmata, in millisecondi epoch
X-MailInApp-Signaturev1= seguito da HMAC-SHA256(secret, timestamp + "." + rawBody) in esadecimale

Calcola la firma attesa a partire dal corpo grezzo della richiesta (prima di qualsiasi parsing JSON) e confrontala con un confronto a tempo costante. Rifiutare i timestamp obsoleti blocca le consegne ripetute (replay):

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidDelivery(headers, rawBody, secret) {
  const timestamp = headers["x-mailinapp-timestamp"];
  const given = Buffer.from(headers["x-mailinapp-signature"] ?? "");
  const expected = Buffer.from(
    "v1=" +
      createHmac("sha256", secret)
        .update(`${timestamp}.${rawBody}`)
        .digest("hex"),
  );
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
    return false;
  }
  // Reject deliveries signed more than 5 minutes ago (replay protection).
  return Math.abs(Date.now() - Number(timestamp)) < 5 * 60 * 1000;
}

Semantica di consegna

  • Il primo tentativo è immediato, poi viene ritentato automaticamente. Le consegne scadono dopo 5 secondi; qualsiasi cosa al di sotto di una risposta 2xx (un timeout, un errore di connessione, o uno stato di errore) viene trattata come un fallimento. L'evento viene sempre memorizzato prima in MailInApp, così una consegna mancata non perde nulla — considera il webhook come un segnale in tempo reale e la vista Risposte come la fonte di verità.
  • Nuovi tentativi automatici con backoff. Una consegna fallita viene ritentata a intervalli crescenti — circa 1 minuto, 5 minuti, 30 minuti, 2 ore, poi 6 ore — rispetto all'URL e al segreto attuali del tuo webhook, così un segreto ruotato o un URL aggiornato vengono recepiti automaticamente. Se ogni tentativo continua a fallire, la consegna smette di ritentare da sola, ma non viene mai scartata.
  • Riconsegna manuale. Qualsiasi consegna ancora fallita (in fase di nuovo tentativo o esaurita) compare sotto Consegne fallite nella pagina Risposte, con il motivo dell'ultimo fallimento e un pulsante Riconsegna — utile subito dopo aver risolto ciò che era rotto dal tuo lato, invece di aspettare il prossimo tentativo pianificato.
  • Mai di intralcio al destinatario. Le consegne avvengono dopo che l'interazione del destinatario è stata confermata; un endpoint lento o non funzionante non può ritardare o far fallire il suo voto o invio.
  • Rispondi velocemente. Restituisci rapidamente qualsiasi 2xx ed esegui l'elaborazione pesante in modo asincrono.

Avviso sulla fiducia: gli endpoint di interazione sono pubblici per necessità (una casella di posta non può autenticarsi), quindi gli eventi anonimi non sono autenticati per progettazione. Gli eventi attribuiti sono protetti da token del destinatario firmati. Verifica la firma della consegna e tratta event.value come input dell'utente.