---
title: Segmentos
description: Filtros salvos sobre seus contatos, usados como público de transmissões.
ai:
  exclude: true
---

Um segmento é um grupo salvo de contatos para o qual você pode enviar uma [transmissão](/docs/pt-br/concepts/broadcasts). Crie segmentos no painel, em **Contatos → Segmentos**, ou pela API.

Há dois tipos:

- **Segmento por filtro.** Ele guarda um filtro, não uma lista de pessoas. Um contato que passa a corresponder ao filtro já está no segmento, e a contagem de contatos é calculada na hora em que você a lê.
- **Segmento manual.** Criado sem filtro. Você adiciona e remove contatos por conta própria, no painel ou com `POST /contacts/{id}/segments/{segmentId}` e `DELETE /contacts/{id}/segments/{segmentId}`.

Um filtro pode testar o e-mail, o nome, o estado de inscrição e a data de criação do contato, além de qualquer [propriedade personalizada](/docs/pt-br/concepts/contacts). Os operadores incluem igual, contém, definido, não definido e comparações de data, e as condições se combinam com e/ou.

## Usando um segmento

- **Transmissões.** Escolha um segmento como público. Quem recebe o e-mail é calculado no momento do envio, com o mesmo filtro da contagem que você viu antes. Contatos descadastrados na equipe inteira, ou que saíram do domínio de envio da transmissão, ficam sempre de fora.
- **Visão de contatos.** Filtre a lista por segmento. A exportação em CSV segue o mesmo filtro.

```sh
curl -X POST "https://api.billionsend.com/segments" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Usuários em teste",
    "filter": { "match": "all", "conditions": [{ "field": "property:plan", "op": "equals", "value": "trial" }] }
  }'
```

`GET /segments/{id}` inclui o `contact_count` ao vivo, e `GET /segments/{id}/contacts` lista os membros. Um filtro inválido retorna `422` e nunca é salvo.

## Um segmento por marca

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

- Uma transmissão para um segmento vinculado deve ser enviada desse domínio. De qualquer outro, as chamadas de transmissão retornam `422`.
- Um segmento sem domínio funciona com todos os domínios. `"domain_id": null` torna o segmento vinculado válido para a equipe inteira de novo.
- Um domínio não pode ser excluído enquanto houver segmentos vinculados a ele (`409`).

Os [tópicos](/docs/pt-br/concepts/topics) podem ser vinculados da mesma forma. Juntos, eles mantêm separados o público, os tópicos e os descadastros de cada marca; veja [Descadastros](/docs/pt-br/concepts/unsubscribes).

## Chaves de API limitadas a um domínio

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