Como Gerenciar as Listas de Contatos

9 Minutes to read

Print
Dark
Light
PDF

Como Gerenciar as Listas de Contatos

9 Minutes to read

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Sobre a função

As integrações desse grupo oferecem controle sobre os recursos relacionados às listas de contatos. É possível consultar informações dos contatos em uma lista, obter uma relação das listas cadastradas, adicionar contatos individualmente ou em lote, gerar relatórios sobre envios em um período específico ou ações específicas, remover contatos, adicionar contatos na lista de opt-out e obter os opt-outs do dia.

11.01 - Consulta as Informações de um Contato em uma Lista Específica

Utilize essa integração para visualizar informações de um contato em uma lista.

XML de envio

<main>
  <emkt trans="11.01">
    <lista>[TITULO DA LISTA]</lista>
    <contato>[E-MAIL ou CODIGO EXTERNO]</contato>
  </emkt>
</main>

XML de retorno

<main>
  <emkt trans="11.01">
    <contato codigo="[CODIGO]">
      <nome>[NOME]</nome>
      <sequencia>[SEQUENCIA]</sequencia>
      <email>[EMAIL]</email>
      <sexo>[SEXO]</sexo>
      <idade>[IDADE]</idade>
      <data_nascimento>[DATA_NASCIMENTO]</data_nascimento>
      <endereco>[ENDERECO]</endereco>
      <complemento>[COMPLEMENTO]</complemento>
      <bairro>[BAIRRO]</bairro>
      <cidade>[CIDADE]</cidade>
      <estado>[ESTADO]</estado>
      <pais>[PAIS]</pais>
      <cep>[CEP]</Cep>
      <telefone1>[TELEFONE 1]</telefone1>
      <telefone2>[TELEFONE 2]</telefone2>
      <telefone3>[TELEFONE 3]</telefone3>
      <fax>[FAX]</fax>
      <infoadc1 name="[Campo Adicional 1]">[INFO 01]</infoadc1>
      <infoadc2 name="[Campo Adicional 2]">[INFO 02]</infoadc2>
      <infoadc3 name="[Campo Adicional 3]">[INFO 03]</infoadc3>
      <infoadc4 name="[Campo Adicional 4]">[INFO 04]</infoadc4>
      <infoadc5 name="[Campo Adicional 5]">[INFO 05]</infoadc5>
      <infoadc6 name="[Campo Adicional 6]">[INFO 06]</infoadc6>
      <infoadc7 name="[Campo Adicional 7]">[INFO 07]</infoadc7>
      <infoadc8 name="[Campo Adicional 8]">[INFO 08]</infoadc8>
      <infoadc9 name="[Campo Adicional 9]">[INFO 09]</infoadc9>
      <infoadc10 name="[Campo Adicional 10]">[INFO 10]</infoadc10>
      <infoadc11 name="[Campo Adicional 11]">[INFO 11]</infoadc11>
      <infoadc12 name="[Campo Adicional 12]">[INFO 12]</infoadc12>
      <infoadc13 name="[Campo Adicional 13]">[INFO 13]</infoadc13>
      <infoadc14 name="[Campo Adicional 14]">[INFO 14]</infoadc14>
      <infoadc15 name="[Campo Adicional 15]">[INFO 15]</infoadc15>
      <infoadc16 name="[Campo Adicional 16]">[INFO 16]</infoadc16>
      <infoadc17 name="[Campo Adicional 17]">[INFO 17]</infoadc17>
      <infoadc18 name="[Campo Adicional 18]">[INFO 18]</infoadc18>
      <infoadc19 name="[Campo Adicional 19]">[INFO 19]</infoadc19>
      <infoadc20 name="[Campo Adicional 20]">[INFO 20]</infoadc20>
      <data_validade>[DATA VALIDADE]</data_validade>
    </contato>
  </emkt>
</main>

11.02 - Retornar o Nome das Listas Cadastradas no Sistema

Utilize essa integração para gerar uma relação das listas cadastradas na plataforma.

XML de envio

<main>
  <emkt trans="11.02">
  </emkt>
</main>

XML de retorno

