# Segmentos API

> Salve filtros sobre os seus contatos, liste quem corresponde a eles e acompanhe os segmentos rastreados ao longo do tempo.

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar um segmento — POST /segments

> Crie um segmento, um filtro salvo sobre os seus contatos a partir de todos os contatos ou de listas escolhidas, e escolha se ele é rastreado. Alfa: aberto apenas à equipe do Emailit.

# Criar um segmento

Cria um segmento: um filtro salvo sobre os contatos do workspace. Requer uma chave de API com escopo `full`.

Um segmento contém os contatos da sua origem (os inscritos de `audience_ids`, ou todos os contatos quando ele estiver vazio) que correspondem às suas `conditions`. A participação é avaliada em tempo real sempre que o segmento é contado, listado, pré-visualizado ou usado por uma campanha que está sendo enviada. Consulte [Segmentos](/pt/docs/segments/).

Cada plano inclui um número de segmentos por workspace, rastreados ou não. Consulte [Limites](/pt/docs/limits/#plan-limits).

`POST /segments`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros do corpo

- `name` (string, obrigatório): Nome do segmento, com até 191 caracteres.

- `description` (string | null): Observação para a sua equipe, com até 1.000 caracteres.

- `audience_ids` (string[]): A origem: IDs de listas de contatos (`aud_…`) deste workspace, até 100. O segmento só contém contatos inscritos em pelo menos uma delas. Vazio ou omitido significa todos os contatos do workspace.

- `conditions` (object): As regras às quais os contatos devem corresponder, descritas em [Condições](#conditions). Omita-o para incluir todos da origem.

- `tracked` (boolean): Armazena os membros do segmento para que as entradas e saídas de contatos se tornem eventos para [automações](/pt/docs/automations/triggers/#segment-triggers) e [webhooks](/pt/docs/webhooks/event-types/#segment-events). Incluído nos planos Pro, Business e Custom. Você o escolhe aqui e não pode mudá-lo depois. Consulte [Segmentos rastreados](/pt/docs/segments/tracked/).

## Condições

`conditions` contém grupos de regras. O `match` de nível superior combina os grupos, e o `match` de cada grupo combina as regras dele:

```json
{
  "match": "all",
  "groups": [
    { "match": "any", "rules": [{ "field": "email_domain", "operator": "in", "value": ["acme.com", "globex.io"] }] },
    { "match": "all", "rules": [{ "field": "status", "operator": "equals", "value": "subscribed" }] }
  ]
}
```

- `match` é `all` (padrão) ou `any`, no nível superior e em cada grupo.
- Omita `conditions`, ou não envie grupos, para incluir todos da origem. Os grupos vazios são descartados.
- O formato plano `{ "match": "any", "rules": [...] }` também é aceito e armazenado como um único grupo.
- Um segmento pode ter até 10 grupos e 50 regras no total.

### Campos

| Campo | Tipo | Observações |
| --- | --- | --- |
| `email` | string | |
| `email_domain` | string | A parte do endereço depois de `@`. |
| `first_name`, `last_name` | string | |
| `status` | enum | `subscribed` (não descadastrado globalmente e inscrito em pelo menos uma lista, para que as campanhas possam alcançar o contato) ou `unsubscribed`. Operadores: `equals`, `not_equals`. |
| `created_at`, `updated_at` | datetime | Quando o contato foi criado ou alterado pela última vez, comparado em UTC. |
| `audience` | audience | Participação como inscrito. `in` corresponde aos contatos inscritos em qualquer um dos IDs de lista, e `not_in`, aos contatos que não estão inscritos em nenhum deles. |
| `tags` | tags | As [tags](/pt/docs/contacts/tags-and-score/) do contato. Os valores são comparados em minúsculas. |
| `score` | score | A [pontuação de lead](/pt/docs/contacts/tags-and-score/#lead-score) do contato. |
| `custom_fields.<key>` | depende do campo | Os campos de texto são `string`, os de número `number`, os de data `date` (`YYYY-MM-DD`), os booleanos `boolean`, os de seleção `enum` e os de seleção múltipla `multi`. |
| `orders_count`, `total_spent`, `average_order_value` | metric | Calculados a partir dos [pedidos](/pt/docs/commerce/) do contato. 0 para contatos sem pedidos. Os valores estão na moeda dos pedidos do contato. |
| `first_order_at`, `last_order_at` | moment | Sem valor para contatos sem pedidos. |
| `expected_next_order_at` | moment | O último pedido mais o intervalo médio do contato entre pedidos. Tem valor a partir do segundo pedido e pode estar no futuro. |
| `churn_risk` | enum | `low`, `medium` ou `high`: o tempo desde o último pedido comparado com o intervalo habitual do contato (no mínimo 14 dias), ou com 90 dias para quem comprou uma única vez. Sem valor se não houver pedidos. |
| `last_active_at` | moment | A última vez que o [script de rastreamento](/pt/docs/commerce/connect-your-shop/#the-tracking-script) viu o contato no seu site. |
| `purchased` | purchase | Pedidos; consulte [Regras de atividade](#activity-rules). |
| `viewed_product` | view | Visualizações de produtos registradas pelo script de rastreamento. |
| `cart` | cart | Carrinhos abertos e abandonados. |
| `used_coupon` | coupon | Pedidos que usaram um código de cupom. |
| `campaign_activity` | campaign_activity | E-mails de campanha recebidos, abertos ou clicados. |

[Listar os campos de segmentos](/pt/docs/api-reference/segments/fields/) retorna os campos do seu workspace, incluindo os campos personalizados e as listas de contatos dele, com os operadores que cada um aceita.

### Operadores

| Tipo | Operadores |
| --- | --- |
| string | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `in`, `not_in`, `is_set`, `is_not_set` |
| number | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between`, `is_set`, `is_not_set` |
| date | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago`, `in_next_days`, `is_set`, `is_not_set` |
| datetime | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago` |
| boolean | `is_true`, `is_false`, `is_set`, `is_not_set` |
| enum | `in`, `not_in`, `is_set`, `is_not_set` |
| multi | `in` (tem qualquer um de), `contains_all` (tem todos de), `not_in` (não tem nenhum de), `is_set`, `is_not_set` |
| audience | `in`, `not_in` |
| tags | `in` (tem qualquer uma de), `contains_all` (tem todas de), `not_in` (não tem nenhuma de), `is_set` (tem alguma tag), `is_not_set` (não tem tags) |
| score | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between` |
| metric | `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `between` |
| moment | `on`, `before`, `after`, `between`, `in_last_days`, `more_than_days_ago`, `in_next_days`, `is_set`, `is_not_set` |
| purchase, view, coupon | `has`, `has_not` |
| cart | `has_open_cart`, `has_abandoned_cart`, `has_no_open_cart` |
| campaign_activity | `received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked`, `received_not_opened`, `received_not_clicked` |

### Valores

- As comparações de texto em campos string não diferenciam maiúsculas de minúsculas. Os valores de seleção e de seleção múltipla devem corresponder exatamente.
- `not_equals`, `not_contains` e `not_in` também correspondem a contatos que não têm valor.
- `in`, `not_in` e `contains_all` recebem uma lista de até 100 valores. Os valores de texto podem ter até 500 caracteres.
- `between` recebe `[from, to]`, com os dois extremos incluídos: dois números ou duas datas `YYYY-MM-DD`.
- `on`, `before` e `after` recebem uma data `YYYY-MM-DD`. `before` e `after` não incluem esse dia.
- `in_last_days`, `more_than_days_ago` e `in_next_days` recebem um número inteiro de dias de 1 a 3650, contado a partir do momento em que o segmento é avaliado. Os campos personalizados de data comparam dias do calendário em UTC; `created_at` e `updated_at` usam horários exatos, então `in_last_days` com `7` significa as últimas 7 × 24 horas.
- `is_set`, `is_not_set`, `is_true` e `is_false` não recebem valor. `is_true` corresponde a `true`, `1`, `yes` e `on`; `is_false` corresponde a `false`, `0`, `no` e `off`.
- Uma regra salva que não se aplica mais, por exemplo depois que o campo personalizado dela mudou de tipo, não corresponde a nenhum contato. As regras sobre um campo personalizado excluído continuam funcionando com os valores que os contatos ainda têm, mas as novas regras devem usar um campo existente.

### Regras de atividade

`purchased`, `viewed_product`, `cart`, `used_coupon` e `campaign_activity` recebem um objeto como `value`. Todas as chaves são opcionais.

| Campo | Chaves do valor |
| --- | --- |
| `purchased` | `days`: só os pedidos feitos nos últimos N dias. `product_ids`: pedidos com qualquer um destes produtos (os IDs de produto da sua loja). `categories`: pedidos com um produto em qualquer uma destas categorias. `min_count`: pelo menos este número de pedidos correspondentes (padrão 1, até 1.000). Os pedidos cancelados não contam. |
| `viewed_product` | `days`, `product_ids`, `categories` e `min_count`, como acima, contando as visualizações de produtos. |
| `cart` | `days`, só com `has_abandoned_cart`: carrinhos abandonados nos últimos N dias. `has_open_cart` corresponde a um carrinho ativo, e `has_no_open_cart`, aos contatos sem carrinho ativo ou abandonado. |
| `used_coupon` | `days` e `coupon`: a chave de um [cupom](/pt/docs/commerce/coupons/). Sem `coupon`, qualquer código conta. |
| `campaign_activity` | `campaign_id`: uma campanha (`cmp_...`), ou qualquer campanha quando ausente. `days`: só os últimos N dias, ou todo o período quando ausente. |

`days` é um número inteiro de 1 a 3650. `has_not` é o oposto de `has` com o mesmo valor.

```json
{
  "match": "all",
  "groups": [
    { "match": "all", "rules": [
      { "field": "purchased", "operator": "has", "value": { "categories": ["Shoes"], "days": 180 } },
      { "field": "churn_risk", "operator": "in", "value": ["medium", "high"] },
      { "field": "campaign_activity", "operator": "clicked", "value": { "days": 90 } }
    ] }
  ]
}
```

`received_not_opened` e `received_not_clicked` correspondem aos contatos que receberam pelo menos um e-mail de campanha correspondente e não abriram nenhum deles (ou não clicaram em nenhum deles, respectivamente). As aberturas são aproximadas: o Apple Mail carrega as imagens de todos os e-mails que recebe.

## Retorno

Retorna `201 Created` com o [objeto de segmento](/pt/docs/api-reference/segments/get/), incluindo `contacts_count` e `subscribed_count`. Um novo segmento rastreado começa com `tracking.status` definido como `syncing` enquanto o Emailit registra os membros atuais dele.

| Status | Quando |
| --- | --- |
| `400` | `name` está ausente, ou um campo tem o tipo errado. |
| `403` | `tracked` é `true` e o plano não inclui segmentos rastreados. O corpo é `{"error": "plan_required", "required_plan": "pro", ...}`. |
| `422` | Um campo ou uma regra é inválido: `errors` é indexado pelo caminho dele, como `conditions.groups.0.rules.1.value`, e `message` repete o primeiro problema. Também é retornado quando o workspace atingiu o limite de segmentos do plano; esse corpo inclui `usage.used` e `usage.limit`. |

**Requisição** `POST /segments`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro customers renewing soon",
    "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
    "conditions": {
      "match": "all",
      "groups": [{
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }]
    },
    "tracked": true
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Pro customers renewing soon',
    audience_ids: ['aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a'],
    conditions: {
      match: 'all',
      groups: [{
        match: 'all',
        rules: [
          { field: 'custom_fields.plan', operator: 'in', value: ['pro', 'enterprise'] },
          { field: 'custom_fields.renews_on', operator: 'in_next_days', value: 30 },
        ],
      }],
    },
    tracked: true,
  }),
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "Pro customers renewing soon",
        "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
        "conditions": {
            "match": "all",
            "groups": [{
                "match": "all",
                "rules": [
                    {"field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"]},
                    {"field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30},
                ],
            }],
        },
        "tracked": True,
    },
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'Pro customers renewing soon',
        'audience_ids' => ['aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a'],
        'conditions' => [
            'match' => 'all',
            'groups' => [[
                'match' => 'all',
                'rules' => [
                    ['field' => 'custom_fields.plan', 'operator' => 'in', 'value' => ['pro', 'enterprise']],
                    ['field' => 'custom_fields.renews_on', 'operator' => 'in_next_days', 'value' => 30],
                ],
            ]],
        ],
        'tracked' => true,
    ],
]);
$segment = json_decode($response->getBody(), true);
```

**201**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": null,
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "syncing",
    "synced_at": null
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-18T12:00:00.000000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}
```

**403**

```json
{
  "error": "plan_required",
  "message": "Tracked segments are included with Pro and Business.",
  "required_plan": "pro"
}
```

**422 Validação**

```json
{
  "message": "Validation failed. conditions.groups.0.rules.1.value: Enter a whole number of days between 1 and 3650.",
  "errors": {
    "conditions.groups.0.rules.1.value": [
      "Enter a whole number of days between 1 and 3650."
    ]
  }
}
```

**422 Limite**

```json
{
  "error": "Pay as you go includes 3 segments.",
  "message": "Pay as you go includes 3 segments.",
  "usage": {
    "used": 3,
    "limit": 3
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/create/

## Obter um segmento — GET /segments/{id}

> Obtenha um segmento com a origem, as regras, o estado do rastreamento e as contagens de contatos em tempo real. Alfa: aberto apenas à equipe do Emailit.

# Obter um segmento

Obtém um segmento e conta os contatos dele no momento da chamada. Requer uma chave de API com escopo `full`.

`GET /segments/{id}`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do segmento (`seg_…`).

## Retorno

Retorna o objeto de segmento.

- `object` (string): Sempre `segment`.

- `id` (string): ID do segmento, com o prefixo `seg_`.

- `name` (string): Nome do segmento.

- `description` (string | null): Observação para a sua equipe.

- `audience_ids` (string[]): As listas de contatos de origem. Vazio significa todos os contatos do workspace.

- `conditions` (object): As regras, no formato `{ "match", "groups": [{ "match", "rules": [...] }] }`. Consulte [Criar um segmento](/pt/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Se o segmento armazena os seus membros e informa as entradas e saídas. Consulte [Segmentos rastreados](/pt/docs/segments/tracked/).

- `tracking` (object | null): `null` para segmentos que não são rastreados. Para segmentos rastreados: - `status`: `active` quando os membros são mantidos atualizados, `syncing` enquanto o Emailit registra os membros atuais depois que o segmento foi criado ou que o rastreamento foi retomado, ou `paused` quando o plano do workspace não inclui mais segmentos rastreados. - `synced_at`: quando o segmento inteiro foi comparado com as regras dele pela última vez, ou `null` antes da primeira comparação.

- `contacts_count` (integer): Contatos que correspondem ao segmento agora.

- `subscribed_count` (integer): A parte de `contacts_count` para a qual as campanhas podem enviar: contatos que não estão descadastrados globalmente e estão inscritos em pelo menos uma lista. Os endereços suprimidos continuam sendo contados.

- `created_at, updated_at` (string): Timestamps em UTC.

Retorna `404` se o segmento não existir.

**Requisição** `GET /segments/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$segment = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-02T09:14:03.551000+00:00"
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/get/

## Atualizar um segmento — POST /segments/{id}

> Altere o nome, a descrição, as listas de contatos de origem ou as regras de um segmento. Não é possível mudar se um segmento é rastreado. Alfa: aberto apenas à equipe do Emailit.

# Atualizar um segmento

Atualiza os campos que você passar e deixa os outros como estão. `audience_ids` e `conditions` são substituídos por inteiro. Requer uma chave de API com escopo `full`.

As campanhas avaliam um segmento no momento do envio, então as novas regras valem para todas as campanhas que ainda não foram enviadas, incluindo as agendadas.

Em um [segmento rastreado](/pt/docs/segments/tracked/), alterar `audience_ids` ou `conditions` compara os membros armazenados com as novas regras. Os contatos que entram ou saem por causa da alteração enviam os eventos `segment.contact_added` e `segment.contact_removed` com `reason` definido como `segment_updated`. Os webhooks os recebem, mas eles não iniciam automações.

`POST /segments/{id}`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do segmento (`seg_…`).

## Parâmetros do corpo

- `name` (string): Novo nome, com até 191 caracteres. Não pode ficar vazio.

- `description` (string | null): Observação para a sua equipe, com até 1.000 caracteres. `null` ou uma string vazia a apaga.

- `audience_ids` (string[]): IDs das listas de contatos de origem. `[]` significa todos os contatos do workspace.

- `conditions` (object): As regras. Consulte [Criar um segmento](/pt/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Aceito apenas com o valor atual do segmento. O rastreamento é escolhido quando um segmento é criado; para mudá-lo, crie um novo segmento.

## Retorno

Retorna o [objeto de segmento](/pt/docs/api-reference/segments/get/) atualizado, com contagens recalculadas.

| Status | Quando |
| --- | --- |
| `404` | O segmento não existe. |
| `422` | Um campo ou uma regra é inválido, ou `tracked` é diferente do valor atual do segmento. `errors` é indexado pelo caminho do campo. |

**Requisição** `POST /segments/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro customers renewing this month" }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Pro customers renewing this month' }),
});
const segment = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"name": "Pro customers renewing this month"},
)
segment = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['name' => 'Pro customers renewing this month'],
]);
$segment = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing this month",
  "description": "Pro and Enterprise plans that renew in the next 30 days.",
  "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
          { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
        ]
      }
    ]
  },
  "tracked": true,
  "tracking": {
    "status": "active",
    "synced_at": "2026-10-18T00:30:04.211000+00:00"
  },
  "contacts_count": 412,
  "subscribed_count": 398,
  "created_at": "2026-10-02T09:14:03.551000+00:00",
  "updated_at": "2026-10-18T12:00:00.000000+00:00"
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

