Fontes de dados e tags de personalização

As tags de personalização permitem personalizar cada e-mail com dados reais. Escreva {{field}} em qualquer lugar de um bloco de texto — Hi {{first_name}}, your {{plan}} renews soon — e cada destinatário verá seus próprios valores. Um projeto pode conectar várias fontes de dados ao mesmo tempo: cada uma recebe um alias curto, e os campos de uma fonte que não seja o público são escritos como {{alias.field}} (por exemplo, {{products.name}}).

Tipos de fonte de dados

As fontes de dados são gerenciadas na seção Fontes de Dados do seu painel (as listas de contatos ficam em Contatos). Existem dois tipos:

Tabelas hospedadas

Uma tabela armazenada no MailInApp. Defina colunas, adicione linhas no painel, e cada coluna se torna um campo de personalização. Ideal quando seus dados hoje vivem em uma planilha. As listas de contatos são tabelas hospedadas com uma coluna email garantida.

Conexões de API

Aponte o MailInApp para o seu próprio endpoint HTTP que retorna JSON. As linhas são buscadas no servidor — a partir dos nossos servidores, nunca da caixa de entrada do destinatário ou do navegador dos seus visitantes.

Três formas de autenticar a conexão, escolhidas no menu suspenso Autenticação ao configurá-la:

Cabeçalhos estáticos — adicione cabeçalhos de requisição (por exemplo, um cabeçalho Authorization) com um valor fixo. A opção mais simples, e a única que fazia sentido antes que um token pudesse expirar.
OAuth2 Client Credentials — uma URL de token mais um ID e um segredo de cliente. O MailInApp os troca por um token de acesso no servidor, o armazena em cache, e o renova automaticamente antes de expirar — o padrão comum na maioria das integrações empresariais baseadas em chave e segredo de API.
OAuth2 JWT Bearer — uma URL de token, emissor, sujeito, audiência, e uma chave privada RSA (PEM). O MailInApp assina uma nova asserção JWT e a troca por um token de acesso, sem login interativo e sem refresh token para gerenciar — é assim que as integrações servidor a servidor do Salesforce se autenticam (veja o guia de integração com o Salesforce), e funciona da mesma forma para uma conta de serviço do Google ou qualquer outro IdP que suporte o fluxo.

Qualquer que seja o modo escolhido, o token bearer resultante é injetado automaticamente como um cabeçalho Authorization — quaisquer cabeçalhos adicionais que você adicionar continuam sendo enviados junto, mesclados (um cabeçalho literalmente chamado Authorization ali é ignorado, já que o token gerado sempre prevalece). Todos os campos de credencial — valores de cabeçalho, segredo de cliente, chave privada — seguem a mesma regra:

armazenados apenas no servidor,
nunca enviados ao navegador,
mascarados em toda resposta da API depois de salvos.

Editar uma conexão cujo segredo aparece mascarado e clicar em Testar estas configurações exige que o valor real seja informado novamente primeiro; Testar conexão salva roda a verificação usando a credencial exatamente como está armazenada, sem nunca enviá-la de volta ao seu navegador.

Conectando fontes: o painel de Dados

O painel de Dados do estúdio é onde um projeto declara quais fontes ele usa. + Adicionar fonte de dados… conecta uma (até 10 por projeto); cada conexão tem três partes:

Alias — o identificador curto que as tags de personalização usam: letras minúsculas, dígitos e sublinhados, começando com uma letra (ex.: contacts, products, open_invoices). Renomear um alias atualiza automaticamente qualquer bloco de repetição vinculado a ele.
Fonte — a tabela hospedada, lista de contatos ou conexão de API por trás dela.
Função — como o e-mail a utiliza:
- Público — a lista de contatos para a qual o e-mail é enviado. No máximo uma por projeto, e precisa ser uma lista de contatos. Seus campos são as tags simples — {{first_name}}, {{email}} — resolvidas por destinatário, a partir da própria linha dele, no momento do envio. O público também controla o seletor "Pré-visualizar como" e a atribuição de respostas por destinatário.
- Campos de personalização — campos legíveis sob o alias: {{alias.field}}, resolvidos a partir da primeira linha da fonte quando o e-mail é renderizado. Use para conteúdo compartilhado — o produto em destaque, as estatísticas da semana — em vez de dados por destinatário.
- Linhas de repetição — linhas que alimentam blocos de repetição vinculados ao alias. Não contribui com campos de personalização fora da repetição. A mesma função collection também alimenta os blocos de gráfico de KPI/barra/linha/pizza — veja Vinculando gráficos a dados reais.

Toda fonte conectada lista seus campos como chips clicáveis — clique em um para copiar a tag de personalização exata, e cole em qualquer propriedade de texto. Os editores de condição de exibição agrupam o menu suspenso de campos da mesma forma: campos do destinatário (público) mais um grupo para cada fonte de personalização.

Tags integradas

Um punhado de tags é fornecido pela própria plataforma, e não por uma fonte de dados — o painel Variáveis, na barra lateral esquerda do estúdio, as lista junto com qualquer variável que você defina; clique em uma para copiar sua tag.

{{recipient_email}} — o endereço para o qual o e-mail é enviado.
{{today}} / {{now}} — a data (ou data e hora) em que o e-mail é aberto.
{{unsubscribe_url}} — um link de cancelamento de inscrição com um clique, por destinatário. O preset de rodapé já o inclui — veja Enviando para seus contatos.

Um código de desconto de loja, único e por destinatário, não é uma tag de personalização — em vez disso, coloque o bloco Desconto para E-commerce (apenas para públicos conectados ao Shopify/WooCommerce) no e-mail, e ele gera e exibe seu próprio código automaticamente. Veja Oferta de desconto.

As tags integradas só são resolvidas em envios reais (manual, agendado, ou um envio de teste no estilo "Backfill") — a pré-visualização e a tela do estúdio as mostram vazias ou com um placeholder, como qualquer campo sem valor de amostra.

Conteúdo repetido

O bloco de repetição renderiza seus filhos uma vez para cada linha da fonte à qual ele está vinculado — uma grade de produtos, um resumo de artigos, uma lista de faturas em aberto. Escolha a fonte pelo alias no Inspetor; dentro da repetição, as tags são resolvidas em relação à própria linha de cada repetição.

Pré-visualizando com dados reais

O seletor de dados de pré-visualização do estúdio renderiza a tela com qualquer linha da lista de público, para que você confira que {{first_name}} realmente aparece como Amina, e não como {{first_name}}, antes de enviar. Campos de outras fontes também podem receber valores de pré-visualização.

Bom saber

Campos ausentes para um destinatário são renderizados como strings vazias — projete de forma que um valor em branco ainda pareça natural.
Páginas hospedadas (visualização ao vivo, formulários hospedados) resolvem tags de personalização por destinatário no momento da renderização, então a personalização sobrevive mesmo quando um destinatário sai da caixa de entrada.
Projetos criados antes do suporte a múltiplas fontes continuam funcionando sem alteração: sua única fonte conectada aparece automaticamente no painel de Dados, e as tags simples {{field}} sempre são resolvidas em relação ao público.