<main>
  <emkt trans="01.22" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    <LISTA ID="[ID]" INDICE="[E/C]" CONTATOS_VALIDOS="[CONTATOS_VALIDOS]"ARQUIVADA="[S/N]">
    [NOME_DA_LISTA]</LISTA>
    (...)
  </emkt>
</main>

ID: Código identificador da lista no sistema.

INDICE: Índice da lista. Indica se a lista usa o campo de e-mail (E) ou o campo de código externo (C) como índice. Listas com índice "E" tratam o campo de e-mail como chave, não permitindo duplicatas. Listas com índice "C" tratam o campo de código externo como chave, permitindo que o campo de e-mail seja repetido na lista.
Por exemplo, em uma escola, um pai com dois filhos pode receber informações relacionadas a ambos, utilizando o código externo como o registro acadêmico (RA) do aluno.

CONTATOS_VALIDOS: Quantidade de contatos válidos na lista.

ARQUIVADA: Indica se a lista está atualmente arquivada:
S - Sim
N - Não

Após um período sem uso, as listas são arquivadas por questões de desempenho. Para reutilizar a lista, basta desarquivá-la na própria ferramenta, nas opções da lista.

NOME_DA_LISTA: Título da lista utilizado no sistema.

11.05 - Inclusão de Contatos em uma Lista

Utilize essa integração para inserir um ou mais contatos em uma lista. Caso a lista ainda não exista, ela será criada automaticamente durante esse processo. Se a quantidade de contatos a ser importada for superior a mil (1.000), é recomendado utilizar a integração (11.10 - Importação de um Arquivo para a Lista).

XML de envio estrutura completa

<main>
  <emkt trans="11.05">
    <nome>[NOME DA LISTA]</nome>
    <substituir>[S/N]</substituir>
    <tags>
      <nome>[NOME DA TAG1]</nome>
      <nome>[NOME DA TAG2]</nome>
    </tags>
    <destinatario codigo="[CODIGO]">
      <nome>[NOME]</nome>
      <email>[EMAIL]</email>
      <sexo>[SEXO]</sexo>
      <idade>[IDADE]</idade>
      <data_nascimento>[DATA_NASCIMENTO]</data_nascimento>
      <empresa>[EMPRESA]</empresa>
      <cpf>[CPF]</cpf>
      <atividade>[ATIVIDADE]</atividade>
      <profissao>[PROFISSAO]</profissao>
      <tipoend>[TIPO DE ENDERECO]</tipoend>
      <endereco>[ENDERECO]</endereco>
      <complemento>[COMPLEMENTO]</complemento>
      <bairro>[BAIRRO]</bairro>
      <cidade>[CIDADE]</cidade>
      <estado>[ESTADO]</estado>
      <pais>[PAIS]</pais>
      <cep>[CEP]</Cep>
      <telefone1>[TELEFONE 1]</telefone1>
      <telefone2>[TELEFONE 2]</telefone2>
      <telefone3>[TELEFONE 3]</telefone3>
      <fax>[FAX]</fax>
      <infoadc1>[INFO 01]</infoadc1>
      <infoadc2>[INFO 02]</infoadc2>
      <infoadc3>[INFO 03]</infoadc3>
      <infoadc4>[INFO 04]</infoadc4>
      <infoadc5>[INFO 05]</infoadc5>
      <infoadc6>[INFO 06]</infoadc6>
      <infoadc7>[INFO 07]</infoadc7>
      <infoadc8>[INFO 08]</infoadc8>
      <infoadc9>[INFO 09]</infoadc9>
      <infoadc10>[INFO 10]</infoadc10>
      <infoadc11>[INFO 11]</infoadc11>
      <infoadc12>[INFO 12]</infoadc12>
      <infoadc13>[INFO 13]</infoadc13>
      <infoadc14>[INFO 14]</infoadc14>
      <infoadc15>[INFO 15]</infoadc15>
      <infoadc16>[INFO 16]</infoadc16>
      <infoadc17>[INFO 17]</infoadc17>
      <infoadc18>[INFO 18]</infoadc18>
      <infoadc19>[INFO 19]</infoadc19>
      <infoadc20>[INFO 20]</infoadc20>
      <data_validade>[DATA VALIDADE]</data_validade>
    </destinatario>
    <destinatario codigo="[CODIGO]">
      (...)
    </destinatario>
    (...)
  </emkt>