**422**

```json
{
  "message": "Validation failed. tracked: Tracking is chosen when a segment is created and can't be changed. Create a new segment instead.",
  "errors": {
    "tracked": [
      "Tracking is chosen when a segment is created and can't be changed. Create a new segment instead."
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/update/

## Listar segmentos — GET /segments

> Liste os segmentos de um workspace, dos mais recentes para os mais antigos, com contagens opcionais em tempo real e o uso de segmentos do plano. Alfa: aberto apenas à equipe do Emailit.

# Listar segmentos

Retorna os segmentos do workspace, dos mais recentes para os mais antigos, com quantos dos segmentos do plano estão em uso. Requer uma chave de API com escopo `full`.

`GET /segments`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de consulta

- `page` (integer): Número da página, a partir de 1.

- `limit` (integer): Segmentos por página, de 1 a 100.

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas em parte do nome do segmento.

- `with_counts` (boolean): Adiciona `contacts_count` e `subscribed_count` a cada segmento. A contagem avalia todos os segmentos da página, então ela vem desativada por padrão.

- `match`, `order`, `direction`: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

### Chaves de filtro

Os filtros usam parâmetros de consulta `key.condition=value`, por exemplo, `name.contains=customers` ou `created_at.after=2026-09-01`. Consulte [Filtragem](/pt/docs/api-reference/filtering/) para as condições de cada tipo.

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Chaves de ordenação para `order`: `name`, `created_at`, `updated_at`.

## Retorno

- `data` (object[]): [Objetos de segmento](/pt/docs/api-reference/segments/get/) desta página. `contacts_count` e `subscribed_count` só são incluídos com `with_counts`.

- `total_records` (integer): Número de segmentos que correspondem à consulta.

- `usage` (object): Os segmentos do workspace em relação ao plano: `used` (todos os segmentos, rastreados ou não), `limit` (segmentos que o plano inclui) e `tracking_allowed` (se o plano inclui segmentos rastreados). Consulte [Limites](/pt/docs/limits/#plan-limits).

- `next_page_url` (string | null): Caminho da próxima página, ou `null` na última página. Ele leva apenas `page` e `limit`; adicione de novo a sua busca e os seus filtros ao segui-lo.

- `previous_page_url` (string | null): Caminho da página anterior, ou `null` na primeira página.

**Requisição** `GET /segments`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d with_counts=true
```

