---
title: Contatos
description: As pessoas para quem você envia e-mail de marketing, com o estado de inscrição e propriedades personalizadas.
ai:
  exclude: true
---

Um contato é um endereço de e-mail na lista da sua equipe. Cada endereço aparece uma só vez (maiúsculas e minúsculas não contam), e você escolhe quem recebe uma transmissão com [segmentos](/docs/pt-br/concepts/segments) e [tópicos](/docs/pt-br/concepts/topics). Gerencie os contatos no painel, em **Contatos**, ou pela API.

## O que um contato armazena

- `email`: o endereço. Criar um segundo contato com o mesmo endereço retorna `409`. Um endereço que nunca pode receber e-mail (por exemplo `example.com`, um nome `.test` ou um domínio sem servidor de e-mail) retorna `422`.
- `first_name`, `last_name`.
- `unsubscribed`: o descadastro da equipe inteira. Enquanto for `true`, o contato não recebe e-mail de marketing de nenhum dos seus domínios. Só você o define; o descadastro feito pelo próprio destinatário nunca o altera.
- `unsubscribed_domains`: somente leitura. Os domínios dos quais o contato saiu por um link de descadastro, cada um com `domain_id`, `name` e `unsubscribed_at`. O e-mail desses domínios pula o contato, e seus outros domínios ainda chegam a ele. Veja [Descadastros](/docs/pt-br/concepts/unsubscribes).
- `verification_status` e `verified_at`: somente leitura. O resultado da última verificação completa do contato, `null` até ele ser verificado. Veja [Verificação](/docs/pt-br/concepts/verification).
- `properties`: valores personalizados como `plan: "pro"` ou `city: "Berlim"`. Os valores são texto ou número (objetos aninhados e listas retornam `422`), com no máximo 100 chaves por contato. As propriedades preenchem campos de mesclagem de modelos e filtros de segmentos. O `PATCH` mescla chave por chave, e um valor `null` remove a chave.

## Criar e consultar

`POST /contacts`, `GET /contacts`, `GET /contacts/{id}`, `PATCH /contacts/{id}` e `DELETE /contacts/{id}`. Em `{id}` você pode usar o id do contato ou o endereço de e-mail dele.

```sh
curl -X POST "https://api.billionsend.com/contacts" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@acme.com",
    "first_name": "Ana",
    "properties": { "plan": "pro" }
  }'
```

Acrescente `include=properties,topics` a `GET /contacts` ou `GET /segments/{id}/contacts` para receber, na mesma resposta, as propriedades e as escolhas de tópicos de cada contato. `POST /contacts/batch/get` lê até 1.000 contatos por id ou e-mail em uma chamada, na ordem do pedido; endereços sem correspondência aparecem em `missing`.

`PATCH /contacts/{id}/topics` define as escolhas de tópicos de um contato, e `GET /contacts/{id}/topics` as devolve com os padrões dos tópicos aplicados.

`POST /contacts/{id}/preferences-link` devolve um link para a página de preferências do contato, para você abri-la a partir de uma tela de configurações do seu produto. O link não expira e permite a quem o tem alterar as escolhas daquele contato, então entregue-o só ao próprio contato. Ele abre a página padrão da equipe e descadastra o contato de todos os domínios.

## Criação em lote

`POST /contacts/batch` recebe de 1 a 1.000 contatos em uma requisição e os grava juntos.

`on_conflict` define o que acontece quando um endereço já existe ou se repete no lote:

- `error` (padrão): aquele item falha com `409` (já existe) ou `422` (repetido).
- `skip`: o contato existente fica como está.
- `upsert`: o item é mesclado ao contato existente. Nomes só quando você os envia, propriedades chave por chave, segmentos acrescentados, tópicos atualizados.

Um lote nunca reinscreve ninguém: `unsubscribed: false` em um contato que já está descadastrado é ignorado. Para isso, use `PATCH /contacts/{id}`.

O cabeçalho `x-batch-validation` escolhe `strict` (padrão: um item inválido rejeita o lote todo) ou `permissive` (os itens válidos são gravados e as falhas vêm em `errors`).

```sh
curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
```

```json
{
  "data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
  "counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
  "errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}
```

## Exclusão em lote

`POST /contacts/batch/remove` exclui até 1.000 contatos por `ids` ou por `emails` (um dos dois) e devolve os que excluiu. Acrescente `erase: true` para também remover cada endereço do histórico de e-mails, dos payloads de eventos e dos logs da API. `DELETE /contacts/{id}?erase=true` faz o mesmo para um contato.

## Importação e exportação em CSV

No painel, **Contatos → Contatos** importa um CSV e exporta a visão atual (inclusive com filtro de segmento, tópico ou domínio) de volta para CSV. A exportação tem uma coluna `unsubscribed` e uma coluna `unsubscribed_domains` (`*` significa a equipe inteira). Linhas com um endereço que nunca pode receber e-mail são ignoradas. Em um plano pago, a janela de importação também pode verificar os novos endereços; veja [Verificação](/docs/pt-br/concepts/verification).

## Eventos

Cada alteração publica um evento de [webhook](/docs/pt-br/concepts/webhooks): `contact.created`, `contact.updated`, `contact.deleted`, `contact.unsubscribed`, `contact.resubscribed`, `contact.topic_opt_in` e `contact.topic_opt_out`.

## Limites

| | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Contatos por equipe | 1.000 | Sem limite |

Acima do limite, criar um contato retorna `403 plan_limit_reached`. Os contatos existentes continuam podendo ser atualizados.
