# Contatos

> Os contatos são as pessoas do seu workspace. Veja como contatos, listas de contatos e inscritos se relacionam, o que a lista e o perfil de contatos mostram e como funcionam os descadastros.

Um contato é uma pessoa no seu workspace, identificada pelo endereço de e-mail. Os contatos guardam os nomes e os valores de campos personalizados que você usa para personalizar campanhas, e participam de listas de contatos, que são as listas para as quais as campanhas são enviadas. Esta página explica como essas peças se encaixam e o que você pode fazer com contatos no painel e na API.

## Contatos, listas e inscritos

O Emailit mantém pessoas e listas separadas. Uma pessoa existe uma única vez como contato, e cada lista em que ela está é um registro de inscrito separado, com o seu próprio estado de opt-in.

| | Contato | Lista de contatos | Inscrito |
| --- | --- | --- | --- |
| **O que é** | Uma pessoa | Uma lista nomeada para a qual você envia campanhas | A participação de um contato em uma lista |
| **Prefixo do ID** | `con_` | `aud_` | `sub_` |
| **Único por** | Endereço de e-mail, por workspace | Nome, por workspace | Um por contato por lista |
| **Contém** | E-mail, nome, sobrenome, campos personalizados, status de marketing | Nome, número de inscritos, URL de inscrição | Um indicador **Subscribed** com as datas de inscrição e de descadastro |
| **Ao excluir** | Também remove o contato de todas as listas | Remove todos os inscritos dela. Os contatos continuam. | Remove essa participação. O contato continua. |

```text
Workspace
├── Contacts ────────────── one per email address
│   ├── email, first_name, last_name, custom_fields
│   └── marketing status (unsubscribed: true | false)
└── Audiences ───────────── named lists, for example "Newsletter"
    └── Subscribers ─────── one per contact on the list
        └── subscribed: true | false
```

Na prática:

- Um contato pode ser inscrito de muitas listas, com um indicador **Subscribed** separado em cada uma.
- Adicionar alguém a uma lista pelo e-mail cria o contato primeiro, se ele ainda não existir.
- Os nomes e os campos personalizados ficam no contato. Editá-los a partir de uma lista altera o contato, então a alteração aparece em todos os lugares.

### Quem recebe uma campanha

Uma campanha é enviada a todos os contatos que atendem às três condições:

1. O contato é inscrito de pelo menos uma das listas da campanha, com **Subscribed** ativado.
2. O status de marketing do contato é **Subscribed**.
3. O endereço não está na sua [lista de supressão](/pt/docs/suppressions/).

Um contato que está em várias das listas selecionadas recebe uma única cópia. Consulte [Criar uma campanha](/pt/docs/campaigns/create/) para as regras completas.

## Status de marketing

Todo contato também tem um **Marketing status** válido para todo o workspace: **Subscribed** ou **Unsubscribed** (o campo `unsubscribed` na API). Ele é um descadastro global que fica acima do indicador de cada lista.

| O que você altera | Como | Efeito nas campanhas |
| --- | --- | --- |
| Status de marketing | **Unsubscribe** ou **Resubscribe** em massa na página de contatos, ou `unsubscribed` na API | Os contatos **Unsubscribed** são ignorados em todas as listas. As participações deles nas listas não mudam. |
| A inscrição em uma lista | **Unsubscribe** ou **Resubscribe** na página do contato ou na lista, ou `subscribed` no inscrito | O contato é ignorado apenas nas campanhas para essa lista. |
| O destinatário clica no link de descadastro | A página de descadastro hospedada | O contato é descadastrado de todas as listas a que pertence. |

O status de marketing e as inscrições em listas controlam apenas as campanhas. Eles não bloqueiam os e-mails que você envia com a API ou por SMTP, nem os e-mails enviados por automações. Para interromper todos os e-mails para um endereço, adicione-o às suas [supressões](/pt/docs/suppressions/). [Descadastros](/pt/docs/audiences/unsubscribes/) explica todas as formas de descadastro.

## A página de contatos

Abra **Email Marketing → Contacts** para ver todos os contatos do workspace, dos mais recentes para os mais antigos.

- **Colunas.** **Email** sempre aparece. Ative ou desative **First name**, **Last name**, **Audiences**, **Created** e **Updated** em **Display options > Edit columns**, ou selecione **Show full name** para juntar os nomes em uma única coluna **Name**. Na coluna **Audiences**, o selo de cada lista fica verde enquanto o contato está inscrito nela e vermelho depois que ele se descadastra.
- A **busca** procura no e-mail, no nome e no sobrenome.
- **Filtre** por Email, Name, First name, Last name, Unsubscribed, Created, Updated, Audiences ou Audience, e por qualquer [campo personalizado](/pt/docs/contacts/custom-fields/). Com dois ou mais filtros, escolha se o contato precisa atender a todos ou a qualquer um deles.
- **Ordene** selecionando o cabeçalho de uma coluna.
- **Import** e **Export** trazem e levam contatos como arquivos. Consulte [Importar e exportar contatos](/pt/docs/contacts/import-export/).