</main>

XML de envio estrutura básica

<main>
  <emkt trans="11.05">
    <nome>[NOME DA LISTA]</nome>
   <destinatario>
      <email>[EMAIL]</email>
    </destinatario>
  </emkt>
</main>

XML de retorno

<main>
  <emkt trans="11.05" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
    <return id="99">
      <EMAIL_INVALIDO>[EMAIL]</EMAIL_INVALIDO>
      ( … )
    </return>
  </emkt>
</main>

Substituir: O valor padrão é N (Não), mas se for informado S (Sim), todos os contatos existentes na lista serão removidos antes da importação.

Os campos "infoadc" são campos adicionais que podem ser incluídos na plataforma. Por exemplo, em um e-commerce, você pode precisar de um campo "descrição do produto". Esses campos devem ser criados manualmente. Consulte nosso passo a passo para obter mais informações.

Código: O código externo do destinatário é opcional e deve ser utilizado quando desejar ter uma lista que permita a repetição do e-mail.

11.10 - Importação de Arquivo para a Lista

Utilize essa integração para importar os contatos em lote. Você pode enviar um arquivo .csv contendo todos os contatos desejados. Se a lista ainda não existir, o sistema irá criá-la automaticamente e importar os contatos.

XML de envio estrutura completa

<main>
  <emkt trans="11.10">
    <nome>[NOME DA LISTA]</nome>
    <identificador>[E/C]</identificador>
    <tags>
      <nome>[NOME DA TAG1]</nome>
      <nome>[NOME DA TAG2]</nome>
    </tags>
    <duplicidade_codigo_externo>[S/N]</duplicidade_codigo_externo>
    <arquivo>[URL DO ARQUIVO]</arquivo>
    <separador>[SEPARADOR]</separador>
    <acao>[I/S/R]</acao>
    <opcoes cabecalho="[S/N]" atualizar="[S/N]" />
    <campos>
      <nome col="[NUMERO DA COLUNA]" />
      <email col="[NUMERO DA COLUNA]" />
      <sexo col="[NUMERO DA COLUNA]" />
      <idade col="[NUMERO DA COLUNA]" />
      <data_nascimento col="[NUMERO DA COLUNA]" />
      <codigo_externo col="[NUMERO DA COLUNA]" />
      <empresa col="[NUMERO DA COLUNA]" />
      <cpf col="[NUMERO DA COLUNA]" />
      <atividade col="[NUMERO DA COLUNA]" />
      <profissao col="[NUMERO DA COLUNA]" />
      <tipoend col="[NUMERO DA COLUNA]" />
      <endereco col="[NUMERO DA COLUNA]" />
      <complemento col="[NUMERO DA COLUNA]" />
      <bairro col="[NUMERO DA COLUNA]" />
      <cidade col="[NUMERO DA COLUNA]" />
      <estado col="[NUMERO DA COLUNA]" />
      <pais col="[NUMERO DA COLUNA]" />
      <cep col="[NUMERO DA COLUNA]" />
      <telefone1 col="[NUMERO DA COLUNA]" />
      <telefone2 col="[NUMERO DA COLUNA]" />
      <telefone3 col="[NUMERO DA COLUNA]" />
      <fax col="[NUMERO DA COLUNA]" />
      <infoadc1 col="[NUMERO DA COLUNA]" />
      <infoadc2 col="[NUMERO DA COLUNA]" />
      <infoadc3 col="[NUMERO DA COLUNA]" />
      <infoadc4 col="[NUMERO DA COLUNA]" />
      <infoadc5 col="[NUMERO DA COLUNA]" />
      <infoadc6 col="[NUMERO DA COLUNA]" />
      <infoadc7 col="[NUMERO DA COLUNA]" />
      <infoadc8 col="[NUMERO DA COLUNA]" />
      <infoadc9 col="[NUMERO DA COLUNA]" />
      <infoadc10 col="[NUMERO DA COLUNA]" />
      <infoadc11 col="[NUMERO DA COLUNA]" />
      <infoadc12 col="[NUMERO DA COLUNA]" />
      <infoadc13 col="[NUMERO DA COLUNA]" />
      <infoadc14 col="[NUMERO DA COLUNA]" />
      <infoadc15 col="[NUMERO DA COLUNA]" />
      <infoadc16 col="[NUMERO DA COLUNA]" />
      <infoadc17 col="[NUMERO DA COLUNA]" />
      <infoadc18 col="[NUMERO DA COLUNA]" />
      <infoadc19 col="[NUMERO DA COLUNA]" />
      <infoadc20 col="[NUMERO DA COLUNA]" />
      <data_validade col="[NUMERO DA COLUNA]" />
    </campos>
  </emkt>