**Node.js**

```javascript
const params = new URLSearchParams({ with_counts: 'true' });
const res = await fetch(`https://api.emailit.com/v2/segments?${params}`, {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data: segments, usage } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"with_counts": "true"},
)
segments = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['with_counts' => 'true'],
]);
$segments = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "object": "segment",
      "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
      "name": "Pro customers renewing soon",
      "description": "Pro and Enterprise plans that renew in the next 30 days.",
      "audience_ids": ["aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a"],
      "conditions": {
        "match": "all",
        "groups": [
          {
            "match": "all",
            "rules": [
              { "field": "custom_fields.plan", "operator": "in", "value": ["pro", "enterprise"] },
              { "field": "custom_fields.renews_on", "operator": "in_next_days", "value": 30 }
            ]
          }
        ]
      },
      "tracked": true,
      "tracking": {
        "status": "active",
        "synced_at": "2026-10-18T00:30:04.211000+00:00"
      },
      "contacts_count": 412,
      "subscribed_count": 398,
      "created_at": "2026-10-02T09:14:03.551000+00:00",
      "updated_at": "2026-10-02T09:14:03.551000+00:00"
    }
  ],
  "total_records": 1,
  "usage": {
    "used": 1,
    "limit": 10,
    "tracking_allowed": true
  },
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/list/

