Importar e exportar contatos

Use o assistente de importação para trazer contatos de uma planilha e a exportação para baixar os contatos que correspondem aos filtros atuais. Esta página também apresenta as ações em massa e o endpoint de exportação da API, para fazer o mesmo pelo código.

Antes de começar

• Crie os campos personalizados que você quer preencher a partir do arquivo. O assistente só consegue associar colunas a campos que já existem.
• Crie as listas de contatos em que os contatos devem entrar. As importações contam para o limite de inscritos de cada lista.
• Importe apenas pessoas que concordaram em receber os seus e-mails. As análises de acesso de produção perguntam como você coleta os inscritos. Consulte Acesso de produção.

Preparar o arquivo

O assistente lê arquivos .csv, .xlsx e .xls com até 2.500 contatos por arquivo. Divida listas maiores em vários arquivos.

email,first_name,last_name,company,birthday
ada@example.com,Ada,Lovelace,Acme,1990-04-12
grace@example.com,Grace,Hopper,Acme,1906-12-09
alan@example.com,Alan,Turing,,

Dicas para uma importação limpa:

• Coloque um contato em cada linha e os nomes das colunas na primeira linha. Nos arquivos do Excel, apenas a primeira planilha é lida.
• Dê às colunas os nomes dos seus campos para que o assistente as associe para você. O cabeçalho de uma coluna é associado automaticamente quando corresponde ao nome ou à chave de um campo, sem diferenciar maiúsculas de minúsculas, por exemplo email, First name, first_name ou a chave de um campo personalizado como company.
• Salve os arquivos CSV em UTF-8 para que os nomes com acentos sejam importados corretamente.
• Escreva as datas como YYYY-MM-DD. Células de data em arquivos do Excel também funcionam. Outros formatos de data são rejeitados.
• Confira os endereços. Um único endereço de e-mail inválido interrompe a importação inteira com um erro que indica a linha, por exemplo “Contact #12 has an invalid email address.” As linhas com a célula de e-mail vazia são ignoradas.
• Os valores de seleção múltipla são importados como um único valor de texto. Para armazenar várias opções como lista, defina-as com a API.

Importar contatos

1. Abra o assistente. Acesse Email Marketing›Contacts e selecione Import.

2. Escolha o arquivo. Em CSV File, selecione o seu arquivo. Deixe File has header marcado se a primeira linha tiver os nomes das colunas. O assistente mostra as primeiras linhas e o número total de linhas, com um aviso se o arquivo tiver mais de 2.500 linhas. Selecione Continue.

3. Associe as colunas. Para cada coluna, escolha o campo do contato que ela preenche: Email, First name, Last name, um dos seus campos personalizados ou Exclude para ignorá-la. É obrigatório associar uma coluna a Email. Cada linha mostra valores de exemplo para você conferir a associação.

4. Escolha as listas. Em Audiences, escolha as listas em que os contatos devem entrar, ou deixe em branco para importar os contatos sem adicioná-los a uma lista. Selecione Continue.

5. Revise e importe. A prévia mostra o arquivo, o número de contatos, as listas, a associação das colunas e os 10 primeiros contatos como serão salvos. Selecione Import.

Primeiro, o Emailit valida o arquivo inteiro. Se algo estiver errado, como um endereço inválido, um campo personalizado desconhecido ou uma lista cheia, nada é importado e os erros são listados para você corrigir o arquivo. Caso contrário, a importação é executada em segundo plano, em lotes de 500. Atualize a página de contatos depois de alguns instantes para ver os novos contatos.

O que acontece com os contatos existentes

Os contatos são comparados pelo endereço de e-mail, sem diferenciar maiúsculas de minúsculas.

Mais algumas coisas a saber:

• A lista de associação inclui Unsubscribed, mas a importação não aplica esse campo. Para marcar as pessoas importadas como descadastradas, selecione-as depois na página de contatos e use a ação em massa Unsubscribe.
• As importações não enviam eventos de webhook contact.* nem subscriber.* e não iniciam automações como Added to audience.
• Se uma lista for ultrapassar o limite de inscritos, a importação é rejeitada com o limite na mensagem, por exemplo “Pay as you go includes 10,000 subscribers per audience.” Consulte Listas de contatos.

Exportar contatos

1. Restrinja a lista. Em Email Marketing›Contacts, use a busca e Filter para mostrar os contatos que você quer. Sem busca nem filtros, a exportação inclui todos os contatos.

2. Exporte. Selecione Export e escolha CSV ou XLSX. O seu navegador baixa contacts.csv ou contacts.xlsx.

Uma exportação pode incluir até 10.000 contatos. Se mais contatos corresponderem, a exportação falha, então adicione filtros, como uma lista ou um intervalo de datas de criação, e exporte em partes.

O arquivo tem uma linha por contato e estas colunas:

Usar a API

A API não tem importação de arquivos. Para adicionar muitos contatos pelo código, chame Criar um contato para cada um, ou Adicionar um inscrito para criar o contato e a participação dele na lista em uma única chamada.

Ações em massa

POST /v2/contacts/bulk executa uma ação em até 100 contatos, informados pelo ID con_:

curl https://api.emailit.com/v2/contacts/bulk \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_to_audience",
    "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"],
    "audience_id": "aud_5hJ2kL8mNp4Qr"
  }'

{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"]
}

A requisição inteira falha se ids tiver mais de 100 entradas (400) ou se algum contato ou a lista não existir (404, com os IDs desconhecidos em missing). Para processar mais contatos, pagine com Listar contatos e envie lotes de 100.

Exportação

GET /v2/contacts/export retorna o mesmo arquivo que o painel. Defina format como csv (o padrão) ou xlsx e adicione qualquer filtro, busca e ordenação de Listar contatos:

curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_5hJ2kL8mNp4Qr&unsubscribed=false" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv

Se mais de 10.000 contatos corresponderem, o endpoint retorna 422 com “Export is limited to 10000 contacts. Narrow your filters and try again.”

Veja também