</main>

XML de envio estrutura básica:

<main>
  <emkt trans="11.10">
    <nome>[NOME DA LISTA]</nome>
    <arquivo>[URL DO ARQUIVO]</arquivo>
    <campos>
      <email col="[NUMERO DA COLUNA]" />
    </campos>
  </emkt>
</main>

Arquivo: Endereço do arquivo a ser importado, suportando os protocolos HTTP, HTTPS, FTP e FTPS.

O sistema suporta os formatos de arquivo .ZIP, .XLS, .CSV e .Txt, porém a melhor opção é o formato .CSV (separado por vírgulas).

No formato ZIP, o arquivo deve conter apenas um arquivo interno. Os arquivos podem estar no formato .XLS, .CSV ou .Txt.
O tamanho máximo permitido para o arquivo a ser enviado é de até 20MB para arquivos .ZIP e 40MB para os outros formatos.
Exemplo: ftp://user:senha@ftp.dominio.com.br/pasta/arquivo.csv
A codificação do arquivo deve ser em ISO-8859-1.

Valores para o campo "ação":
I = Adicionar o conteúdo do arquivo ao conteúdo da lista.
S = Remover o conteúdo anterior da lista antes de importar.
R = Excluir da lista os contatos importados do arquivo.

Opções (esses itens são opcionais)
Cabeçalho - Informe se o seu arquivo importado possui ou não a linha de cabeçalho, ou seja, se possui o nome das colunas.
Atualizar - Atualiza os dados dos contatos que estiverem diferentes.

Todos os campos exceto e-mail são de uso opcional, portanto a omissão pode ser feita sem problemas.

Atenção

Perceba que todos os campos possuem um item col="[NUMERO DA COLUNA], nele você deve informar o número da coluna que correspondente ao seu arquivo .CSV.

XML de retorno

<main>
  <emkt trans="11.10" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <processo>[CODIGO MD5]</processo>
  </emkt>
</main>

11.11 - Consulta a Situação do Processo de Importação dos Contatos

Com essa integração, você pode verificar o status da importação dos contatos na integração anterior (11.10 Importação de Arquivo para Lista). O retorno fornecerá informações sobre o progresso da importação, incluindo o percentual concluído, bem como quaisquer problemas encontrados, como contatos duplicados ou em formato inválido. Todos esses contatos problemáticos não serão inseridos na lista.

XML de envio

<main>
  <emkt trans="11.11">
    <processo>[CODIGO MD5]</processo>
  </emkt>
</main>

XML de retorno

<main>
  <emkt trans="11.11" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
    <progresso>[PERCENTUAL]</progresso>
    <resultado>
      <erro>[MENSAGEM DE ERRO]</erro>
      <lista>[NOME DA LISTA]</lista>
      <arquivo>[NOME DO ARQUIVO]</arquivo>
      <linhas>[LINHAS NO ARQUIVO]</linhas>
      <duplicados>[CONTATOS DUPLICADOS NO ARQUIVO]</duplicados>
      <inseridos>[CONTATOS INSERIDOS]</inseridos>
      <atualizados>[CONTATOS ATUALIZADOS]</atualizados>
      <invalidos>[CONTATOS INVALIDOS]</invalidos>
      <formato_invalido>[CONTATOS COM E-MAIL ERRADOS]</formato_invalido>
      <cadastrados>[CONTATOS JÁ CADASTRADOS]</cadastrados>
      <validos_antes>[CONTATOS VALIDOS ANTES DA IMPORTAÇÃO]</validos_antes>
      <validos_apos>[CONTATOS VALIDOS APÓS IMPORTAÇÃO]</validos_apos>
    </resultado>
  </emkt>
</main>

11.40 – Informa as Listas em que o Contato está Presente