## Excluir um segmento — DELETE /segments/{id}

> Exclua um segmento. As campanhas em rascunho que enviam para ele o perdem; os rascunhos que o deixam de fora não podem ser enviados até você substituir a exclusão. Campanhas agendadas ou em envio e automações que usam o segmento impedem a exclusão. Alfa: aberto apenas à equipe do Emailit.

# Excluir um segmento

Exclui um segmento. Requer uma chave de API com escopo `full`.

- Um segmento que uma campanha usa enquanto ela está agendada, na fila, em envio ou em teste não pode ser excluído. Altere primeiro os destinatários da campanha.
- Um segmento não pode ser excluído enquanto qualquer automação não excluída, em qualquer status, o usar: em um gatilho **Added to segment** ou **Removed from segment**, em uma meta, etapa **Wait until** ou condição de saída sobre esses eventos, ou em uma regra **Segment** de uma condição. Altere primeiro essas automações.
- As campanhas em rascunho que enviam para o segmento o perdem dos seus destinatários, e `removed_from_campaigns` informa quantas são. Os rascunhos que deixam o segmento de fora mantêm a exclusão, então não podem ser enviados até você substituí-la: descartá-la enviaria a campanha para as pessoas que você queria deixar de fora. As campanhas enviadas, canceladas e arquivadas mantêm a referência como histórico.
- No caso de um segmento rastreado, os membros armazenados e o histórico de crescimento dele também são excluídos.

