# Importar e exportar contatos

> Importe contatos de um arquivo CSV ou Excel com o assistente de importação, exporte os contatos filtrados para CSV ou XLSX e execute ações em massa e exportações com a API.

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](/pt/docs/contacts/custom-fields/) que você quer preencher a partir do arquivo. O assistente só consegue associar colunas a campos que já existem.
- Crie as [listas de contatos](/pt/docs/audiences/) 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](/pt/docs/workspaces/production-access/).

## 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.

```csv title="contacts.csv"
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.

| Caso | Resultado |
| --- | --- |
| O endereço é novo | Um contato é criado. |
| O endereço já existe | O contato é atualizado. Os nomes só são sobrescritos quando o arquivo tem um valor. Os valores de campos personalizados do arquivo substituem os armazenados, e uma célula em branco em uma coluna associada a um campo personalizado limpa esse campo. Os outros campos personalizados são mantidos. |
| O endereço aparece duas vezes no arquivo | As duas linhas são aplicadas em ordem, então a última prevalece. |
| O contato ainda não está na lista selecionada | Ele entra na lista como inscrito. |
| O contato tinha se descadastrado da lista selecionada | Ele é inscrito nessa lista de novo. |

> **As importações reinscrevem as pessoas:** Importar um contato para uma lista da qual ele se descadastrou o inscreve de novo. Antes de importar para uma lista existente, remova do arquivo as pessoas que pediram para sair, ou importe sem escolher essa lista.

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](/pt/docs/audiences/#limits).

## 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:

| Coluna | Valor |
| --- | --- |
| `email` | O endereço de e-mail do contato. |
| `first_name`, `last_name` | O nome e o sobrenome do contato. |
| `unsubscribed` | `true` se o status de marketing for **Unsubscribed**; caso contrário, `false`. |
| `audiences` | Os nomes de todas as listas a que o contato pertence, separados por `; `. |
| Uma coluna por chave de campo personalizado | O valor armazenado. Os valores de seleção múltipla são unidos com `;`. |
| `created_at`, `updated_at` | Timestamps ISO 8601. |

## Usar a API

A API não tem importação de arquivos. Para adicionar muitos contatos pelo código, chame [Criar um contato](/pt/docs/api-reference/contacts/create/) para cada um, ou [Adicionar um inscrito](/pt/docs/api-reference/audiences/subscribers/add/) para criar o contato e a participação dele na lista em uma única chamada.

### Ações em massa

[`POST /v2/contacts/bulk`](/pt/docs/api-reference/contacts/bulk/) executa uma ação em até 100 contatos, informados pelo ID `con_`:

| `action` | Efeito | Exige `audience_id` |
| --- | --- | --- |
| `add_to_audience` | Adiciona os contatos à lista. Os contatos com `unsubscribed: true` entram como descadastrados. | Sim |
| `remove_from_audience` | Exclui a participação deles na lista. | Sim |
| `unsubscribe` | Define `unsubscribed: true` (status de marketing **Unsubscribed**). | Não |
| `resubscribe` | Define `unsubscribed: false`. | Não |
| `delete` | Exclui os contatos e as participações deles. | Não |

```bash
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"
  }'
```

```json
{
  "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](/pt/docs/api-reference/contacts/list/) e envie lotes de 100.

### Exportação

[`GET /v2/contacts/export`](/pt/docs/api-reference/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](/pt/docs/api-reference/contacts/list/):

```bash
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

  - [Campos personalizados](/pt/docs/contacts/custom-fields/): Defina os campos aos quais as suas colunas são associadas.
  - [Inscritos](/pt/docs/audiences/subscribers/): Gerencie quem está em cada lista.

---
Fonte: https://emailit.com/pt/docs/contacts/import-export/