# Segmenti API

> Salva filtri sui contatti, elenca chi corrisponde e segui nel tempo i segmenti tracciati.

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea un segmento — POST /segments

> Crea un segmento, cioè un filtro salvato sui contatti che parte da tutti i contatti o da liste scelte, e scegli se tracciarlo. Alpha: aperti solo al team di Emailit.

# Crea un segmento

Crea un segmento: un filtro salvato sui contatti del workspace. Richiede una chiave API `full`.

Un segmento contiene i contatti della sua origine (gli iscritti delle liste in `audience_ids`, oppure tutti i contatti se è vuoto) che soddisfano le sue `conditions`. L’appartenenza viene valutata in tempo reale ogni volta che il segmento viene contato, elencato, visualizzato in anteprima o usato da una campagna al momento dell’invio. Vedi [Segmenti](/it/docs/segments/).

Ogni piano include un certo numero di segmenti per workspace, tracciati o no. Vedi [Limiti e quote](/it/docs/limits/#plan-limits).

`POST /segments`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri del corpo

- `name` (string, obbligatorio): Nome del segmento, fino a 191 caratteri.

- `description` (string | null): Nota per il team, fino a 1000 caratteri.

- `audience_ids` (string[]): L’origine: ID di liste (`aud_…`) di questo workspace, fino a 100. Il segmento contiene solo i contatti iscritti ad almeno una di esse. Vuoto o omesso significa tutti i contatti del workspace.

- `conditions` (object): Le regole che i contatti devono soddisfare, descritte in [Condizioni](#conditions). Omettilo per includere tutti i contatti dell’origine.

- `tracked` (boolean): Memorizza i membri del segmento, così i contatti che entrano ed escono diventano eventi per le [automazioni](/it/docs/automations/triggers/#segment-triggers) e i [webhook](/it/docs/webhooks/event-types/#segment-events). Incluso nei piani Pro, Business e Custom. Lo scegli qui e non puoi cambiarlo in seguito. Vedi [Segmenti tracciati](/it/docs/segments/tracked/).

## Condizioni

`conditions` contiene gruppi di regole. Il `match` di primo livello combina i gruppi, e il `match` di ogni gruppo combina le sue regole:

```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` vale `all` (predefinito) o `any`, al primo livello e in ogni gruppo.
- Ometti `conditions`, o non inviare gruppi, per includere tutti i contatti dell’origine. I gruppi vuoti vengono scartati.
- Viene accettata anche la forma piatta `{ "match": "any", "rules": [...] }`, salvata come un unico gruppo.
- Un segmento può avere fino a 10 gruppi e 50 regole in tutto.

### Campi

| Campo | Tipo | Note |
| --- | --- | --- |
| `email` | string | |
| `email_domain` | string | La parte dell’indirizzo dopo `@`. |
| `first_name`, `last_name` | string | |
| `status` | enum | `subscribed` (non disiscritto a livello globale e iscritto ad almeno una lista, quindi raggiungibile dalle campagne) o `unsubscribed`. Operatori: `equals`, `not_equals`. |
| `created_at`, `updated_at` | datetime | Quando il contatto è stato creato o modificato l’ultima volta, con il confronto in UTC. |
| `audience` | audience | Iscrizione attiva alle liste. `in` corrisponde ai contatti iscritti ad almeno una delle liste indicate, `not_in` ai contatti non iscritti a nessuna di esse. |
| `tags` | tags | I [tag](/it/docs/contacts/tags-and-score/) del contatto. I valori vengono confrontati in minuscolo. |
| `score` | score | Il [lead score](/it/docs/contacts/tags-and-score/#lead-score) del contatto. |
| `custom_fields.<key>` | dipende dal campo | I campi di testo sono `string`, i campi numerici `number`, i campi data `date` (`YYYY-MM-DD`), i campi booleani `boolean`, i campi a selezione `enum` e i campi a selezione multipla `multi`. |
| `orders_count`, `total_spent`, `average_order_value` | metric | Dagli [ordini](/it/docs/commerce/) del contatto. 0 per i contatti senza ordini. Gli importi sono nella valuta degli ordini del contatto. |
| `first_order_at`, `last_order_at` | moment | Non impostati per i contatti senza ordini. |
| `expected_next_order_at` | moment | L’ultimo ordine più l’intervallo medio tra gli ordini del contatto. Impostato a partire dal secondo ordine, e può essere nel futuro. |
| `churn_risk` | enum | `low`, `medium` o `high`: il tempo trascorso dall’ultimo ordine confrontato con l’intervallo abituale del contatto (almeno 14 giorni), oppure con 90 giorni per chi ha acquistato una sola volta. Non impostato senza ordini. |
| `last_active_at` | moment | L’ultima volta in cui lo [script di tracciamento](/it/docs/commerce/connect-your-shop/#the-tracking-script) ha visto il contatto sul tuo sito. |
| `purchased` | purchase | Ordini, vedi [Regole di attività](#activity-rules). |
| `viewed_product` | view | Visualizzazioni di prodotto registrate dallo script di tracciamento. |
| `cart` | cart | Carrelli aperti e abbandonati. |
| `used_coupon` | coupon | Ordini che hanno usato un codice coupon. |
| `campaign_activity` | campaign_activity | Email di campagne ricevute, aperte o cliccate. |

[Elenca i campi dei segmenti](/it/docs/api-reference/segments/fields/) restituisce i campi del workspace, compresi i campi personalizzati e le liste, con gli operatori accettati da ciascuno.

### Operatori

| Tipo | Operatori |
| --- | --- |
| 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` (ne ha almeno uno), `contains_all` (li ha tutti), `not_in` (non ne ha nessuno), `is_set`, `is_not_set` |
| audience | `in`, `not_in` |
| tags | `in` (ne ha almeno uno), `contains_all` (li ha tutti), `not_in` (non ne ha nessuno), `is_set` (ha almeno un tag), `is_not_set` (non ha tag) |
| 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` |

### Valori

- I confronti di testo sui campi string non distinguono tra maiuscole e minuscole. I valori dei campi a selezione e a selezione multipla devono corrispondere esattamente.
- `not_equals`, `not_contains` e `not_in` corrispondono anche ai contatti che non hanno un valore.
- `in`, `not_in` e `contains_all` accettano un elenco di fino a 100 valori. I valori di testo possono arrivare a 500 caratteri.
- `between` accetta `[from, to]`, estremi inclusi: due numeri o due date `YYYY-MM-DD`.
- `on`, `before` e `after` accettano una data `YYYY-MM-DD`. `before` e `after` non includono quel giorno.
- `in_last_days`, `more_than_days_ago` e `in_next_days` accettano un numero intero di giorni da 1 a 3650, contati dal momento in cui il segmento viene valutato. I campi personalizzati di tipo data confrontano giorni di calendario in UTC; `created_at` e `updated_at` usano orari esatti, quindi `in_last_days` con `7` significa le ultime 7 × 24 ore.
- `is_set`, `is_not_set`, `is_true` e `is_false` non accettano valori. `is_true` corrisponde a `true`, `1`, `yes` e `on`; `is_false` corrisponde a `false`, `0`, `no` e `off`.
- Una regola salvata che non è più applicabile, ad esempio perché il suo campo personalizzato ha cambiato tipo, non corrisponde a nessun contatto. Le regole su un campo personalizzato eliminato continuano a funzionare con i valori che i contatti hanno ancora, ma le nuove regole devono usare un campo esistente.

### Regole di attività

`purchased`, `viewed_product`, `cart`, `used_coupon` e `campaign_activity` accettano un oggetto come `value`. Tutte le chiavi sono facoltative.

| Campo | Chiavi del valore |
| --- | --- |
| `purchased` | `days`: solo gli ordini effettuati negli ultimi N giorni. `product_ids`: gli ordini con uno qualsiasi di questi prodotti (gli ID dei prodotti del tuo negozio). `categories`: gli ordini con un prodotto in una qualsiasi di queste categorie. `min_count`: almeno questo numero di ordini corrispondenti (predefinito 1, fino a 1000). Gli ordini annullati non contano. |
| `viewed_product` | `days`, `product_ids`, `categories` e `min_count` come sopra, contando le visualizzazioni di prodotto. |
| `cart` | `days` solo con `has_abandoned_cart`: i carrelli abbandonati negli ultimi N giorni. `has_open_cart` corrisponde a un carrello attivo, `has_no_open_cart` ai contatti senza carrelli attivi o abbandonati. |
| `used_coupon` | `days`, e `coupon`: la chiave di un [coupon](/it/docs/commerce/coupons/). Senza `coupon`, conta qualsiasi codice. |
| `campaign_activity` | `campaign_id`: una campagna (`cmp_...`), qualsiasi campagna se assente. `days`: solo gli ultimi N giorni, da sempre se assente. |

`days` è un numero intero da 1 a 3650. `has_not` è l’opposto di `has` con lo stesso valore.

```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` corrispondono ai contatti che hanno ricevuto almeno un’email di campagna corrispondente e non ne hanno aperta o cliccata nessuna. Le aperture sono approssimative: Apple Mail carica le immagini di ogni email che riceve.

## Restituisce

Restituisce `201 Created` con l’[oggetto segmento](/it/docs/api-reference/segments/get/), compresi `contacts_count` e `subscribed_count`. Un nuovo segmento tracciato parte con `tracking.status` impostato a `syncing` mentre Emailit registra i suoi membri attuali.

| Stato | Quando |
| --- | --- |
| `400` | `name` manca, oppure un campo ha il tipo sbagliato. |
| `403` | `tracked` è `true` e il piano non include i segmenti tracciati. Il corpo è `{"error": "plan_required", "required_plan": "pro", ...}`. |
| `422` | Un campo o una regola non è valido: `errors` ha come chiave il suo percorso, ad esempio `conditions.groups.0.rules.1.value`, e `message` ripete il primo problema. Viene restituito anche quando il workspace ha raggiunto il limite di segmenti del piano; in quel caso il corpo contiene `usage.used` e `usage.limit`. |

**Richiesta** `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 Convalida**

```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/it/docs/api-reference/segments/create/

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

> Recupera un segmento con la sua origine, le regole, lo stato del tracciamento e i conteggi dei contatti in tempo reale. Alpha: aperti solo al team di Emailit.

# Recupera un segmento

Recupera un segmento e ne conta i contatti nel momento in cui lo chiami. Richiede una chiave API `full`.

`GET /segments/{id}`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del segmento (`seg_…`).

## Restituisce

Restituisce l’oggetto segmento.

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

- `id` (string): ID del segmento, con prefisso `seg_`.

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

- `description` (string | null): Nota per il team.

- `audience_ids` (string[]): Le liste di origine. Vuoto significa tutti i contatti del workspace.

- `conditions` (object): Le regole, nella forma `{ "match", "groups": [{ "match", "rules": [...] }] }`. Vedi [Crea un segmento](/it/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Indica se il segmento memorizza i suoi membri e segnala ingressi e uscite. Vedi [Segmenti tracciati](/it/docs/segments/tracked/).

- `tracking` (object | null): `null` per i segmenti non tracciati. Per i segmenti tracciati: - `status`: `active` quando i membri sono aggiornati, `syncing` mentre Emailit registra i membri attuali dopo la creazione del segmento o la ripresa del tracciamento, oppure `paused` quando il piano del workspace non include più i segmenti tracciati. - `synced_at`: quando l’intero segmento è stato confrontato l’ultima volta con le sue regole, oppure `null` prima del primo confronto.

- `contacts_count` (integer): Contatti che corrispondono in questo momento.

- `subscribed_count` (integer): La parte di `contacts_count` a cui le campagne possono inviare: i contatti non disiscritti a livello globale e iscritti ad almeno una lista. Gli indirizzi soppressi vengono comunque contati.

- `created_at, updated_at` (string): Timestamp in UTC.

Restituisce `404` se il segmento non esiste.

**Richiesta** `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/it/docs/api-reference/segments/get/

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

> Modifica il nome, la descrizione, le liste di origine o le regole di un segmento. Non si può cambiare se un segmento è tracciato o no. Alpha: aperti solo al team di Emailit.

# Aggiorna un segmento

Aggiorna i campi che passi e lascia invariati gli altri. `audience_ids` e `conditions` vengono sostituiti per intero. Richiede una chiave API `full`.

Le campagne valutano un segmento al momento dell’invio, quindi le nuove regole valgono per tutte le campagne non ancora inviate, comprese quelle programmate.

In un [segmento tracciato](/it/docs/segments/tracked/), la modifica di `audience_ids` o `conditions` confronta i membri memorizzati con le nuove regole. I contatti che entrano o escono a causa della modifica generano gli eventi `segment.contact_added` e `segment.contact_removed` con `reason` impostato a `segment_updated`. I webhook li ricevono, ma non avviano automazioni.

`POST /segments/{id}`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del segmento (`seg_…`).

## Parametri del corpo

- `name` (string): Nuovo nome, fino a 191 caratteri. Non può essere vuoto.

- `description` (string | null): Nota per il team, fino a 1000 caratteri. `null` o una stringa vuota la cancellano.

- `audience_ids` (string[]): ID delle liste di origine. `[]` significa tutti i contatti del workspace.

- `conditions` (object): Le regole. Vedi [Crea un segmento](/it/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Accettato solo con il valore attuale del segmento. Il tracciamento si sceglie quando si crea un segmento; per cambiarlo, crea un nuovo segmento.

## Restituisce

Restituisce l’[oggetto segmento](/it/docs/api-reference/segments/get/) aggiornato, con i conteggi ricalcolati.

| Stato | Quando |
| --- | --- |
| `404` | Il segmento non esiste. |
| `422` | Un campo o una regola non è valido, oppure `tracked` è diverso dal valore attuale del segmento. `errors` ha come chiavi i percorsi dei campi. |

**Richiesta** `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/it/docs/api-reference/segments/update/

## Elenca i segmenti — GET /segments

> Elenca i segmenti di un workspace, a partire dal più recente, con i conteggi in tempo reale facoltativi e l’utilizzo dei segmenti del piano. Alpha: aperti solo al team di Emailit.

# Elenca i segmenti

Restituisce i segmenti del workspace, a partire dal più recente, insieme a quanti dei segmenti inclusi nel piano sono in uso. Richiede una chiave API `full`.

`GET /segments`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di query

- `page` (integer): Numero della pagina, a partire da 1.

- `limit` (integer): Segmenti per pagina, da 1 a 100.

- `search` (string): Corrispondenza su una parte del nome del segmento, senza distinzione tra maiuscole e minuscole.

- `with_counts` (boolean): Aggiunge `contacts_count` e `subscribed_count` a ogni segmento. Il conteggio valuta ogni segmento della pagina, quindi è disattivato per impostazione predefinita.

- `match`, `order`, `direction`: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

### Chiavi di filtro

I filtri usano parametri di query `key.condition=value`, ad esempio `name.contains=customers` o `created_at.after=2026-09-01`. Per le condizioni di ogni tipo, vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `created_at` | date | |
| `updated_at` | date | |

Chiavi di ordinamento per `order`: `name`, `created_at`, `updated_at`.

## Restituisce

- `data` (object[]): Gli [oggetti segmento](/it/docs/api-reference/segments/get/) di questa pagina. `contacts_count` e `subscribed_count` sono presenti solo con `with_counts`.

- `total_records` (integer): Numero di segmenti che corrispondono alla query.

- `usage` (object): I segmenti del workspace rispetto al piano: `used` (tutti i segmenti, tracciati o no), `limit` (i segmenti inclusi nel piano) e `tracking_allowed` (indica se il piano include i segmenti tracciati). Vedi [Limiti e quote](/it/docs/limits/#plan-limits).

- `next_page_url` (string | null): Percorso della pagina successiva, oppure `null` sull’ultima pagina. Contiene solo `page` e `limit`; quando lo segui, aggiungi di nuovo la ricerca e i filtri.

- `previous_page_url` (string | null): Percorso della pagina precedente, oppure `null` sulla prima pagina.

**Richiesta** `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/it/docs/api-reference/segments/list/

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

> Elimina un segmento. Le bozze di campagna che inviano al segmento lo perdono; quelle che lo escludono non si possono inviare finché non sostituisci l’esclusione. Le campagne programmate o in invio e le automazioni che usano il segmento bloccano l’eliminazione. Alpha: aperti solo al team di Emailit.

# Elimina un segmento

Elimina un segmento. Richiede una chiave API `full`.

- Un segmento usato da una campagna programmata, in coda, in invio o in test non si può eliminare. Prima cambia i destinatari della campagna.
- Un segmento non si può eliminare finché un’automazione non eliminata, in qualsiasi stato, lo usa: in un trigger **Added to segment** o **Removed from segment**, in un obiettivo, in un passaggio **Wait until** o in una condizione di uscita su questi eventi, oppure in una regola **Segment** di una condizione. Prima modifica queste automazioni.
- Le bozze di campagna che inviano al segmento lo perdono dai destinatari, e `removed_from_campaigns` indica quante sono. Le bozze che escludono il segmento mantengono l’esclusione, quindi non si possono inviare finché non la sostituisci: toglierla invierebbe la campagna alle persone che volevi escludere. Le campagne inviate, annullate e archiviate mantengono il riferimento come cronologia.
- Per un segmento tracciato vengono eliminati anche i membri memorizzati e la cronologia della crescita.

`DELETE /segments/{id}`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del segmento (`seg_…`).

## Restituisce

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

- `id` (string): ID del segmento eliminato.

- `name` (string): Il suo nome.

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

- `removed_from_campaigns` (integer): Numero di bozze di campagna che non inviano più al segmento.

| Stato | Quando |
| --- | --- |
| `404` | Il segmento non esiste. |
| `409` | Una campagna programmata, in coda, in invio o in test usa il segmento, oppure un’automazione parte dal segmento. Il messaggio le indica per nome. |

**Richiesta** `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 Campagne**

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

```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/it/docs/api-reference/segments/delete/

## Elenca i contatti di un segmento — GET /segments/{id}/contacts

> Elenca i contatti che corrispondono a un segmento in questo momento, con la ricerca, i filtri dell’elenco dei contatti e, per i segmenti tracciati, quando è entrato ogni contatto. Alpha: aperti solo al team di Emailit.

# Elenca i contatti di un segmento

Restituisce i contatti che corrispondono al segmento nel momento in cui lo chiami, a partire dal più recente. Richiede una chiave API `full`.

`GET /segments/{id}/contacts`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del segmento (`seg_…`).

## Parametri di query

- `page` (integer): Numero della pagina, a partire da 1.

- `limit` (integer): Contatti per pagina, da 1 a 100.

- `search` (string): Corrispondenza su una parte dell’indirizzo email, del nome o del cognome, senza distinzione tra maiuscole e minuscole.

- `match`, `order`, `direction`: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

### Chiavi di filtro

I contatti di un segmento accettano le stesse chiavi di filtro e di ordinamento di [Elenca i contatti](/it/docs/api-reference/contacts/list/), applicate in aggiunta al segmento, ad esempio `email.ends_with=acme.com`.

Chiavi di filtro e di ordinamento: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

## Restituisce

- `data` (object[]): I contatti di questa pagina, ciascuno con `object`, `id`, `email`, `first_name`, `last_name`, `custom_fields`, `unsubscribed`, `audiences` (`id`, `name`, `subscribed`), `created_at` e `updated_at`. I contatti di un [segmento tracciato](/it/docs/segments/tracked/) hanno anche `joined_at`.

- `data[].joined_at` (string | null): Solo per i segmenti tracciati: quando è iniziata la permanenza attuale del contatto nel segmento. `null` finché il tracciamento non ha registrato il contatto, ad esempio subito dopo che ha iniziato a corrispondere, mentre il segmento è `syncing` o mentre il tracciamento è `paused`.

- `total_records` (integer): Numero di contatti che corrispondono al segmento, alla ricerca e ai filtri.

- `subscribed_count` (integer): A quanti di loro le campagne possono inviare: non disiscritti a livello globale e iscritti ad almeno una lista.

- `next_page_url` (string | null): Percorso della pagina successiva, oppure `null` sull’ultima pagina. Contiene `page`, `limit` e `search`; quando lo segui, aggiungi di nuovo i filtri.

- `previous_page_url` (string | null): Percorso della pagina precedente, oppure `null` sulla prima pagina.

Restituisce `404` se il segmento non esiste.

**Richiesta** `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/it/docs/api-reference/segments/contacts/

## Recupera la crescita di un segmento — GET /segments/{id}/growth

> Numero giornaliero di membri, ingressi e uscite di un segmento tracciato, una riga per giorno UTC, fino a 365 giorni. Alpha: aperti solo al team di Emailit.

# Recupera la crescita di un segmento

Restituisce la cronologia di un [segmento tracciato](/it/docs/segments/tracked/): una riga per giorno UTC, a partire dal meno recente, fino a oggi. Sono i dati del grafico **Growth** nella pagina del segmento. Richiede una chiave API `full`.

La cronologia inizia quando inizia il tracciamento. I contatti registrati dal primo conteggio dopo la creazione del segmento, o dopo la ripresa del tracciamento, contano come membri ma non come ingressi.

`GET /segments/{id}/growth`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del segmento (`seg_…`).

## Parametri di query

- `days` (integer): Numero di giorni da restituire, da 1 a 365, fino a oggi.

## Restituisce

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

- `segment_id` (string): L’ID del segmento.

- `data` (object[]): Una riga per giorno.

- `data[].date` (string): Il giorno UTC, `YYYY-MM-DD`.

- `data[].members_count` (integer | null): I membri alla fine del giorno, oppure il conteggio più recente per oggi. I giorni senza un nuovo conteggio riportano il valore precedente, ad esempio mentre il tracciamento è in pausa. `null` prima dell’inizio del tracciamento.

- `data[].joined_count` (integer): Contatti entrati nel segmento quel giorno.

- `data[].left_count` (integer): Contatti usciti dal segmento quel giorno.

| Stato | Quando |
| --- | --- |
| `404` | Il segmento non esiste. |
| `422` | Il segmento non è tracciato. |

**Richiesta** `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/it/docs/api-reference/segments/growth/

## Visualizza l’anteprima di un segmento — POST /segments/preview

> Conta i contatti che una definizione di segmento conterrebbe e ne restituisce un campione, senza salvarla. Alpha: aperti solo al team di Emailit.

# Visualizza l’anteprima di un segmento

Controlla una definizione di segmento senza salvarla: restituisce quanti contatti corrispondono e un campione di essi. La definizione viene convalidata come in [Crea un segmento](/it/docs/api-reference/segments/create/), e un’anteprima non rientra nel limite di segmenti del piano. Richiede una chiave API `full`.

`POST /segments/preview`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Parametri del corpo

- `audience_ids` (string[]): ID delle liste da cui attingerebbe il segmento. Vuoto o omesso significa tutti i contatti.

- `conditions` (object): Le regole. Vedi [Crea un segmento](/it/docs/api-reference/segments/create/#conditions).

- `limit` (integer): Numero di contatti del campione, da 1 a 25.

## Restituisce

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

- `audience_ids` (string[]): Le liste di origine, senza duplicati.

- `conditions` (object): Le regole come verrebbero salvate: un `{ match, rules }` piatto diventa un unico gruppo e i gruppi vuoti vengono scartati.

- `contacts_count` (integer): Contatti che corrispondono.

- `subscribed_count` (integer): A quanti di loro le campagne possono inviare.

- `contacts` (object[]): I contatti corrispondenti più recenti, nella stessa forma di [Elenca i contatti di un segmento](/it/docs/api-reference/segments/contacts/).

Restituisce `422` con `errors`, che ha come chiavi i percorsi dei campi, se la definizione non è valida.

**Richiesta** `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/it/docs/api-reference/segments/preview/

## Elenca i campi dei segmenti — GET /segments/fields

> Elenca i campi del contatto, i campi personalizzati e le liste che le regole dei segmenti possono usare, con gli operatori e i valori accettati da ciascuno. Alpha: aperti solo al team di Emailit.

# Elenca i campi dei segmenti

Restituisce i campi che le regole dei segmenti possono usare in questo workspace: i campi del contatto, ogni campo personalizzato (con il tipo dato dal tipo del campo personalizzato), l’appartenenza alle liste, i dati di acquisto e l’engagement con le campagne. Richiede una chiave API `full`.

`GET /segments/fields`

> **I segmenti sono in alpha:** I segmenti sono aperti solo al team di Emailit mentre li testiamo. Le altre richieste, comprese tutte quelle fatte con una chiave API, restituiscono `403` con `error: "segments_alpha"`. Vedi [Chi può usare i segmenti](/it/docs/segments/#who-can-use-segments).

## Restituisce

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

- `data[].key` (string): Il valore da usare come `field` di una regola, ad esempio `email_domain` o `custom_fields.plan`.

- `data[].label` (string): Nome visualizzato. Per i campi personalizzati, il nome del campo personalizzato.

- `data[].type` (string): `string`, `number`, `date`, `datetime`, `boolean`, `enum`, `multi`, `audience`, `metric`, `moment`, `purchase`, `view`, `cart`, `coupon` o `campaign_activity`. Vedi [Crea un segmento](/it/docs/api-reference/segments/create/#fields). I campi di attività come `purchased` accettano un oggetto come valore, vedi [Regole di attività](/it/docs/api-reference/segments/create/#activity-rules).

- `data[].group` (string): `contact`, `custom_fields`, `audiences`, `commerce` (dati di acquisto) o `engagement` (attività sulle campagne).

- `data[].operators` (string[]): Gli operatori accettati dal campo.

- `data[].values` (object[]): Valori consentiti, come `value` e `label`: le opzioni dei campi personalizzati a selezione e a selezione multipla, `subscribed` e `unsubscribed` per `status` e le liste del workspace per `audience`. Assente per gli altri campi.

**Richiesta** `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/it/docs/api-reference/segments/fields/