Mailings

O que é

Mailing é o universo de contatos que uma Campanha Outbound vai discar. É uma lista — geralmente um arquivo CSV — que entra na plataforma uma vez e passa a alimentar a discagem da Campanha respeitando a Renitência herdada do Contratante.

Cada linha do mailing vira um Contato de Mailing (ContatoMailing) vinculado à Campanha, com dados pessoais, contato, dados comerciais e um status operacional que evolui conforme a discagem acontece.

Estrutura do arquivo

O caminho recomendado é CSV, mas o sistema também aceita TSV e arquivos com delimitador ponto-e-vírgula. O processador detecta:

• Delimitador — ; (padrão), \t, ,.
• Cabeçalho — quando a primeira linha contém nomes de coluna (recomendado).
• Encoding — utf-8 (padrão), latin1.

Cabeçalho com nomes claros simplifica o mapeamento. O sistema gera um hash do cabeçalho e, se já houver um Layout salvo na Operação que bate com aquele hash, reusa o mapeamento automaticamente — você sobe o arquivo e ele entra direto.

Colunas suportadas

O modelo de Contato cobre os campos típicos de operação de call center. O upload mapeia colunas do arquivo para esses campos:

Identificação

• codigo_externo — ID do contato no sistema do cliente, para rastreabilidade.

Dados pessoais

• nome (obrigatório).
• cpf (pode vir mascarado).
• data_nascimento, idade, sexo (MASC, FEM), estado_civil, nome_mae, nacionalidade.

Contato

• telefone (obrigatório).
• ddd, telefone2 (segundo número).
• email.

Telefones múltiplos: o modelo expõe um telefone principal e um secundário. Para listas com mais que dois números por contato, use dados_extras (JSON) e configure no Fluxo a lógica de tentativa.

Endereço

• endereco, numero, complemento, bairro, cidade, uf, cep, regiao.

Dados comerciais

• data_ultima_compra, categoria_produto, produto_descricao, marca, forma_pagamento, valor_ultima_compra.

Score / classificação

• score, status_carteira (VIRGEM, ATIVO, etc.).

Dados extras

• dados_extras — campo JSON livre para colunas que não cabem nos campos fixos (sem precisar criar coluna nova).

Layouts reaproveitáveis

Cada Operação tem uma biblioteca de Layouts de Mailing — configurações de upload (delimitador, encoding, mapeamento de colunas) reutilizáveis entre Campanhas da mesma Operação.

Fluxo do primeiro upload de um layout novo:

1. Upload do arquivo — sistema detecta delimitador e cabeçalho.
2. Hash do cabeçalho é calculado para identificação única.
3. Como é a primeira vez, o wizard de mapeamento abre — você liga cada coluna do arquivo a um campo do modelo (ou ao dados_extras).
4. O Layout é salvo na Operação com nome amigável (ex.: “Layout Cobrança Acme — V3”).
5. Próximos uploads de arquivos com o mesmo cabeçalho reusam o layout automaticamente — sem novo wizard.

Status operacional do Contato

Cada ContatoMailing carrega um status que evolui durante a operação:

Status	Significado
pendente	Cadastrado, ainda não foi discado.
discando	Em discagem agora.
em_atendimento	Conectado a Atendente ou Fluxo.
agendado	Tem retorno marcado para data/hora futura (agendado_para).
concluido	Atendimento finalizado com sucesso.
sem_sucesso	Esgotaram as tentativas sem conseguir contato útil.

Cada Contato registra também:

• prioridade (número, maior = mais prioritário).
• total_tentativas acumuladas.
• ultima_tentativa (timestamp).
• resultado do contato (venda, sem_interesse, nao_atendeu, numero_invalido, retornar, cancelou).
• observacoes livres do Atendente.

Renitência herdada

A política de retentativa não vive no mailing. Ela vive no Contratante (ver Contratantes) — defaults de 2 tentativas/dia, 15/mês, 120 minutos de intervalo, com regras adicionais por código de resultado.

Quando o discador escolhe o próximo contato a discar, ele:

1. Filtra contatos com status pendente ou agendado (com agendado_para no passado).
2. Aplica a Renitência efetiva (a mais restritiva entre limite local da Campanha e da Renitência do Contratante) para verificar se pode discar agora.
3. Respeita prioridade, persona atribuída e demais regras da Campanha.

A Campanha pode adicionar regras locais (ex.: limite local de tentativas), mas nunca afrouxar a Renitência do Contratante.

Persona atribuída por afinidade

A Campanha pode ter regras de afinidade de Persona que atribuem, no momento da discagem, qual persona vai conduzir a Conversa com cada contato. O persona_id fica gravado no ContatoMailing para reaproveitamento em ligações futuras com o mesmo contato.

Isso é útil em Operações que segmentam atendimento por perfil de contato (cobrança suave para score alto, abordagem técnica para categoria de produto X, etc.).

Acompanhamento de execução

A página de Mailings mostra, por Campanha:

• Distribuição por status — quantos pendentes, em discagem, concluídos, sem sucesso.
• Tentativas acumuladas.
• Conversão (resultado positivo / total).

Para análise mais profunda (taxa de contato útil, melhor janela de discagem, conversão por persona), use Relatórios.

Importação

A importação roda como job assíncrono rastreado por import_job_id. Cada Contato carrega referência ao job que o importou — útil para “rollback parcial” (excluir contatos da última importação se houve erro).

Erros de importação aparecem com a linha e o motivo (telefone inválido, CPF mal formatado, coluna obrigatória ausente). Linhas com erro não bloqueiam a importação — entram no relatório de erro, o restante segue.

Boas práticas

• Padronize o cabeçalho com o time de origem — ganha reuso de Layout e elimina retrabalho de mapeamento.
• Telefone como única chave de unicidade é fraco. Use codigo_externo para rastrear o registro mesmo se o telefone muda.
• Pré-valide telefones e CPFs na origem. O sistema rejeita formatos inválidos, mas tomar erros antes da importação é mais rápido.
• Use dados_extras para colunas que não cabem no schema fixo, em vez de tentar mapear “à força”. O Fluxo pode ler campos extras via interpolação.
• Não subir mailing duplicado. Cheque o resultado da última importação antes de subir o mesmo arquivo de novo.
• Atenção à LGPD. Mailing carrega dados pessoais. Suba apenas com base legal documentada e respeite a DNC do Contratante.

Erros comuns

• Encoding errado. Arquivo gerado em Windows com cp1252 importado como utf-8 quebra acentos. Salve como UTF-8 antes.
• Delimitador ambíguo. Vírgula em campos de texto sem escape quebra colunas. Prefira ; quando o conteúdo tem vírgulas.
• Cabeçalho variável. Um espaço a mais ou caixa diferente no cabeçalho gera hash diferente, e o Layout não é reusado.
• Esperar afrouxar Renitência via mailing. Não acontece — Renitência é do Contratante.
• Confundir status concluido com venda. concluido é “atendimento terminou”; resultado = venda é o resultado comercial. Os dois campos são independentes.

Ver também

• Campanhas
• Contratantes
• Operações
• Conversas
• Relatórios