Essa integração gera uma lista das listas em que um determinado contato está presente. Você pode informar vários contatos na mesma integração para obter as respectivas listas.

XML de envio

<main>
   <emkt trans="11.40">
      <email>teste@teste.com.br</email>
      <email>teste@teste.com.br</email>
     (...)
   </emkt>
</main>

XML de retorno

<main>
 <emkt>
  <contato>
    <email>teste@teste.com.br</email>
      <listas>
       <titulo>Lista 01</titulo>
       <titulo>Lista 02</titulo>
       <titulo>Lista 30</titulo>
      </listas>
   </contato>
   <contato>
    <email>teste01@teste.com.br</email>
     <listas>
       <titulo>Lista 01</titulo>
       <titulo>Lista 35</titulo>
       <titulo>Lista 70</titulo>
     </listas>
   </contato>
 </emkt>
</main>

11.45 – Remover Contatos de uma Lista

Utilize essa integração para remover contatos de uma lista específica. Você pode utilizar o endereço de e-mail ou o número de celular como "chave" para a remoção dos contatos.

XML de remoção usando o campo e-mail

<main>
 <emkt trans="11.45">
  <titulo>Titulo da lista</titulo>
   <destinatarios>
    <email>teste@teste.com.br</email>
    <email>teste@teste.com.br</email>
    <email>teste@teste.com.br</email>
    (...)
   </destinatarios>
  </emkt>
</main>

XML de remoção usando o campo celular

<main>
 <emkt trans="11.45">
  <titulo>Titulo da lista</titulo>
   <destinatarios>
    <celular>11999999999</celular>
    <celular>11999999999</celular>
    <celular>11999999999</celular>
    (...)
   </destinatarios>
  </emkt>
</main>

XML de retorno

<MAIN>
    <EMKT TRANS="11.45" KEY="0c5001c9dd16bb98dd78631b9ce6">
        <RETURN ID="00">Contatos removidos com sucesso. </RETURN>
    </EMKT>
</MAIN>

11.90 - Insere Opt-Out / Opt-In

Utilize essa integração para definir se um contato será opt-out ou opt-in. Quando um contato é opt-out, ele não receberá mais as mensagens enviadas pela plataforma. Se o contato estiver com o status opt-in, ele continuará recebendo as mensagens normalmente. Além disso, você pode utilizar as categorias para determinar quais tipos de mensagens o contato deve ou não receber. A categoria deve conter o título ao qual o contato será alterado para opt-out ou opt-in. Também é possível utilizar a literal "[TODAS]" para indicar que a alteração será aplicada a todas as categorias. Por exemplo: [TODAS].

Na plataforma, as categorias são descritas como áreas de interesse. Dessa forma, você pode tornar um contato opt-in para uma categoria e opt-out para outra, garantindo que ele receba apenas as mensagens relacionadas às áreas de seu interesse.

XML de envio

<main>
  <emkt trans="11.90">
    <acao>[ACAO]</acao> (0 = Opt-out, 1 = Opt-In)
    <email>[EMAIL]</email> (E-mail que será setado opt-out ou opt-in)
    <categoria>[CATEGORIA]</categoria>
    <categoria>[CATEGORIA]</categoria>
    <categoria>[CATEGORIA]</categoria>
    (...)
  </emkt>
</main>

XML de retorno

<main>
  <emkt trans="11.90" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="00">Ok</return>
  </emkt>
</main>

Retorno com falha

<main>
  <emkt trans="11.90" key="XXXXXXXXXXXXXXXXXXXXXXXXXXXX">
    <return id="99">Categoria não encontrada (Lista de categorias separadas por vírgula)</return>
  </emkt>
</main>

Pontos Impotantes:

A importação de contatos para a plataforma não está limitada à criação de uma nova lista. Você pode importar os contatos para uma lista já existente. Para fazer isso, informe o nome de uma lista existente no campo "nome" da integração 11.05 ou 11.10.
O arquivo de retorno na integração 11.05 pode eventualmente apresentar uma lista de e-mails que foram considerados inválidos pelo sistema. A API irá inserir todos os e-mails válidos durante o processo.

Was this article helpful?

What's Next

Como Gerar Relatórios via Integração

Table of contents

Sobre a função
Pontos Impotantes: