Visão geral
Um contato guarda o perfil, as preferências e os dados de engajamento de um inscrito em campos predefinidos e personalizados. Ele pode pertencer a várias listas de emails.
Campos do contato
| Campo | Tipo | Descrição |
|---|---|---|
email | String | Endereço de email do contato e seu identificador único (Obrigatório) |
external_id | String | Referência opcional ao contato no seu próprio sistema. Não é único (veja Identidade do contato) |
first_name | String | Nome do contato |
last_name | String | Sobrenome do contato |
phone | String | Número de telefone |
timezone | String | Fuso horário ISO do contato |
language | String | Idioma preferido |
job_title | String | Cargo |
address_line_1 | String | Endereço principal |
address_line_2 | String | Complemento (apartamento, sala etc.) |
country | String | País no formato ISO |
state | String | Estado ou província |
postcode | String | CEP ou código postal |
custom_string_1 a custom_string_5 | String | Campos de texto personalizados |
custom_number_1 a custom_number_5 | Number | Campos numéricos personalizados |
custom_datetime_1 a custom_datetime_5 | DateTime | Campos de data e hora personalizados |
custom_json_1 a custom_json_5 | JSON | Campos JSON personalizados |
tracking_opens_consent, tracking_clicks_consent | String | granted, denied ou null (desconhecido): a escolha do contato sobre o rastreamento de aberturas e cliques |
tracking_consent_updated_at, tracking_consent_source | DateTime, String | Quando e onde essa escolha mudou pela última vez |
A ficha do contato
Ao clicar em um contato na tabela, a ficha dele abre sobre a página. A ficha tem um endereço próprio (a URL da página com ?contact= e o email), que você pode compartilhar ou abrir de novo. Se você a abriu pela tabela, o botão Voltar do navegador a fecha.
- Percorra a tabela com as setas no topo ou com J (próximo) e K (anterior). A ficha segue, na ordem, as linhas da visualização de onde você a abriu e carrega mais linhas quando você chega à última.
- Edite um campo clicando no valor dele. Os campos vazios ficam recolhidos sob um link no fim de cada painel.
- Números principais: emails recebidos, taxas de abertura e de cliques, a última atividade e, com a análise web ativada, as visitas ao site.
- Atividade: a linha do tempo do contato, filtrada por tipo (emails, listas e segmentos, alterações no perfil, eventos, visitas web).
- Mensagens: os emails enviados ao contato.
- Visitas web: as visitas do contato ao seu site, quando a análise web está ativada.
- Listas e segmentos: as inscrições do contato, que você pode alterar, e os segmentos a que ele pertence.
Gerenciamento de contatos
Identidade do contato e comportamento do upsert
O endereço de email é o identificador único de um contato. Ele é a chave primária no banco de dados, e todo upsert (contacts.upsert, contacts.import e o contato incluído em transactional.send) encontra os contatos apenas pelo endereço de email:
- Emails novos: cria um contato novo
- Emails existentes: atualiza o contato existente com os campos enviados
- Valores nulos: definir um campo como
nullremove esse valor do contato
external_id é uma referência opcional ao contato no seu próprio sistema (por exemplo, o ID do usuário na sua aplicação). Ele é armazenado, pode ser pesquisado e é retornado pela API, mas não é uma chave única:
- Ele nunca é usado para encontrar contatos durante os upserts.
- O Notifuse não impede que vários contatos compartilhem o mesmo
external_id. - Se vários contatos compartilham o mesmo
external_id,contacts.getByExternalIDretorna apenas um deles (qual deles não é definido).
Alterar o endereço de email de um contato
Como o endereço de email é a identidade do contato, fazer upsert do mesmo external_id com um novo endereço de email cria um segundo contato e não altera o email do contato existente. Quando um usuário muda o endereço de email no seu sistema:
- Busque o contato antigo com
contacts.getByEmailpara obter o perfil dele e as inscrições em listas com seus status. - Faça upsert de um contato com o endereço de email novo, enviando o perfil completo (o upsert mescla os campos, então inclua todos os campos que quer manter, como
external_id, nomes e campos personalizados). - Recrie as inscrições em listas no novo contato com
lists.subscribe. - Exclua o contato com o endereço de email antigo usando
contacts.delete.
Atenção
Preserve os status de descadastro ao recriar as inscrições. Se o contato antigo tinha cancelado a inscrição, retornado ou reclamado em uma lista, não inscreva o novo endereço de email nessa lista: o novo contato começa do zero, e reinscrevê-lo sem verificar apaga um descadastro sem aviso. Isso viola o consentimento (GDPR / CAN-SPAM) e pode prejudicar sua reputação de remetente.
Lembre-se também:
- O histórico de mensagens e a participação em segmentos são vinculados ao endereço de email. Eles continuam ligados ao endereço antigo e não são transferidos para o novo contato.
- Automações em andamento: excluir o contato antigo o remove de qualquer automação em que ele esteja avançando; o novo contato não retoma essa posição.
Excluir um contato
Excluir um contato com contacts.delete também exclui as inscrições dele em listas, incluindo os status de não inscrito, retornado e reclamado. Com isso, o Notifuse deixa de saber que o endereço pediu para sair. Uma importação posterior, um upsert com subscribe_to_lists ou lists.subscribe adiciona o endereço de volta como um contato novo e inscrito. Para continuar respeitando um descadastro, mude o status do contato na lista para não inscrito em vez de excluí-lo.
Um link de descadastro em um email enviado antes da exclusão continua respondendo com sucesso, mas não guarda nada sobre o endereço.
Inscrições em listas
- Os contatos podem se inscrever em uma ou várias listas de emails
- O status da inscrição é gerenciado por lista
- A participação em listas é registrada pela relação
contact_lists
Mecanismo de segmentação de contatos
O Notifuse segmenta os contatos pelas propriedades deles e pela forma como interagem. A participação é calculada em segundo plano, não em tempo real. Quando algo entra na linha do tempo de um contato (uma alteração no perfil, um email aberto, um evento personalizado), o contato vai para uma fila.
Uma tarefa recorrente processa essa fila, então uma mudança costuma aparecer nos segmentos do contato em até um minuto. Segmentos com datas relativas, como “nos últimos 30 dias”, também são reconstruídos todos os dias às 5h, no fuso horário do segmento.
Criar segmentos
Os segmentos são criados a partir dos tipos de condição abaixo.
Condições sobre propriedades do contato
Filtre os contatos pelos dados do perfil:
- Campos de texto: email, nomes, telefone, país, idioma, fuso horário, endereço, cargo, consentimento de rastreamento e sua origem, campos de texto personalizados. Operadores: está definido, não está definido, é igual a, é diferente de, contém (um ou vários valores), não contém.
- Campos numéricos: campos numéricos personalizados. Operadores: está definido, não está definido, é igual a, é diferente de, maior ou menor que (ou igual a).
- Campos de data: datas de criação e de atualização, data do consentimento de rastreamento, campos de data personalizados. Operadores: está definido, não está definido, antes de, depois de, entre, não está entre, nos últimos N dias, não nos últimos N dias (que também encontra os contatos cuja data nunca foi definida).
- Campos JSON: campos JSON personalizados, lidos em um caminho de chaves e índices de array, como texto, número ou data. O texto acrescenta “está no array”; a data oferece antes de, depois de, é igual a e os operadores de últimos N dias.
Vários filtros em uma condição precisam corresponder todos. Cada filtro é editado no próprio lugar, e uma condição não pode ser confirmada enquanto um dos filtros estiver incompleto.
Condições baseadas em metas
Crie segmentos RFM (Recência, Frequência, Valor monetário) usando Eventos personalizados e metas:
- Valor monetário: gasto total, valor médio do pedido
- Frequência: número de compras, número de eventos
- Recência: atividade dentro de um período
Exemplos de segmentos: clientes VIP (gastaram US$ 1000 ou mais), clientes recorrentes (3 pedidos ou mais), clientes em risco (nenhuma compra em 90 dias).
Condições baseadas em atividade
Segmente os contatos pela forma como eles interagem com seus emails e com seu site:
- Email enviado: o contato recebeu um email
- E-mail aberto: o contato abriu um email
- E-mail clicado: o contato clicou em um link de um email, opcionalmente um link cujo endereço contém um texto. Para emails enviados a partir da versão 42.2, o contato entra no segmento assim que clica nesse link, mesmo que não seja o primeiro link em que clicou no email
- Email rejeitado: o email retornou para esse contato
- Reclamação do e-mail: o contato marcou um email como spam
- Descadastrou-se por um e-mail: o contato cancelou a inscrição por um email
- Ver página web: o contato viu uma página do seu site, com filtro por caminho, tempo na página e profundidade de rolagem
- Visitar site: o contato fez uma visita, com filtro por página de entrada e de saída, páginas vistas, duração, canal, campanha, dispositivo e país
As duas condições de site exigem a Web Analytics e um visitante que tenha sido identificado.
As condições de atividade aceitam parâmetros adicionais:
- Frequência: pelo menos, no máximo ou exatamente um número de vezes
- Período: a qualquer momento, entre duas datas, antes ou depois de uma data, ou nos últimos N dias
- Template e broadcast (todas as atividades de email, incluindo Email enviado): conta apenas os emails enviados com um template ou por um broadcast
- Link clicado (E-mail clicado): conta apenas os cliques em links que contêm um texto, como
/pricing
Lógica das condições
Os segmentos combinam condições com a lógica E ou OU:
- Todas as condições a seguir: o contato precisa corresponder a todas as condições (lógica E)
- Pelo menos uma das condições a seguir: o contato precisa corresponder a uma condição ou mais (lógica OU)
As condições podem ser agrupadas, cada grupo com seu próprio “todas” ou “pelo menos uma”, e os grupos podem ser aninhados.
Casos de uso
Cenários comuns:
- Clientes VIP: quem gasta muito e compra várias vezes (use condições baseadas em metas)
- Recuperação de engajamento: reengaje inscritos inativos que não abrem emails há 90 dias
- Clientes em risco: compradores antes ativos que não compram há algum tempo
- Segmentação geográfica: envie campanhas regionais com base no país ou no estado
- Gatilhos comportamentais: alcance usuários que clicaram em links de produtos específicos
Detalhes técnicos
O mecanismo de segmentação lê a linha do tempo do contato, criada na versão 7.0, que registra todas as interações do contato, incluindo mensagens, eventos de webhook e alterações no perfil. Cada evento de atividade tem um kind (por exemplo, email.opened, email.clicked, web.pageview) que as condições podem usar. Os horários são armazenados em UTC, e as condições baseadas em data podem avaliá-los em um fuso horário que você indicar.
Permissões de segmentos
Os segmentos têm sua própria permissão Segmentos: leitura lista os segmentos e abre cada um, escrita cria, edita, exclui e reconstrói os segmentos, e executa, reinicia ou exclui as tarefas de construção em segundo plano.
Visualizar um segmento enquanto você o monta, e listar os contatos que um segmento abrange no momento, também exigem a permissão de leitura de Contatos. As duas ações respondem a perguntas sobre seus contatos, e não sobre a definição do segmento. Um membro que só tem leitura de Segmentos pode trabalhar com as definições, mas não vê quem está nos segmentos.
A visualização aceita qualquer definição, não só um segmento salvo. Assim, quem tem leitura de Segmentos e leitura de Contatos pode fazer perguntas de contagem sobre qualquer atributo de contato, participação em lista, evento personalizado ou entrada da linha do tempo, uma contagem por vez.
Importar contatos de um CSV
A importação tem três etapas: solte um arquivo CSV, associe as colunas e acompanhe a importação.
Associar as colunas
A primeira linha do arquivo traz os nomes das colunas, e uma coluna precisa conter endereços de email. Cada coluna aparece com valores de exemplo das primeiras linhas. Uma coluna com o nome de um campo do contato, pela chave (first_name) ou pelo rótulo (First Name), é associada automaticamente.
Você pode associar qualquer coluna a um campo padrão ou personalizado, ou deixá-la em Não importar. Cada campo recebe uma coluna, e a importação fica desativada até que uma coluna seja associada ao Email.
As colunas de consentimento aceitam granted ou denied, e os campos JSON personalizados aceitam JSON válido. Um contato que já está no workspace é encontrado pelo email e atualizado: cada campo presente na linha substitui o valor armazenado.
Adicionar a listas
Todo contato importado é inscrito nas listas que você escolher, uma ou várias.
Acompanhar a importação
As linhas são enviadas em lotes de 100, e a importação conta os contatos criados, atualizados e com falha. Cada linha com falha aparece com o número da linha no seu arquivo e o motivo. Baixar as linhas com falha entrega essas linhas com uma coluna error, para você corrigir e importar de novo.
A importação roda no seu navegador. Você pode pausá-la ou interrompê-la, e fechar o painel ou a aba também a interrompe. O progresso fica guardado neste navegador por 7 dias: a etapa Arquivo lista as importações não concluídas, e soltar o mesmo arquivo de novo oferece retomar a partir da linha onde ela parou, com a mesma associação de colunas e as mesmas listas.
Permissões da importação
Importar exige a permissão de escrita de Contatos. Escolher uma ou mais listas de emails durante a importação também exige escrita de Listas.
Cada campo presente em uma linha substitui o valor armazenado no contato correspondente, então uma única importação pode reescrever toda a sua base de contatos. Conceda escrita de Contatos tendo isso em mente.
Atualização em massa a partir de um CSV
Atualização em massa (CSV), no menu ⋯ da página Contatos, aplica uma ação a todos os contatos cujo endereço está em uma coluna de um CSV:
- Cancelar a assinatura de uma lista muda para não inscrito a inscrição dos contatos nessa lista. Eles continuam no workspace e podem se inscrever de novo. Um contato que não está na lista é ignorado.
- Excluir contatos remove os contatos e o histórico deles do workspace. Essa ação não pode ser desfeita.
A coluna cujo nome contém “mail” é escolhida automaticamente, e você pode escolher outra. Os endereços são convertidos para minúsculas e cada um é processado uma vez. Antes de começar, o resumo conta as linhas do arquivo, os duplicados removidos e as linhas sem um endereço válido.
A atualização roda no seu navegador, um contato por vez. Cada endereço aparece como concluído, ignorado ou com falha; você pode baixar os resultados em CSV e tentar de novo as falhas. Uma atualização interrompida pode ser retomada a partir do mesmo arquivo.
Cancelar inscrições exige a permissão de escrita de Listas além da escrita de Contatos; excluir exige escrita de Contatos.
Permissões
Os dados de contato dependem da permissão Contatos:
- Leitura cobre os registros de contato e seus perfis completos, a linha do tempo do contato e os eventos personalizados registrados nos contatos. Junto com a permissão correspondente de Listas ou de Segmentos, ela também é necessária para listar os endereços de uma lista ou de um segmento. Ela é exigida ainda para definir
ccoubccem um envio transacional. - Escrita cobre criar e atualizar contatos, excluí-los de forma definitiva, sobrescrevê-los em massa por uma importação de CSV ou pela API, e registrar eventos personalizados. Mudar o status da inscrição de um contato em uma lista também exige escrita de Listas.
Na ficha do contato, cada parte exige sua própria permissão: Mensagens exige leitura do histórico de mensagens, Visitas web exige leitura de análise web (com a análise web ativada), e os painéis de listas e segmentos exigem leitura de Listas e leitura de Segmentos. Sem escrita de Contatos, os campos da ficha não podem ser editados.
Três permissões chegam aos dados de contato sem escrita de Contatos. Verifique-as antes de conceder qualquer uma delas:
- Escrita de Listas, sozinha, cria ou sobrescreve o registro completo de um contato:
/api/lists.subscribegrava todos os campos presentes na requisição e pode inscrever alguém em uma lista que não é pública. - Escrita de Automações envia o registro completo do contato para qualquer URL indicada por um nó de webhook, e nada verifica permissões enquanto uma automação roda.
- Escrita de Transacional cria o contato destinatário como parte do envio. Sem escrita de Contatos, só o endereço de email é armazenado e um contato existente nunca é modificado (veja API transacional).
Principais recursos
- Os campos predefinidos atendem à maioria das necessidades, e os campos personalizados cobrem o resto.
- O upsert procura pelo endereço de email, então o mesmo endereço nunca cria dois contatos.
- Um contato pode pertencer a várias listas de emails.
- Definir um campo como
nullo apaga.
