Respostas e webhooks
Tudo que os destinatários enviam de volta — votos de enquete, envios de formulário, avaliações, giros — é coletado por projeto. Isso retorna para você de duas formas: uma visualização de respostas por destinatário no painel, e um webhook opcional que envia cada interação para o seu próprio endpoint no instante em que ela chega.
Respostas por destinatário no painel
Abra Painel → seu e-mail → Respostas. Cada interação que o e-mail coletou é agrupada por destinatário e unida à fonte de dados do projeto. Cada grupo mostra quem respondeu — o endereço de e-mail e os outros campos da linha dele — junto com o que fez: qual bloco, qual ação, os valores enviados e quando.
A atribuição funciona por meio dos mesmos tokens assinados que protegem os links de visualização ao vivo. Quando um e-mail é personalizado a partir de uma fonte de dados, os links de cada destinatário carregam um token vinculado à linha dele, e as interações que chegam com um token válido são atribuídas a essa linha. Interações que chegam sem token (por exemplo, um voto de enquete de um e-mail enviado sem personalização) ainda contam — elas são listadas em um grupo separado de Anônimos.
A lista de eventos brutos é paginada (mais recentes primeiro): depois de carregar a página mais recente, uma ação Carregar mais busca eventos mais antigos. Tudo abaixo — resumos, histogramas, o funil e a tendência — não é afetado por essa paginação; é pré-computado e sempre cobre o histórico completo do projeto.
Pedidos, fulfillment e reembolsos
Qualquer projeto com um bloco de produto recebe uma tabela de Pedidos em sua página de Respostas — uma linha por checkout, com comprador, valor, status e horário do pedido.
- No instante em que um pagamento é aprovado, o comprador recebe um e-mail automaticamente: o conteúdo de entrega de um produto digital, ou uma confirmação de que um pedido físico está a caminho do fulfillment.
- Para pedidos físicos, clique em Marcar como atendido depois de enviá-lo — o MailInApp não cuida do envio em si, mas envia ao comprador um aviso de envio no instante em que você aciona o botão.
- Clique em Reembolsar em qualquer pedido pago para reverter a cobrança por meio da sua conta Stripe conectada; o comprador recebe um e-mail de confirmação do reembolso. O mesmo e-mail é enviado automaticamente se uma venda for concluída exatamente quando a última unidade se esgota — o MailInApp reembolsa o comprador em vez de vender silenciosamente além do estoque.
- Contatar comprador abre um ticket de suporte pré-preenchido com o contexto daquele pedido — a forma mais rápida de perguntar algo diretamente a um comprador.
Métrica principal guiada pelo propósito
Se um projeto tiver um propósito definido (pesquisa, promoção, newsletter ou evento), a página de Respostas lidera com o único número que esse propósito mais valoriza: taxa de resposta para pesquisas, destinatários engajados para promoções, e aberturas rastreadas para newsletters e eventos. Projetos transacionais e projetos sem propósito definido vão direto para o funil e os resumos abaixo. Altere ou limpe o propósito quando quiser no menu ao lado do título da página; isso só afeta qual número é destacado, nunca o que é registrado.
Taxa de conclusão
Quando um e-mail pede respostas em dois ou mais blocos (enquetes, avaliações, quizzes, RSVPs e formulários), o Insights acompanha quem respondeu a todos. O painel Respostas do estúdio define quais blocos contam (Blocos que contam, todos por padrão). Com Agradecer aos destinatários em Depois de qualquer resposta, ou menos de dois blocos contados, não há taxa de conclusão.
- A Visão geral tem um bloco Taxa de conclusão: as pessoas que concluíram, como parcela de todas que responderam a pelo menos um bloco contado, com seu intervalo de 95%. Clique para ver quem concluiu.
- Onde as pessoas pararam ganha uma barra Concluíram e, abaixo dela, um link para as pessoas que começaram mas não terminaram.
- Em Destinatários, a coluna Concluído mostra quando cada pessoa terminou, e Adicionar condição oferece Começou a responder e Concluiu a resposta, ambas podendo ser invertidas ("Não concluiu a resposta"). A exportação CSV ampla tem uma coluna
completed_at. - O relatório em PDF e Explicar esta página incluem a taxa, e O que mudou pode apontar uma variação nela.
Com um intervalo de datas, a taxa conta as pessoas que começaram dentro dele e quantas delas concluíram até o fim dele. Uma resposta é concluída uma única vez, na primeira vez em que cada bloco contado mostrado a ela tem resposta, então mudar uma resposta depois não altera a contagem. Só contam as conclusões registradas pelo MailInApp: um e-mail respondido por inteiro antes de elas serem registradas não mostra conclusões para essas pessoas.
Resumos de CSAT, CES e NPS
Todo bloco de avaliação recebe um resumo acima da lista de destinatários: contagem de respostas, média, e um histograma (a distribuição por trás da média — uma média de 4,1 esconde se é tudo notas 4 ou uma mistura de 5 e 1). Blocos no estilo NPS mostram contagens de promotores/neutros/detratores e a pontuação de −100…100 em vez de uma média simples. Uma divisão de distribuição de respostas faz o mesmo para blocos de enquete, por opção.
Um funil de engajamento (Enviado → Aberto (aprox.) → Respondido) fica acima dos resumos. Um gráfico de tendência de respostas por bloco (em blocos de dia ou semana) mostra a média ao longo do tempo — o valor de uma pesquisa recorrente está na linha de tendência, não em um único instantâneo. Ele só é renderizado quando um bloco tem pelo menos dois blocos de dados.
Resumos de perguntas da pesquisa
Todo bloco de formulário recebe um resumo por pergunta, da mesma forma que os blocos de avaliação e enquete. Perguntas de múltipla escolha, caixas de seleção, escala linear e avaliação por estrelas recebem um gráfico de barras com a contagem de opções; perguntas de texto livre (texto curto, texto longo, e-mail, número, telefone, data) recebem uma contagem de respostas mais algumas respostas de amostra. Pesquisas de múltiplas páginas são resumidas da mesma forma que as de página única — um envio só conta quando todas as páginas foram concluídas, então uma pesquisa abandonada nunca aparece como uma resposta parcial.
Esses resultados de enquete, avaliação e pergunta de pesquisa não são um beco sem saída — qualquer um deles pode ser plotado diretamente dentro de um e-mail futuro vinculando um bloco de gráfico a "resposta de campanha", sem necessidade de reentrada manual. Veja Vinculando gráficos a dados reais.
Lição de casa e diário de notas
Cada bloco de tarefa ganha um card nos Insights do e-mail, em Blocos: quantas das pessoas que abriram ou interagiram a entregaram e, se houver prazo, quantas no prazo ou atrasadas. Destinatários lista cada aluno com uma coluna por tarefa (feita, no prazo ou atrasada). Abra um aluno para ler o que ele entregou, na linha do tempo dele, pronto para dar nota. A exportação CSV ampla tem as mesmas colunas, e a exportação de eventos traz cada entrega com a resposta.
Mapa de calor de cliques
Abaixo dos resumos, um Mapa de calor de cliques classifica todo bloco portador de link simples — botões, imagens com link, ícones sociais, links de prêmio de raspadinhas e roletas premiadas — por contagem de cliques, com o comprimento e a intensidade da barra proporcionais ao volume relativo. Veja como os cliques são rastreados para saber o que conta e o que não conta.
Funil de profundidade de rolagem
Um funil de profundidade de rolagem mostra qual fração dos visitantes da visualização ao vivo alcançou cada marco de 25/50/75/100% da página, para que você saiba se as pessoas estão desistindo no início ou lendo até o fim. Ele só reflete visitas à visualização ao vivo hospedada, não ao e-mail enviado em si — veja Profundidade de rolagem para entender por quê.
Teste A/B e vencedores automáticos
Enviar com mais de uma variante (veja Enviar) adiciona um cartão Teste A/B ao Insights do e-mail, em Envios. Escolha o envio em Envio A/B para ver as taxas de abertura, de cliques e de resposta de cada variante nesse envio. Cada taxa conta uma pessoa uma única vez, sobre as pessoas que receberam aquela variante. No plano Pro e superiores, Comparado com a variante A acrescenta a diferença de cada variante em relação à variante A, com um intervalo de 95%.
Uma variante não se limita à redação da linha de assunto; ela também pode trocar a identidade de remetente, ou o e-mail inteiro. Uma variante que enviou outro e-mail é contada nesse outro e-mail, sob o mesmo envio, e o cartão leva ao Insights desse e-mail.
Escolher um vencedor automaticamente envia primeiro para uma fatia de teste. Escolha uma fração de teste (por exemplo, 20% da lista, dividida entre as variantes), quanto tempo esperar antes de decidir e qual métrica usar na decisão: abertura, clique, resposta dentro do e-mail ou receita. Resposta dentro do e-mail (conclusão de enquete, quiz ou RSVP) é o padrão recomendado, já que a Proteção de Privacidade do Mail da Apple infla as aberturas. Decidir pela receita exige o plano Pro ou superior.
Quando a espera termina, o MailInApp envia a variante com a melhor taxa por destinatário para todos que ficaram de fora do teste, nunca a de maior total bruto. Um empate, ou uma amostra com menos de 5 envios por variante, volta para a primeira variante e avisa isso. O aviso do cartão mostra em que estado um teste está e se a variante na frente supera o ruído até agora.
Leia os resultados A/B com cautela
Um envio A/B simples não fixa nada antes: nem a métrica, nem o tamanho da amostra, nem quando parar. Leia o cartão dele como uma comparação simples, como diz o próprio rótulo, e não como prova de que uma variante é melhor. Para uma resposta em que você possa se basear, rode um experimento, que resolve cada um destes pontos:
- Amostras pequenas têm muito ruído. Com algumas centenas de destinatários por variante, uma diferença de um ou dois pontos percentuais muitas vezes é acaso. O vencedor automático decide a partir de 5 envios por variante, pouco demais para descartar o acaso. Um experimento dimensiona a amostra antes do envio com o planejador do tamanho da amostra, e os resultados dele dizem a menor diferença que ele conseguia detectar.
- Cada teste redistribui a lista. A variante de um contato depende do endereço de e-mail dele e do envio, então dois testes na mesma lista colocam contatos diferentes na variante A. Um experimento sorteia a amostra uma única vez, dá a cada contato uma só variante e o deixa de fora dos outros envios do e-mail.
- A taxa de clique conta pessoas, não cliques. Cada destinatário conta uma vez na taxa de clique, não importa quantas vezes clique, assim como nas taxas de abertura e de resposta. A taxa de cliques únicos de um experimento conta do mesmo jeito, sobre os e-mails entregues.
- Receita significa checkout dentro do e-mail. A métrica de receita conta só compras do bloco de produto. Pedidos em uma loja Shopify ou WooCommerce conectada não contam para nenhuma variante. Um experimento associa os pedidos da loja às variantes por código de desconto, link rastreado ou endereço de e-mail.
- Aberturas são o sinal mais fraco. A Proteção de Privacidade do Mail da Apple e os proxies de imagem carregam o pixel de abertura automaticamente, então as taxas de abertura ficam altas e variam conforme o app de e-mail. Um experimento mostra as aberturas só como referência, nunca como a métrica que decide.
- Um envio alcança no máximo 200 destinatários. Um teste maior precisa ser dividido em vários envios, e os resultados só são tão limpos quanto o cronograma. Um experimento envia a amostra inteira em um único processo, com todas as variantes intercaladas nos mesmos minutos.
Otimização de horário de envio
Disponível a partir do plano Pro. Em vez de todo mundo em um envio saindo de uma vez, Enviar no melhor horário de cada destinatário analisa o próprio histórico de abertura de cada contato — em qual hora do dia, em UTC, ele de fato mais abriu e-mails seus. O envio da mensagem dele é retido até essa hora. Qualquer pessoa sem histórico de abertura suficiente para um sinal confiável passa direto para um envio imediato comum.
Isso se aplica da mesma forma a um envio manual, a um agendamento recorrente e à própria etapa de envio de uma jornada; um agendamento ainda envia para todos sem sinal no próprio horário configurado, igual ao comportamento anterior à otimização. Não pode, atualmente, ser combinado com um teste de vencedor automático no mesmo envio, já que um destinatário postergado não seria contado a tempo de um vencedor ser decidido.
Detalhando por um campo
Use Detalhar por para agrupar os mesmos resumos por qualquer campo da sua fonte de dados — CSAT médio por agente, NPS por plano, e assim por diante. Destinatários cuja linha foi excluída ou reduzida desde o envio são agrupados em (desconhecido); se um campo de texto livre gerar mais de 20 valores distintos, os grupos menores se dobram em um grupo final de Outros, para que a visualização não exploda.
Exportação de CSV
Baixar CSV na página de Respostas exporta um arquivo amplo, com uma linha por destinatário: todo campo da fonte de dados, horário da primeira abertura, e uma coluna por bloco interativo (com o cabeçalho da respectiva pergunta). Respostas de acompanhamento recebem sua própria coluna <pergunta> — follow-up. Uma segunda exportação de eventos brutos fornece uma linha por evento (destinatário, bloco, ação, valor, data/hora) para analistas que preferem o formato longo.
Ciclo de vida da pesquisa
Um projeto pode ter uma data de encerramento e/ou um limite de respostas (maxResponses). Assim que qualquer um dos dois é atingido, novos eventos de interação são rejeitados — a visualização ao vivo mostra um aviso de encerramento em vez dos blocos interativos, embora o conteúdo estático continue sendo exibido — e a página de Respostas mostra se a pesquisa está atualmente encerrada. Nada é filtrado retroativamente: as respostas já registradas permanecem nos seus dados.
Alertas de nota baixa no app
Além da flag lowScore do webhook (abaixo), um projeto pode listar até alguns poucos endereços de e-mail para notificar diretamente — sem precisar de uma etapa no Zapier/Make. Sempre que uma resposta de avaliação cruza o limite configurado do bloco, o MailInApp envia um e-mail para esses endereços (através das suas próprias configurações de SMTP) com a pergunta, a nota, a identidade do destinatário quando conhecida, e um link direto para a página de Respostas. Se nenhum relay de SMTP estiver configurado, o alerta é ignorado silenciosamente — o webhook ainda dispara. Os alertas são limitados por projeto por hora, para que uma explosão de notas baixas não sobrecarregue seu relay.
Reconstruindo agregados
Resumos, o funil e a tendência são servidos a partir de um agregado pré-computado por projeto, atualizado conforme os eventos chegam — para que permaneçam rápidos independentemente do histórico que um projeto acumulou. Se um projeto mostrar totais inesperadamente baixos ou zerados, é provável que tenha coletado respostas antes de esse agregado existir para ele; clique em Reconstruir agregados em sua página de Respostas uma vez para reprocessar todo o histórico de eventos no agregado. Projetos novos nunca precisam disso.
Webhooks
Se preferir que os dados cheguem aos seus próprios sistemas — um CRM, uma planilha, uma ferramenta de automação — configure um webhook na mesma página de Respostas: informe uma URL HTTPS e clique em Ativar.
Este webhook cobre um único e-mail. Para receber em um só lugar as interações de todos os seus e-mails, mais eventos da conta como leads novos, agendamentos e movimentações de negócios, use um webhook da conta. Ele é assinado do mesmo jeito.
Duas coisas acontecem:
- Você vê um segredo de assinatura (
whsec_…) — copie-o imediatamente, ele é exibido apenas uma vez. Ele é armazenado no servidor e mascarado em todo lugar depois disso, como todas as credenciais no MailInApp. - A partir daí, cada interação é enviada via POST para a sua URL como JSON, imediatamente após ser registrada.
Você pode rotacionar o segredo (um novo é gerado e exibido uma vez) ou remover o webhook a qualquer 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é o próprio dado coletado — a opção de enquete escolhida, os valores dos campos do formulário, a quantidade de estrelas.recipienténullpara interações anônimas. Para as atribuídas,keyé o índice da linha do destinatário na sua fonte de dados ("row:3"= quarta linha).recipient.row— a linha completa de dados do destinatário — é incluído para fontes de dados hospedadas. Para fontes do tipo API, não chamamos seu endpoint em cada interação; faça a junção pelo índice da linha do seu lado.lowScoreétruequando o evento é uma açãorateem um bloco de avaliação cujo valor está em ou abaixo do limite de alerta configurado para esse bloco — o sinal que uma automação no Zapier/Make (ou seu próprio alerta dentro do app) filtra para notificar um gestor de suporte. Ele é omitido inteiramente em eventos que não são de avaliação, ou quando o bloco não tem limite configurado.
Respostas completas
Quando um destinatário respondeu a todos os blocos que o e-mail conta (definido no painel Respostas do Estúdio), o webhook também recebe uma entrega response.completed para ele, assinada da mesma forma. O seu data é o do evento do webhook da conta:
{
"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
}
}
Ela é enviada uma vez por destinatário: mudar uma resposta depois não a envia de novo. Esta entrega não tem event, então verifique type primeiro.
Verificando assinaturas
Toda entrega é assinada para que seu endpoint possa confirmar que ela realmente veio do MailInApp. Dois cabeçalhos são enviados:
| Cabeçalho | Conteúdo |
|---|---|
X-MailInApp-Timestamp | Quando a entrega foi assinada, em milissegundos desde a época Unix |
X-MailInApp-Signature | v1= seguido do HMAC-SHA256(secret, timestamp + "." + rawBody) em hexadecimal |
Calcule a assinatura esperada a partir do corpo bruto da requisição (antes de qualquer análise de JSON) e compare com uma comparação de tempo constante. Rejeitar registros de data/hora antigos bloqueia entregas repetidas (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;
}
Semântica de entrega
- A primeira tentativa é imediata, depois há novas tentativas automáticas. As entregas expiram após 5 segundos; qualquer coisa que não seja uma resposta
2xx(um tempo esgotado, uma falha de conexão, ou um status de erro) é tratada como falha. O evento é sempre armazenado primeiro no MailInApp, então uma entrega perdida não perde nada — trate o webhook como um sinal em tempo real e a visualização de Respostas como a fonte da verdade. - Novas tentativas automáticas com backoff. Uma entrega com falha é reenviada em intervalos crescentes — aproximadamente 1 minuto, 5 minutos, 30 minutos, 2 horas, depois 6 horas — usando a URL e o segredo atuais do seu webhook, então um segredo rotacionado ou uma URL atualizada são adotados automaticamente. Se todas as tentativas falharem, a entrega para de tentar por conta própria, mas nunca é descartada.
- Reenvio manual. Qualquer entrega que ainda esteja falhando (em nova tentativa ou esgotada) aparece em Entregas com falha na página de Respostas, com o motivo da última falha e um botão Reenviar — útil logo depois que você corrigir o que estava quebrado do seu lado, em vez de esperar a próxima tentativa agendada.
- Nunca no caminho do destinatário. As entregas acontecem depois que a interação do destinatário é confirmada; um endpoint lento ou quebrado não pode atrasar ou falhar o voto ou envio dele.
- Responda rápido. Retorne qualquer
2xxrapidamente e faça o processamento pesado de forma assíncrona.
Aviso sobre confiança: os endpoints de interação são públicos por necessidade (uma caixa de entrada não tem como se autenticar), então eventos anônimos não são autenticados por design. Eventos atribuídos são protegidos por tokens de destinatário assinados. Verifique a assinatura da entrega e trate
event.valuecomo entrada de usuário.
