---
title: Tópicos
description: Categorias de inscrição que deixam o destinatário escolher o que recebe.
ai:
  exclude: true
---

Um tópico é uma categoria de e-mail, como "Novidades do produto", "Newsletter" ou "Promoções". O destinatário pode sair de um tópico e continuar inscrito nos outros. Gerencie os tópicos no painel, em **Contatos → Tópicos**, ou pela API.

Cada tópico tem um `default_subscription`, definido na criação e que não muda depois:

- `opt_in`: todo contato está inscrito, a menos que opte por sair.
- `opt_out`: o contato só está inscrito depois de optar por entrar.

Um tópico também tem uma `visibility`. Um tópico `public` aparece na página de descadastro, e um `private` só aparece pelo link próprio dele.

## Como os tópicos se aplicam

- **Transmissões.** Uma transmissão pode ter um tópico como alvo. Ela vai para os contatos inscritos naquele tópico (a escolha do próprio contato ou o padrão do tópico). Contatos descadastrados na equipe inteira, ou que saíram do domínio de envio, ficam sempre de fora.
- **E-mails avulsos.** Envie um e-mail com `topic_id` e ele respeita aquele tópico. Se todos os endereços de `to` tiverem optado por sair, o envio retorna `422 all_recipients_suppressed`.
- **Página de descadastro.** A página lista os tópicos públicos, então o destinatário pode desativar um deles ou sair de todo o e-mail de marketing daquele domínio. O e-mail enviado sem `topic_id` e fora de uma transmissão nunca é afetado. Veja [Descadastros](/docs/pt-br/concepts/unsubscribes).

Um tópico usado por uma transmissão, ou por um e-mail ainda à espera de envio, não pode ser excluído: a chamada retorna `409 conflict` até que eles tenham saído ou sido cancelados.

```sh
curl -X POST "https://api.billionsend.com/topics" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Novidades do produto", "default_subscription": "opt_in" }'
```

Você define as escolhas de um contato com `PATCH /contacts/{id}/topics`, enviando entradas como `{ "id": "<topic-id>", "subscription": "opt_in" }`. `GET /contacts/{id}/topics` lista todos os tópicos com a `subscription` do contato e um indicador `explicit` (falso quando é o padrão do tópico).

## Um tópico por marca

Se cada um dos seus domínios é uma marca própria, vincule o tópico ao domínio a que ele pertence definindo `domain_id`, ao criá-lo ou depois com `PATCH /topics/{id}`, ou escolhendo o domínio no painel.

- Um tópico vinculado aparece só na página de descadastro desse domínio. A página de nenhum outro domínio mostra o nome dele.
- Um envio com esse `topic_id` deve sair desse domínio. De qualquer outro, `POST /emails` e as chamadas de transmissão retornam `422`.
- Um tópico sem domínio aparece na página de todos os domínios e pode ser enviado de qualquer um. `"domain_id": null` torna o tópico vinculado válido para a equipe inteira de novo.
- Um domínio não pode ser excluído enquanto houver tópicos vinculados a ele (`409`).

Os [segmentos](/docs/pt-br/concepts/segments) podem ser vinculados da mesma forma.

## Chaves de API limitadas a um domínio

Uma chave de API limitada a um domínio só cria tópicos vinculados a esse domínio e não pode torná-los válidos para a equipe inteira.