Selecione uma linha para abrir o contato. O menu da linha tem **Edit** e **Delete**.

### Adicionar um contato

Selecione **Add contact** e digite o **Email** e, opcionalmente, **First name**, **Last name** e **Audiences**. Selecione **Show custom fields** para preencher os valores dos campos personalizados. Um endereço de e-mail só pode existir uma vez por workspace, então adicionar um endereço existente falha.

Para alterar um contato depois, selecione **Edit**. Você pode alterar os nomes e os campos personalizados. O endereço de e-mail não pode ser alterado no painel. Use o campo `email` de [Atualizar um contato](/pt/docs/api-reference/contacts/update/).

### Ações em massa

Selecione os contatos com as caixas de seleção (a caixa do cabeçalho seleciona a página inteira) e abra **Actions**. Cada ação se aplica a até 100 contatos por vez.

| Ação | O que faz |
| --- | --- |
| **Add to audience** | Adiciona os contatos à lista que você escolher. As participações existentes continuam como estão. Os contatos com status de marketing **Unsubscribed** entram como inscritos descadastrados. |
| **Remove from audience** | Exclui a participação deles na lista que você escolher. Os contatos continuam. |
| **Unsubscribe** | Define o status de marketing deles como **Unsubscribed**. |
| **Resubscribe** | Define o status de marketing deles de volta como **Subscribed**. As inscrições nas listas não mudam. |
| **Delete** | Exclui os contatos e todas as participações deles. Essa ação não pode ser desfeita. |

## A página do contato

A página do contato mostra tudo o que o Emailit sabe sobre uma pessoa. Use **Edit** e **Delete** no topo.

| Seção | O que mostra |
| --- | --- |
| **Details** | E-mail, nome, sobrenome, status de marketing, datas de criação e de atualização. |
| **Custom fields** | Todos os campos personalizados definidos no workspace e o valor do contato. |
| **Metrics and Insights** | **Emails sent**, **Loads**, **Clicks**, **Last activity**, **Subscribed audiences** (listas em que está inscrito, em relação ao total) e **Marketing status**. As contagens incluem todos os e-mails de saída enviados ao endereço, não apenas as campanhas. |
| **Audiences** | Cada lista a que o contato pertence, com o status e as datas de inscrição e de descadastro. O menu da linha pode descadastrar (**Unsubscribe**) ou reinscrever (**Resubscribe**) o contato nessa lista, ou removê-lo dela (**Remove from audience**). **Add to audience** adiciona uma nova participação. |
| **Sent emails** | Os e-mails de saída enviados ao endereço, com assunto, status, campanha, carregamentos, cliques e horário de envio. |
| **Activity log** | Uma linha do tempo de eventos do contato, como “Contact created”, “Added to Newsletter”, “Unsubscribed from Newsletter” e “Email delivered”. |

## Usar a API

A [API de contatos](/pt/docs/api-reference/contacts/) cobre tudo o que a lista e o perfil fazem, exceto a importação de arquivos:

- [Crie](/pt/docs/api-reference/contacts/create/), [obtenha](/pt/docs/api-reference/contacts/get/), [atualize](/pt/docs/api-reference/contacts/update/), [liste](/pt/docs/api-reference/contacts/list/) e [exclua](/pt/docs/api-reference/contacts/delete/) contatos. Onde um ID for esperado, você pode passar o endereço de e-mail do contato em vez do ID `con_` dele.
- Passe `audiences` (um array de IDs `aud_`) ao criar um contato para inscrevê-lo na hora. Na atualização, `audiences` substitui as participações do contato.
- [Execute uma ação em massa](/pt/docs/api-reference/contacts/bulk/) em até 100 contatos e [exporte](/pt/docs/api-reference/contacts/export/) até 10.000 como CSV ou XLSX.

```bash
curl https://api.emailit.com/v2/contacts \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Acme", "plan": "pro" },
    "audiences": ["aud_2kq8Vt4xLm7Rz"]
  }'
```

Criar um contato com um e-mail que já existe retorna `409` com o contato existente em `existing`. A API de contatos exige uma chave de API com **Full Access**.

As alterações em contatos geram os eventos [`contact.created`, `contact.updated` e `contact.deleted`](/pt/docs/webhooks/events/contact/), e as alterações nas participações geram eventos [`subscriber.*`](/pt/docs/webhooks/events/subscriber/), que você pode receber com [webhooks](/pt/docs/webhooks/).

## Próximos passos

  - [Campos personalizados](/pt/docs/contacts/custom-fields/): Guarde dados extras nos contatos e use-os em filtros e e-mails.
  - [Importar e exportar](/pt/docs/contacts/import-export/): Traga contatos de um arquivo CSV ou Excel e baixe-os.
  - [Listas de contatos](/pt/docs/audiences/): Agrupe contatos em listas para as quais você pode enviar campanhas.
  - [Descadastros](/pt/docs/audiences/unsubscribes/): Como os descadastros funcionam e como respeitá-los.

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