---
title: Descadastros e marcas
description: Os descadastros são guardados por domínio de envio, então cada marca tem a própria lista, a própria página de descadastro e o próprio host de links.
ai:
  exclude: true
---

Um descadastro quer dizer "chega de e-mail de marketing". O BillionSend o registra para o domínio de envio cujo e-mail trouxe o link, então uma equipe com várias marcas nunca mistura as listas. Quem sai de uma marca continua ouvindo das outras.

O e-mail transacional (enviado sem [tópico](/docs/pt-br/concepts/topics) e fora de uma [transmissão](/docs/pt-br/concepts/broadcasts)) nunca é afetado por um descadastro.

## Três escopos

| Escopo | Quem define | O que interrompe |
| --- | --- | --- |
| Domínio | O destinatário, com o link de descadastro ou o botão de um clique do cliente de e-mail | O e-mail de marketing do domínio que enviou aquele e-mail |
| Equipe inteira | Você, ao definir `unsubscribed` como `true` em um contato (API, painel ou importação de CSV) | O e-mail de marketing de todos os domínios da sua equipe |
| Tópico | O destinatário, na página de descadastro | Os e-mails enviados com aquele [tópico](/docs/pt-br/concepts/topics) |

O descadastro feito pelo próprio destinatário nunca altera o indicador `unsubscribed` do contato. Ele é guardado como um registro do domínio, identificado pelo endereço de e-mail, então sobrevive a excluir e reimportar o contato.

Transmissões e envios por tópico pulam o destinatário que saiu do domínio de envio, da equipe inteira ou do tópico. Um e-mail avulso interrompido assim termina `suppressed` com o motivo `domain_unsubscribed`, `contact_unsubscribed` ou `topic_unsubscribed`.

Descadastros não são [supressões](/docs/pt-br/concepts/suppressions). A lista de supressão guarda os endereços que deram bounce, reclamaram ou que você bloqueou, e interrompe todo e-mail, inclusive o transacional. Um descadastro interrompe só o e-mail de marketing.

## A página de descadastro

Toda transmissão e todo e-mail de tópico leva cabeçalhos `List-Unsubscribe` de um clique (RFC 8058) e um link para uma página de descadastro hospedada. Coloque `{{{UNSUBSCRIBE_URL}}}` em um corpo e ele vira o mesmo link para cada destinatário. A página abre no idioma do navegador do destinatário (catorze idiomas, com inglês como alternativa). Além de sair de todo o e-mail de marketing do domínio, o destinatário pode ligar e desligar tópicos individuais.

Quem clicou por engano pode apertar **Inscrever-me de novo** na página de confirmação. Isso desfaz só aquilo de que aquele link o descadastrou. Um scanner de e-mail que abre o link nunca reinscreve ninguém. Quando você mesmo define `unsubscribed: true`, a página não tem o botão de reinscrição.

### Cada domínio tem o próprio visual

A página tem a cara do domínio que enviou o e-mail. Cada domínio pode definir:

- um nome de marca, um logo e o arredondamento dos cantos do logo,
- as cores de fundo, de texto e de destaque,
- o texto acima do botão e o texto mostrado depois que a escolha é salva,
- uma URL de redirecionamento a abrir depois do descadastro, no lugar da mensagem na página.

No painel, abra o domínio e use a aba **Página de descadastro**, que mostra uma prévia. Um campo deixado em branco usa os **Padrões da marca** da equipe (Configurações) e, depois, o visual simples do BillionSend. A página mostra só o que pertence àquele domínio: nunca cita outro domínio da sua equipe e lista apenas os tópicos vinculados a ele mais os tópicos sem domínio.

Pela API, envie os campos em `unsubscribe_page` em `PATCH /domains/{id}`. Um `null` limpa um campo. O logo é enviado pelo painel e é somente leitura na API.

```sh
curl -X PATCH "https://api.billionsend.com/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribe_page": {
      "brand_name": "Acme",
      "message": "Que pena que você vai embora. Cancelar a inscrição nos e-mails da Acme?",
      "success_message": "Você saiu da lista da Acme.",
      "accent_color": "#0a7d5a",
      "logo_radius": "rounded"
    }
  }'
```

Um link feito fora de um e-mail, como o de `POST /contacts/{id}/preferences-link`, abre a página padrão da equipe, e o descadastro ali tira o contato de todos os domínios.

### Seu próprio subdomínio de descadastro

Por padrão, os links abrem em um host do BillionSend. Para abri-los no seu domínio, dê ao domínio um subdomínio de descadastro na aba Configuração dele, ou com `unsubscribe_subdomain` em `POST /domains` ou `PATCH /domains/{id}` (um rótulo como `unsubscribe` para `unsubscribe.seudominio.com`; `null` o limpa). Funciona como o subdomínio de rastreamento, veja [Domínios](/docs/pt-br/concepts/domains).