`DELETE /segments/{id}`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do segmento (`seg_…`).

## Retorno

- `object` (string): Sempre `segment`.

- `id` (string): ID do segmento excluído.

- `name` (string): O nome dele.

- `deleted` (boolean): Sempre `true`.

- `removed_from_campaigns` (integer): Número de campanhas em rascunho que não enviam mais para o segmento.

| Status | Quando |
| --- | --- |
| `404` | O segmento não existe. |
| `409` | Uma campanha agendada, na fila, em envio ou em teste usa o segmento, ou uma automação parte dele. A mensagem informa os nomes delas. |

**Requisição** `DELETE /segments/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "deleted": true,
  "removed_from_campaigns": 1
}
```

**409 Campanhas**

```json
{
  "error": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first.",
  "message": "This segment is used by campaigns that are scheduled or sending: October launch. Change their recipients first."
}
```

**409 Automações**

```json
{
  "error": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first.",
  "message": "This segment is used by automations: Renewal reminder. Change their triggers, conditions or exit conditions first."
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/delete/

## Listar os contatos de um segmento — GET /segments/{id}/contacts

> Liste os contatos que correspondem a um segmento agora, com busca, os filtros da lista de contatos e, nos segmentos rastreados, quando cada contato entrou. Alfa: aberto apenas à equipe do Emailit.

# Listar os contatos de um segmento

Retorna os contatos que correspondem ao segmento no momento da chamada, dos mais recentes para os mais antigos. Requer uma chave de API com escopo `full`.

`GET /segments/{id}/contacts`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do segmento (`seg_…`).

## Parâmetros de consulta

- `page` (integer): Número da página, a partir de 1.

- `limit` (integer): Contatos por página, de 1 a 100.

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas em parte do endereço de e-mail, do nome ou do sobrenome.

- `match`, `order`, `direction`: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

### Chaves de filtro

Os contatos de um segmento aceitam as mesmas chaves de filtro e de ordenação que [Listar contatos](/pt/docs/api-reference/contacts/list/), aplicadas sobre o segmento, por exemplo, `email.ends_with=acme.com`.

Chaves de filtro e de ordenação: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

## Retorno

- `data` (object[]): Os contatos desta página, cada um com `object`, `id`, `email`, `first_name`, `last_name`, `custom_fields`, `unsubscribed`, `audiences` (`id`, `name`, `subscribed`), `created_at` e `updated_at`. Os contatos de um [segmento rastreado](/pt/docs/segments/tracked/) também têm `joined_at`.

- `data[].joined_at` (string | null): Apenas segmentos rastreados: quando começou a permanência atual do contato no segmento. `null` até o rastreamento registrar o contato, por exemplo logo depois que ele passou a corresponder, enquanto o segmento está em `syncing` ou enquanto o rastreamento está em `paused`.

- `total_records` (integer): Número de contatos que correspondem ao segmento, à busca e aos filtros.

- `subscribed_count` (integer): Para quantos deles as campanhas podem enviar: não descadastrados globalmente e inscritos em pelo menos uma lista.

- `next_page_url` (string | null): Caminho da próxima página, ou `null` na última página. Ele leva `page`, `limit` e `search`; adicione de novo os seus filtros ao segui-lo.

- `previous_page_url` (string | null): Caminho da página anterior, ou `null` na primeira página.

Retorna `404` se o segmento não existir.

**Requisição** `GET /segments/{id}/contacts`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d email.ends_with=acme.com
```

