# Segmentos API

> Guarda filtros sobre tus contactos, lista quién coincide con ellos y sigue la evolución de los segmentos con seguimiento.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear un segmento — POST /segments

> Crea un segmento, un filtro guardado sobre tus contactos que parte de todos los contactos o de las listas que elijas, y elige si tiene seguimiento. Alfa: solo para el equipo de Emailit.

# Crear un segmento

Crea un segmento: un filtro guardado sobre los contactos del espacio de trabajo. Requiere una clave de API con el permiso `full`.

Un segmento contiene los contactos de su origen (los suscriptores de `audience_ids`, o todos los contactos si está vacío) que cumplen sus `conditions`. La pertenencia se evalúa en directo cada vez que el segmento se cuenta, se lista, se previsualiza o lo usa una campaña al enviarse. Consulta [Segmentos](/es/docs/segments/).

Cada plan incluye un número de segmentos por espacio de trabajo, con seguimiento o sin él. Consulta [Límites](/es/docs/limits/#plan-limits).

`POST /segments`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros del cuerpo

- `name` (string, obligatorio): El nombre del segmento, de hasta 191 caracteres.

- `description` (string | null): Una nota para tu equipo, de hasta 1000 caracteres.

- `audience_ids` (string[]): El origen: los ID de listas de contactos (`aud_…`) de este espacio de trabajo, hasta 100. El segmento solo contiene contactos suscritos al menos a una de ellas. Si está vacío o se omite, se usan todos los contactos del espacio de trabajo.

- `conditions` (object): Las reglas que tienen que cumplir los contactos, descritas en [Condiciones](#conditions). Omítelo para incluir a todos los contactos del origen.

- `tracked` (boolean): Guarda los miembros del segmento para que las entradas y salidas de contactos se conviertan en eventos para [automatizaciones](/es/docs/automations/triggers/#segment-triggers) y [webhooks](/es/docs/webhooks/event-types/#segment-events). Incluido en Pro, Business y Custom. Lo eliges aquí y no puedes cambiarlo después. Consulta [Segmentos con seguimiento](/es/docs/segments/tracked/).

## Condiciones

`conditions` contiene grupos de reglas. El `match` del nivel superior une los grupos, y el `match` de cada grupo une sus reglas:

```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` es `all` (por defecto) o `any`, en el nivel superior y en cada grupo.
- Omite `conditions`, o no envíes grupos, para incluir a todos los contactos del origen. Los grupos vacíos se descartan.
- También se acepta la forma plana `{ "match": "any", "rules": [...] }`, que se guarda como un solo grupo.
- Un segmento puede tener hasta 10 grupos y 50 reglas en total.

### Campos

| Campo | Tipo | Notas |
| --- | --- | --- |
| `email` | string | |
| `email_domain` | string | La parte de la dirección que va después de `@`. |
| `first_name`, `last_name` | string | |
| `status` | enum | `subscribed` (no se ha dado de baja de forma global y está suscrito al menos a una lista, así que las campañas pueden llegar al contacto) o `unsubscribed`. Operadores: `equals`, `not_equals`. |
| `created_at`, `updated_at` | datetime | Cuándo se creó el contacto o cuándo cambió por última vez, comparado en UTC. |
| `audience` | audience | Pertenencia con suscripción. `in` coincide con los contactos suscritos a cualquiera de los ID de lista, y `not_in`, con los contactos que no están suscritos a ninguna de ellas. |
| `tags` | tags | Las [etiquetas](/es/docs/contacts/tags-and-score/) del contacto. Los valores se comparan en minúsculas. |
| `score` | score | La [puntuación de lead](/es/docs/contacts/tags-and-score/#lead-score) del contacto. |
| `custom_fields.<key>` | según el campo | Los campos de texto son `string`; los numéricos, `number`; los de fecha, `date` (`YYYY-MM-DD`); los booleanos, `boolean`; los de selección, `enum`, y los de selección múltiple, `multi`. |
| `orders_count`, `total_spent`, `average_order_value` | metric | A partir de los [pedidos](/es/docs/commerce/) del contacto. 0 en los contactos sin pedidos. Los importes están en la moneda de los pedidos del contacto. |
| `first_order_at`, `last_order_at` | moment | Sin valor en los contactos sin pedidos. |
| `expected_next_order_at` | moment | El último pedido más el intervalo medio del contacto entre pedidos. Tiene valor a partir del segundo pedido y puede estar en el futuro. |
| `churn_risk` | enum | `low`, `medium` o `high`: el tiempo transcurrido desde el último pedido comparado con el intervalo habitual del contacto (como mínimo 14 días), o con 90 días para quienes solo han comprado una vez. Sin valor si no hay pedidos. |
| `last_active_at` | moment | La última vez que el [script de seguimiento](/es/docs/commerce/connect-your-shop/#the-tracking-script) vio al contacto en tu web. |
| `purchased` | purchase | Pedidos; consulta [Reglas de actividad](#activity-rules). |
| `viewed_product` | view | Visualizaciones de productos registradas por el script de seguimiento. |
| `cart` | cart | Carritos abiertos y abandonados. |
| `used_coupon` | coupon | Pedidos en los que se usó un código de cupón. |
| `campaign_activity` | campaign_activity | Emails de campaña recibidos, abiertos o con clic. |

[Listar los campos de segmento](/es/docs/api-reference/segments/fields/) devuelve los campos de tu espacio de trabajo, incluidos sus campos personalizados y sus listas, con los operadores que acepta cada uno.

### 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` (tiene alguno), `contains_all` (los tiene todos), `not_in` (no tiene ninguno), `is_set`, `is_not_set` |
| audience | `in`, `not_in` |
| tags | `in` (tiene alguna), `contains_all` (las tiene todas), `not_in` (no tiene ninguna), `is_set` (tiene alguna etiqueta), `is_not_set` (no tiene etiquetas) |
| 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

- Las comparaciones de texto en los campos string no distinguen mayúsculas y minúsculas. Los valores de selección y de selección múltiple tienen que coincidir exactamente.
- `not_equals`, `not_contains` y `not_in` también coinciden con los contactos que no tienen ningún valor.
- `in`, `not_in` y `contains_all` aceptan una lista de hasta 100 valores. Los valores de texto pueden tener hasta 500 caracteres.
- `between` acepta `[from, to]`, ambos incluidos: dos números o dos fechas `YYYY-MM-DD`.
- `on`, `before` y `after` aceptan una fecha `YYYY-MM-DD`. `before` y `after` no incluyen ese día.
- `in_last_days`, `more_than_days_ago` e `in_next_days` aceptan un número entero de días de 1 a 3650, contados desde el momento en que se evalúa el segmento. Los campos personalizados de fecha comparan días naturales en UTC; `created_at` y `updated_at` usan horas exactas, así que `in_last_days` con `7` significa las últimas 7 × 24 horas.
- `is_set`, `is_not_set`, `is_true` e `is_false` no aceptan ningún valor. `is_true` coincide con `true`, `1`, `yes` y `on`; `is_false` coincide con `false`, `0`, `no` y `off`.
- Una regla guardada que ya no es aplicable, por ejemplo porque su campo personalizado ha cambiado de tipo, no coincide con ningún contacto. Las reglas sobre un campo personalizado eliminado siguen funcionando con los valores que aún tienen los contactos, pero las reglas nuevas tienen que usar un campo existente.

### Reglas de actividad

`purchased`, `viewed_product`, `cart`, `used_coupon` y `campaign_activity` aceptan un objeto como `value`. Todas las claves son opcionales.

| Campo | Claves del valor |
| --- | --- |
| `purchased` | `days`: solo los pedidos realizados en los últimos N días. `product_ids`: pedidos con cualquiera de estos productos (los ID de producto de tu tienda). `categories`: pedidos con un producto de cualquiera de estas categorías. `min_count`: al menos este número de pedidos que coinciden (por defecto 1, hasta 1000). Los pedidos cancelados no cuentan. |
| `viewed_product` | `days`, `product_ids`, `categories` y `min_count`, como en la fila anterior, contando visualizaciones de productos. |
| `cart` | `days`, solo con `has_abandoned_cart`: carritos abandonados en los últimos N días. `has_open_cart` coincide con un carrito activo, y `has_no_open_cart`, con los contactos sin ningún carrito activo ni abandonado. |
| `used_coupon` | `days` y `coupon`: la clave de un [cupón](/es/docs/commerce/coupons/). Sin `coupon`, cuenta cualquier código. |
| `campaign_activity` | `campaign_id`: una campaña (`cmp_...`); si falta, cualquier campaña. `days`: solo los últimos N días; si falta, desde siempre. |

`days` es un número entero de 1 a 3650. `has_not` es lo contrario de `has` con el mismo 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` y `received_not_clicked` coinciden con los contactos que han recibido al menos un email de campaña que cumple la regla y no han abierto ninguno o no han hecho clic en ninguno, respectivamente. Las aperturas son aproximadas: Apple Mail carga las imágenes de todos los emails que recibe.

## Devuelve

Devuelve `201 Created` con el [objeto de segmento](/es/docs/api-reference/segments/get/), incluidos `contacts_count` y `subscribed_count`. Un segmento con seguimiento nuevo empieza con `tracking.status` en `syncing` mientras Emailit registra sus miembros actuales.

| Código | Cuándo |
| --- | --- |
| `400` | Falta `name` o un campo tiene un tipo incorrecto. |
| `403` | `tracked` es `true` y el plan no incluye segmentos con seguimiento. El cuerpo es `{"error": "plan_required", "required_plan": "pro", ...}`. |
| `422` | Un campo o una regla no son válidos: `errors` usa su ruta como clave, por ejemplo `conditions.groups.0.rules.1.value`, y `message` repite el primer problema. También se devuelve cuando el espacio de trabajo ha alcanzado el límite de segmentos de su plan; ese cuerpo incluye `usage.used` y `usage.limit`. |

**Petición** `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 Validación**

```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 Límite**

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

---
Fuente: https://emailit.com/es/docs/api-reference/segments/create/

## Obtener un segmento — GET /segments/{id}

> Obtén un segmento con su origen, sus reglas, el estado de su seguimiento y los recuentos de contactos en directo. Alfa: solo para el equipo de Emailit.

# Obtener un segmento

Obtiene un segmento y cuenta sus contactos en el momento de la llamada. Requiere una clave de API con el permiso `full`.

`GET /segments/{id}`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de ruta

- `id` (string, obligatorio): El ID del segmento (`seg_…`).

## Devuelve

Devuelve el objeto de segmento.

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

- `id` (string): El ID del segmento, con el prefijo `seg_`.

- `name` (string): El nombre del segmento.

- `description` (string | null): Una nota para tu equipo.

- `audience_ids` (string[]): Las listas de contactos de origen. Si está vacío, se usan todos los contactos del espacio de trabajo.

- `conditions` (object): Las reglas, con la forma `{ "match", "groups": [{ "match", "rules": [...] }] }`. Consulta [Crear un segmento](/es/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Si el segmento guarda sus miembros e informa de las entradas y salidas. Consulta [Segmentos con seguimiento](/es/docs/segments/tracked/).

- `tracking` (object | null): `null` en los segmentos sin seguimiento. En los segmentos con seguimiento: - `status`: `active` cuando los miembros se mantienen al día, `syncing` mientras Emailit registra los miembros actuales después de crear el segmento o de reanudar el seguimiento, o `paused` cuando el plan del espacio de trabajo ya no incluye segmentos con seguimiento. - `synced_at`: la última vez que se comparó todo el segmento con sus reglas, o `null` antes de la primera comparación.

- `contacts_count` (integer): Los contactos que coinciden en este momento.

- `subscribed_count` (integer): La parte de `contacts_count` a la que pueden enviar las campañas: los contactos que no se han dado de baja de forma global y están suscritos al menos a una lista de contactos. Las direcciones bloqueadas se siguen contando.

- `created_at, updated_at` (string): Las marcas de tiempo en UTC.

Devuelve `404` si el segmento no existe.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/get/

## Actualizar un segmento — POST /segments/{id}

> Cambia el nombre, la descripción, las listas de contactos de origen o las reglas de un segmento. No se puede cambiar si un segmento tiene seguimiento. Alfa: solo para el equipo de Emailit.

# Actualizar un segmento

Actualiza los campos que envías y deja los demás sin cambios. `audience_ids` y `conditions` se sustituyen por completo. Requiere una clave de API con el permiso `full`.

Las campañas evalúan un segmento cuando se envían, así que las reglas nuevas se aplican a todas las campañas que aún no se han enviado, también a las programadas.

En un [segmento con seguimiento](/es/docs/segments/tracked/), cambiar `audience_ids` o `conditions` compara los miembros guardados con las reglas nuevas. Los contactos que entran o salen por el cambio envían eventos `segment.contact_added` y `segment.contact_removed` con `reason` en `segment_updated`. Los webhooks los reciben, pero no inician automatizaciones.

`POST /segments/{id}`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de ruta

- `id` (string, obligatorio): El ID del segmento (`seg_…`).

## Parámetros del cuerpo

- `name` (string): El nombre nuevo, de hasta 191 caracteres. No puede estar vacío.

- `description` (string | null): Una nota para tu equipo, de hasta 1000 caracteres. `null` o una cadena vacía la borran.

- `audience_ids` (string[]): Los ID de las listas de contactos de origen. `[]` significa todos los contactos del espacio de trabajo.

- `conditions` (object): Las reglas. Consulta [Crear un segmento](/es/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Solo se acepta con el valor actual del segmento. El seguimiento se elige al crear un segmento; para cambiarlo, crea un segmento nuevo.

## Devuelve

Devuelve el [objeto de segmento](/es/docs/api-reference/segments/get/) actualizado, con los recuentos recalculados.

| Código | Cuándo |
| --- | --- |
| `404` | El segmento no existe. |
| `422` | Un campo o una regla no son válidos, o `tracked` es distinto del valor actual del segmento. `errors` usa la ruta del campo como clave. |

**Petición** `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."
    ]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/update/

## Listar segmentos — GET /segments

> Lista los segmentos de un espacio de trabajo, del más reciente al más antiguo, con recuentos en directo opcionales y el uso de segmentos del plan. Alfa: solo para el equipo de Emailit.

# Listar segmentos

Devuelve los segmentos del espacio de trabajo, del más reciente al más antiguo, con cuántos de los segmentos del plan están en uso. Requiere una clave de API con el permiso `full`.

`GET /segments`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de consulta

- `page` (integer): El número de página, empezando por 1.

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

- `search` (string): Una búsqueda sin distinguir mayúsculas y minúsculas en una parte del nombre del segmento.

- `with_counts` (boolean): Añade `contacts_count` y `subscribed_count` a cada segmento. El recuento evalúa todos los segmentos de la página, así que está desactivado por defecto.

- `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

### Claves de filtro

Los filtros usan parámetros de consulta `key.condition=value`, por ejemplo `name.contains=customers` o `created_at.after=2026-09-01`. Para las condiciones de cada tipo, consulta [Filtrado y ordenación](/es/docs/api-reference/filtering/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Claves de orden para `order`: `name`, `created_at`, `updated_at`.

## Devuelve

- `data` (object[]): Los [objetos de segmento](/es/docs/api-reference/segments/get/) de esta página. `contacts_count` y `subscribed_count` solo se incluyen con `with_counts`.

- `total_records` (integer): El número de segmentos que coinciden con la consulta.

- `usage` (object): Los segmentos del espacio de trabajo frente a su plan: `used` (todos los segmentos, con seguimiento o sin él), `limit` (los segmentos que incluye el plan) y `tracking_allowed` (si el plan incluye segmentos con seguimiento). Consulta [Límites](/es/docs/limits/#plan-limits).

- `next_page_url` (string | null): La ruta de la página siguiente, o `null` en la última página. Solo lleva `page` y `limit`; vuelve a añadir tu búsqueda y tus filtros cuando la sigas.

- `previous_page_url` (string | null): La ruta de la página anterior, o `null` en la primera página.

**Petición** `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
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/list/

## Eliminar un segmento — DELETE /segments/{id}

> Elimina un segmento. Los borradores de campaña que se envían a él lo pierden; los que lo excluyen no se pueden enviar hasta que sustituyas la exclusión. Las campañas programadas o en curso de envío y las automatizaciones que usan el segmento impiden eliminarlo. Alfa: solo para el equipo de Emailit.

# Eliminar un segmento

Elimina un segmento. Requiere una clave de API con el permiso `full`.

- Un segmento que usa una campaña mientras está programada, en cola, enviándose o en prueba no se puede eliminar. Cambia antes los destinatarios de la campaña.
- Un segmento no se puede eliminar mientras lo use alguna automatización no eliminada, en cualquier estado: en un disparador **Added to segment** o **Removed from segment**, en un objetivo, un paso **Wait until** o una condición de salida sobre esos eventos, o en una regla **Segment** de una condición. Cambia antes esas automatizaciones.
- Los borradores de campaña que se envían al segmento lo pierden de sus destinatarios, y `removed_from_campaigns` indica cuántos son. Los borradores que excluyen el segmento conservan la exclusión, así que no se pueden enviar hasta que la sustituyas: si se descartara, la campaña llegaría a las personas que querías dejar fuera. Las campañas enviadas, canceladas y archivadas conservan la referencia como historial.
- En un segmento con seguimiento, también se eliminan sus miembros guardados y su historial de crecimiento.

`DELETE /segments/{id}`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de ruta

- `id` (string, obligatorio): El ID del segmento (`seg_…`).

## Devuelve

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

- `id` (string): El ID del segmento eliminado.

- `name` (string): Su nombre.

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

- `removed_from_campaigns` (integer): El número de borradores de campaña que ya no se envían al segmento.

| Código | Cuándo |
| --- | --- |
| `404` | El segmento no existe. |
| `409` | Una campaña programada, en cola, enviándose o en prueba usa el segmento, o una automatización parte de él. El mensaje las nombra. |

**Petición** `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 Campañas**

```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 Automatizaciones**

```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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/delete/

## Listar los contactos de un segmento — GET /segments/{id}/contacts

> Lista los contactos que coinciden con un segmento en este momento, con búsqueda, los filtros de la lista de contactos y, en los segmentos con seguimiento, cuándo entró cada contacto. Alfa: solo para el equipo de Emailit.

# Listar los contactos de un segmento

Devuelve los contactos que coinciden con el segmento en el momento de la llamada, del más reciente al más antiguo. Requiere una clave de API con el permiso `full`.

`GET /segments/{id}/contacts`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de ruta

- `id` (string, obligatorio): El ID del segmento (`seg_…`).

## Parámetros de consulta

- `page` (integer): El número de página, empezando por 1.

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

- `search` (string): Una búsqueda sin distinguir mayúsculas y minúsculas en una parte de la dirección de email, el nombre o los apellidos.

- `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

### Claves de filtro

Los contactos de un segmento aceptan las mismas claves de filtro y de orden que [Listar contactos](/es/docs/api-reference/contacts/list/), aplicadas además del segmento, por ejemplo `email.ends_with=acme.com`.

Claves de filtro y de ordenación: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

## Devuelve

- `data` (object[]): Los contactos de esta página, cada uno con `object`, `id`, `email`, `first_name`, `last_name`, `custom_fields`, `unsubscribed`, `audiences` (`id`, `name`, `subscribed`), `created_at` y `updated_at`. Los contactos de un [segmento con seguimiento](/es/docs/segments/tracked/) también tienen `joined_at`.

- `data[].joined_at` (string | null): Solo en los segmentos con seguimiento: cuándo empezó la permanencia actual del contacto en el segmento. `null` hasta que el seguimiento registra al contacto, por ejemplo justo después de que empiece a coincidir, mientras el segmento está en `syncing` o mientras el seguimiento está en `paused`.

- `total_records` (integer): El número de contactos que coinciden con el segmento, la búsqueda y los filtros.

- `subscribed_count` (integer): Cuántos de ellos pueden recibir campañas: no se han dado de baja de forma global y están suscritos al menos a una lista de contactos.

- `next_page_url` (string | null): La ruta de la página siguiente, o `null` en la última página. Lleva `page`, `limit` y `search`; vuelve a añadir tus filtros cuando la sigas.

- `previous_page_url` (string | null): La ruta de la página anterior, o `null` en la primera página.

Devuelve `404` si el segmento no existe.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/contacts/

## Obtener el crecimiento de un segmento — GET /segments/{id}/growth

> Los recuentos diarios de miembros, entradas y salidas de un segmento con seguimiento, con una fila por día UTC durante hasta 365 días. Alfa: solo para el equipo de Emailit.

# Obtener el crecimiento de un segmento

Devuelve el historial de un [segmento con seguimiento](/es/docs/segments/tracked/): una fila por día UTC, del más antiguo al más reciente, hasta hoy. Son los datos del gráfico **Growth** de la página del segmento. Requiere una clave de API con el permiso `full`.

El historial empieza cuando empieza el seguimiento. Los contactos registrados en el primer recuento tras crear el segmento, o tras reanudar el seguimiento, cuentan como miembros, pero no como entradas.

`GET /segments/{id}/growth`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros de ruta

- `id` (string, obligatorio): El ID del segmento (`seg_…`).

## Parámetros de consulta

- `days` (integer): El número de días que se devuelven, de 1 a 365, hasta hoy.

## Devuelve

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

- `segment_id` (string): El ID del segmento.

- `data` (object[]): Una fila por día.

- `data[].date` (string): El día UTC, `YYYY-MM-DD`.

- `data[].members_count` (integer | null): Los miembros al final del día, o el último recuento en el caso de hoy. Los días sin un recuento nuevo mantienen el valor anterior, por ejemplo mientras el seguimiento está pausado. `null` antes de que empezara el seguimiento.

- `data[].joined_count` (integer): Los contactos que entraron en el segmento ese día.

- `data[].left_count` (integer): Los contactos que salieron del segmento ese día.

| Código | Cuándo |
| --- | --- |
| `404` | El segmento no existe. |
| `422` | El segmento no tiene seguimiento. |

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/growth/

## Previsualizar un segmento — POST /segments/preview

> Cuenta los contactos que tendría la definición de un segmento y obtén una muestra de ellos, sin guardarla. Alfa: solo para el equipo de Emailit.

# Previsualizar un segmento

Comprueba la definición de un segmento sin guardarla: devuelve cuántos contactos coinciden y una muestra de ellos. La definición se valida igual que en [Crear un segmento](/es/docs/api-reference/segments/create/), y una vista previa no cuenta para el límite de segmentos del plan. Requiere una clave de API con el permiso `full`.

`POST /segments/preview`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Parámetros del cuerpo

- `audience_ids` (string[]): Los ID de las listas de contactos de las que tomaría sus contactos el segmento. Si está vacío o se omite, se usan todos los contactos.

- `conditions` (object): Las reglas. Consulta [Crear un segmento](/es/docs/api-reference/segments/create/#conditions).

- `limit` (integer): El número de contactos de muestra, de 1 a 25.

## Devuelve

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

- `audience_ids` (string[]): Las listas de contactos de origen, sin duplicados.

- `conditions` (object): Las reglas tal como se guardarían: un `{ match, rules }` plano se convierte en un grupo y los grupos vacíos se descartan.

- `contacts_count` (integer): Los contactos que coinciden.

- `subscribed_count` (integer): Cuántos de ellos pueden recibir campañas.

- `contacts` (object[]): Los contactos coincidentes más recientes, con la misma forma que en [Listar los contactos de un segmento](/es/docs/api-reference/segments/contacts/).

Devuelve `422` con `errors`, con la ruta del campo como clave, si la definición no es válida.

**Petición** `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."
    ]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/preview/

## Listar los campos de segmento — GET /segments/fields

> Lista los campos del contacto, los campos personalizados y las listas de contactos que pueden usar las reglas de los segmentos, con los operadores y los valores que acepta cada uno. Alfa: solo para el equipo de Emailit.

# Listar los campos de segmento

Devuelve los campos que pueden usar las reglas de los segmentos en este espacio de trabajo: los campos del contacto, todos los campos personalizados (con el tipo que corresponde a su tipo de campo personalizado), la pertenencia a listas de contactos, los datos de compra y la interacción con las campañas. Requiere una clave de API con el permiso `full`.

`GET /segments/fields`

> **Los segmentos están en alfa:** Los segmentos solo están abiertos al equipo de Emailit mientras los probamos. Las demás peticiones, incluidas todas las que se hacen con una clave de API, devuelven `403` con `error: "segments_alpha"`. Consulta [Quién puede usar los segmentos](/es/docs/segments/#who-can-use-segments).

## Devuelve

- `data` (object[]): Un elemento por campo.

- `data[].key` (string): El valor que se usa como `field` de una regla, por ejemplo `email_domain` o `custom_fields.plan`.

- `data[].label` (string): El nombre visible. En los campos personalizados, el nombre del campo personalizado.

- `data[].type` (string): `string`, `number`, `date`, `datetime`, `boolean`, `enum`, `multi`, `audience`, `metric`, `moment`, `purchase`, `view`, `cart`, `coupon` o `campaign_activity`. Consulta [Crear un segmento](/es/docs/api-reference/segments/create/#fields). Los campos de actividad como `purchased` aceptan un objeto como valor; consulta [Reglas de actividad](/es/docs/api-reference/segments/create/#activity-rules).

- `data[].group` (string): `contact`, `custom_fields`, `audiences`, `commerce` (datos de compra) o `engagement` (actividad en las campañas).

- `data[].operators` (string[]): Los operadores que acepta el campo.

- `data[].values` (object[]): Los valores permitidos, como `value` y `label`: las opciones de los campos personalizados de selección y de selección múltiple, `subscribed` y `unsubscribed` para `status`, y las listas de contactos del espacio de trabajo para `audience`. No aparece en los demás campos.

**Petición** `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"]
    }
  ]
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/segments/fields/