1. Adicione o CNAME que a aba Registros do domínio mostra, apontando para `cname.billiondns.com`, como somente DNS (nuvem cinza no Cloudflare).
2. O certificado é emitido automaticamente assim que o CNAME resolve, em geral em minutos. `unsubscribe_status` passa de `pending` para `active`, e `unsubscribe_error` diz por que isso não acontece.
3. Daí em diante, os e-mails novos usam o seu host no link e no cabeçalho `List-Unsubscribe`. Enquanto ele não estiver ativo, e depois de um resultado `failed` (72 horas sem ativar), usa-se o host compartilhado.

Um link já enviado mantém o host com que foi enviado, então para de funcionar se você remover o CNAME depois. Um subdomínio seu abre só os links do próprio domínio; qualquer outro link responde `404`.

Você pode usar o mesmo rótulo para rastreamento e descadastro, mas nomes separados são mais seguros: bloqueadores de anúncios bloqueiam os hosts de rastreamento, e um nome compartilhado derrubaria junto o link de descadastro.

## Ler e alterar descadastros

`GET /contacts/{id}` devolve `unsubscribed` (o indicador da equipe inteira) e `unsubscribed_domains`. No painel, a página de um contato lista os dois e permite remover o descadastro de um domínio. A aba **Descadastros**, em Contatos, lista todos os registros.

```sh
# Listar, do mais novo ao mais antigo. domain_id restringe a um domínio.
curl "https://api.billionsend.com/unsubscribes?domain_id=$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..."

# Registrar um descadastro de um domínio (sem domain_id, vale para todos os domínios)
curl -X POST "https://api.billionsend.com/unsubscribes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.org", "domain_id": "'"$DOMAIN_ID"'" }'

# Remover um registro
curl -X DELETE "https://api.billionsend.com/unsubscribes/$UNSUBSCRIBE_ID" \
  -H "Authorization: Bearer bs_..."
```

Um registro com `domain_id` e `domain` ambos `null` descadastra o endereço de todos os domínios. O `POST` é idempotente: um registro existente volta sem alteração. As mesmas chamadas existem como as ferramentas MCP `list_unsubscribes`, `add_unsubscribe` e `delete_unsubscribe`.

O que desfaz o quê:

- `PATCH /contacts/{id}` com `unsubscribed: false` desfaz só o descadastro da equipe inteira. Os descadastros de domínios específicos permanecem.
- `DELETE /unsubscribes/{id}` remove aquele registro.

Se você excluir um domínio e o adicionar de novo com o mesmo nome, os descadastros dos destinatários voltam a valer.

### Quem pode alterá-los

Proprietários, administradores e membros de marketing, e chaves de API de acesso total, podem registrar descadastros. Só proprietários e administradores podem desfazer um. Veja [Funções da equipe](/docs/pt-br/team-roles).

Uma chave de API limitada a um domínio gerencia só os descadastros desse domínio: os outros domínios retornam `403 restricted_api_key`.

## Importar uma lista de um CSV

Para trazer uma lista de descadastros de outro provedor, abra **Contatos → Descadastros** no painel e escolha **Importar CSV**.

```csv
email,domain
ada@example.com,
grace@example.com,news.example.org
alan@example.com,*
```

- `email` é obrigatório. `domain` é opcional. A linha de cabeçalho também é opcional.
- `domain` é um dos seus domínios e limita o descadastro ao e-mail dele. `*` significa todos os domínios. Uma célula vazia usa o **Domínio padrão** que você escolhe na janela.
- Uma linha com domínio desconhecido ou endereço inválido é ignorada.

A janela mostra quantos descadastros foram adicionados, quantos já existiam e por que linhas foram ignoradas. Importar o mesmo arquivo duas vezes é seguro.

## Eventos

O descadastro de um destinatário dispara `contact.unsubscribed` com `source` igual a `hosted_page` ou `one_click`, mais `domain_id` e `domain_name` (ambos `null` para um descadastro da equipe inteira). Desfazê-lo dispara `contact.resubscribed`. Veja [Webhooks](/docs/pt-br/concepts/webhooks).

## Limites

| | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Visual da página de descadastro (logo, cores, fonte, arredondamento do logo) | Visual padrão | Visual próprio por domínio |
| Subdomínio de descadastro próprio | Não (host compartilhado) | Sim |
| "Powered by BillionSend" na página | Exibido | Oculto |

No Free, definir um subdomínio retorna `403 plan_limit_reached`. Você pode salvar um visual para a página, mas os destinatários veem o visual padrão até você fazer upgrade. Depois de um downgrade, os visuais salvos são mantidos e voltam a valer no upgrade, e os subdomínios que você já definiu continuam funcionando.