**Node.js**

```javascript
const params = new URLSearchParams({ 'email.ends_with': 'acme.com' });
const res = await fetch(
  `https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts?${params}`,
  { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const { data: contacts } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"email.ends_with": "acme.com"},
)
contacts = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['email.ends_with' => 'acme.com'],
]);
$contacts = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00",
      "joined_at": "2026-10-03T00:30:02.874000+00:00"
    }
  ],
  "total_records": 1,
  "subscribed_count": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/contacts/

## Obter o crescimento de um segmento — GET /segments/{id}/growth

> Contagens diárias de membros, entradas e saídas de um segmento rastreado, uma linha por dia UTC por até 365 dias. Alfa: aberto apenas à equipe do Emailit.

# Obter o crescimento de um segmento

Retorna o histórico de um [segmento rastreado](/pt/docs/segments/tracked/): uma linha por dia UTC, dos mais antigos para os mais recentes, terminando hoje. São os dados por trás do gráfico **Growth** na página do segmento. Requer uma chave de API com escopo `full`.

O histórico começa quando o rastreamento começa. Os contatos registrados pela primeira contagem depois que o segmento foi criado, ou depois que o rastreamento foi retomado, contam como membros, mas não como entradas.

`GET /segments/{id}/growth`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do segmento (`seg_…`).

## Parâmetros de consulta

- `days` (integer): Número de dias a retornar, de 1 a 365, terminando hoje.

## Retorno

- `object` (string): Sempre `segment_growth`.

- `segment_id` (string): O ID do segmento.

- `data` (object[]): Uma linha por dia.

- `data[].date` (string): O dia em UTC, `YYYY-MM-DD`.

- `data[].members_count` (integer | null): Membros no fim do dia, ou a contagem mais recente para hoje. Os dias sem uma nova contagem repetem o valor anterior, por exemplo enquanto o rastreamento está pausado. `null` antes de o rastreamento começar.

- `data[].joined_count` (integer): Contatos que entraram no segmento naquele dia.

- `data[].left_count` (integer): Contatos que saíram do segmento naquele dia.

| Status | Quando |
| --- | --- |
| `404` | O segmento não existe. |
| `422` | O segmento não é rastreado. |

**Requisição** `GET /segments/{id}/growth`

**cURL**

```bash
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d days=7
```

**Node.js**

```javascript
const res = await fetch(
  'https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth?days=7',
  { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const { data: days } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    params={"days": 7},
)
days = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'query' => ['days' => 7],
]);
$days = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "object": "segment_growth",
  "segment_id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "data": [
    { "date": "2026-10-12", "members_count": null, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-13", "members_count": 380, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-14", "members_count": 391, "joined_count": 14, "left_count": 3 },
    { "date": "2026-10-15", "members_count": 391, "joined_count": 0, "left_count": 0 },
    { "date": "2026-10-16", "members_count": 402, "joined_count": 12, "left_count": 1 },
    { "date": "2026-10-17", "members_count": 405, "joined_count": 6, "left_count": 3 },
    { "date": "2026-10-18", "members_count": 412, "joined_count": 9, "left_count": 2 }
  ]
}
```

**422**

```json
{
  "error": "Growth is recorded for tracked segments only.",
  "message": "Growth is recorded for tracked segments only."
}
```

**404**

```json
{
  "error": "Segment not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/growth/

## Pré-visualizar um segmento — POST /segments/preview

> Conte e veja uma amostra dos contatos que uma definição de segmento conteria, sem salvá-la. Alfa: aberto apenas à equipe do Emailit.

# Pré-visualizar um segmento

Verifica uma definição de segmento sem salvá-la: retorna quantos contatos correspondem a ela e uma amostra deles. A definição é validada como em [Criar um segmento](/pt/docs/api-reference/segments/create/), e uma pré-visualização não conta para o limite de segmentos do plano. Requer uma chave de API com escopo `full`.

`POST /segments/preview`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Parâmetros do corpo

- `audience_ids` (string[]): IDs das listas de contatos que o segmento usaria como origem. Vazio ou omitido significa todos os contatos.

- `conditions` (object): As regras. Consulte [Criar um segmento](/pt/docs/api-reference/segments/create/#conditions).

- `limit` (integer): Número de contatos de amostra, de 1 a 25.

## Retorno

- `object` (string): Sempre `segment_preview`.

- `audience_ids` (string[]): As listas de contatos de origem, sem duplicatas.

- `conditions` (object): As regras como seriam salvas: um `{ match, rules }` plano vira um único grupo, e os grupos vazios são descartados.

- `contacts_count` (integer): Contatos que correspondem à definição.

- `subscribed_count` (integer): Para quantos deles as campanhas podem enviar.

- `contacts` (object[]): Os contatos correspondentes mais recentes, no mesmo formato de [Listar os contatos de um segmento](/pt/docs/api-reference/segments/contacts/).

Retorna `422` com `errors` indexado pelo caminho do campo se a definição for inválida.

**Requisição** `POST /segments/preview`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/segments/preview \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": { "rules": [{ "field": "email_domain", "operator": "equals", "value": "acme.com" }] },
    "limit": 5
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conditions: { rules: [{ field: 'email_domain', operator: 'equals', value: 'acme.com' }] },
    limit: 5,
  }),
});
const preview = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/segments/preview",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "conditions": {"rules": [{"field": "email_domain", "operator": "equals", "value": "acme.com"}]},
        "limit": 5,
    },
)
preview = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('segments/preview', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'conditions' => ['rules' => [['field' => 'email_domain', 'operator' => 'equals', 'value' => 'acme.com']]],
        'limit' => 5,
    ],
]);
$preview = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "segment_preview",
  "audience_ids": [],
  "conditions": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "rules": [
          { "field": "email_domain", "operator": "equals", "value": "acme.com" }
        ]
      }
    ]
  },
  "contacts_count": 8,
  "subscribed_count": 8,
  "contacts": [
    {
      "object": "contact",
      "id": "con_2nYs7Ab3Kd9Lm1Qw5Er8Ty2Ui4o",
      "email": "ada@acme.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "plan": "pro",
        "renews_on": "2026-10-20"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a",
          "name": "Customers",
          "subscribed": true
        }
      ],
      "created_at": "2026-03-11T08:00:00.000000+00:00",
      "updated_at": "2026-09-30T16:42:10.000000+00:00"
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. conditions.groups.0.rules.0.operator: \"greater_than\" does not apply to Email domain.",
  "errors": {
    "conditions.groups.0.rules.0.operator": [
      "\"greater_than\" does not apply to Email domain."
    ]
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/preview/

## Listar os campos de segmentos — GET /segments/fields

> Liste os campos do contato, os campos personalizados e as listas de contatos que as regras de segmento podem usar, com os operadores e os valores que cada um aceita. Alfa: aberto apenas à equipe do Emailit.

# Listar os campos de segmentos

Retorna os campos que as regras de segmento podem usar neste workspace: os campos do contato, cada campo personalizado (com o tipo definido pelo tipo do campo personalizado), a participação em listas, os dados de compra e o engajamento com campanhas. Requer uma chave de API com escopo `full`.

`GET /segments/fields`

> **Os segmentos estão em alfa:** Os segmentos estão abertos apenas à equipe do Emailit enquanto os testamos. As outras requisições, incluindo todas as requisições feitas com uma chave de API, retornam `403` com `error: "segments_alpha"`. Consulte [Quem pode usar os segmentos](/pt/docs/segments/#who-can-use-segments).

## Retorno

- `data` (object[]): Um item por campo.

- `data[].key` (string): O valor a usar como `field` de uma regra, por exemplo `email_domain` ou `custom_fields.plan`.

- `data[].label` (string): Nome de exibição. Nos campos personalizados, o nome do campo personalizado.

- `data[].type` (string): `string`, `number`, `date`, `datetime`, `boolean`, `enum`, `multi`, `audience`, `metric`, `moment`, `purchase`, `view`, `cart`, `coupon` ou `campaign_activity`. Consulte [Criar um segmento](/pt/docs/api-reference/segments/create/#fields). Os campos de atividade, como `purchased`, recebem um objeto como valor; consulte [Regras de atividade](/pt/docs/api-reference/segments/create/#activity-rules).

- `data[].group` (string): `contact`, `custom_fields`, `audiences`, `commerce` (dados de compra) ou `engagement` (atividade em campanhas).

- `data[].operators` (string[]): Operadores que o campo aceita.

- `data[].values` (object[]): Valores permitidos, como `value` e `label`: as opções dos campos personalizados de seleção e de seleção múltipla, `subscribed` e `unsubscribed` para `status` e as listas de contatos do workspace para `audience`. Ausente nos outros campos.

**Requisição** `GET /segments/fields`

**cURL**

```bash
curl https://api.emailit.com/v2/segments/fields \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/segments/fields', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data: fields } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/segments/fields",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
fields = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('segments/fields', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$fields = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "key": "email",
      "label": "Email",
      "type": "string",
      "group": "contact",
      "operators": ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_set", "is_not_set"]
    },
    {
      "key": "status",
      "label": "Subscription status",
      "type": "enum",
      "group": "contact",
      "operators": ["equals", "not_equals"],
      "values": [
        { "value": "subscribed", "label": "Subscribed" },
        { "value": "unsubscribed", "label": "Unsubscribed" }
      ]
    },
    {
      "key": "audience",
      "label": "Audience",
      "type": "audience",
      "group": "audiences",
      "operators": ["in", "not_in"],
      "values": [
        { "value": "aud_2nYs8Qm4Hc1Zx7Vb3Ne6Tg9Lk2a", "label": "Customers" }
      ]
    },
    {
      "key": "purchased",
      "label": "Purchased",
      "type": "purchase",
      "group": "commerce",
      "operators": [
        "has",
        "has_not"
      ]
    },
    {
      "key": "custom_fields.renews_on",
      "label": "Renews on",
      "type": "date",
      "group": "custom_fields",
      "operators": ["on", "before", "after", "between", "in_last_days", "more_than_days_ago", "in_next_days", "is_set", "is_not_set"]
    }
  ]
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/segments/fields/