# Segments API

> Enregistrez des filtres sur vos contacts, listez ceux qui correspondent et suivez l’évolution des segments avec suivi.

URL de base : `https://api.emailit.com/v2`. Authentifiez-vous avec `Authorization: Bearer <API key>`.

## Créer un segment — POST /segments

> Créez un segment, un filtre enregistré sur vos contacts, à partir de tous les contacts ou de listes choisies, et indiquez s’il s’agit d’un segment avec suivi. Alpha : réservé à l’équipe Emailit.

# Créer un segment

Crée un segment : un filtre enregistré sur les contacts de l’espace de travail. Nécessite une clé API avec la portée `full`.

Un segment contient les contacts de sa source (les abonnés des listes `audience_ids`, ou tous les contacts si ce champ est vide) qui correspondent à ses `conditions`. L’appartenance est évaluée en direct chaque fois que le segment est compté, listé, prévisualisé ou utilisé par une campagne au moment de son envoi. Consultez [Segments](/fr/docs/segments/).

Chaque forfait inclut un nombre de segments par espace de travail, avec ou sans suivi. Consultez [Limites](/fr/docs/limits/#plan-limits).

`POST /segments`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres du corps

- `name` (string, obligatoire): Nom du segment, 191 caractères au maximum.

- `description` (string | null): Note pour votre équipe, 1 000 caractères au maximum.

- `audience_ids` (string[]): La source : des ID de listes (`aud_…`) de cet espace de travail, 100 au maximum. Le segment ne contient que les contacts abonnés à au moins l’une d’elles. Vide ou omis : tous les contacts de l’espace de travail.

- `conditions` (object): Les règles auxquelles les contacts doivent correspondre, décrites dans [Conditions](#conditions). Omettez-le pour inclure toutes les personnes de la source.

- `tracked` (boolean): Enregistre les membres du segment pour que les entrées et les sorties de contacts deviennent des événements pour les [automatisations](/fr/docs/automations/triggers/#segment-triggers) et les [webhooks](/fr/docs/webhooks/event-types/#segment-events). Inclus dans les forfaits Pro, Business et Custom. Vous le choisissez ici et ne pouvez plus le modifier ensuite. Consultez [Segments avec suivi](/fr/docs/segments/tracked/).

## Conditions

`conditions` contient des groupes de règles. Le `match` de premier niveau combine les groupes, et le `match` de chaque groupe combine ses règles :

```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` vaut `all` (par défaut) ou `any`, au premier niveau et dans chaque groupe.
- Omettez `conditions`, ou n’envoyez aucun groupe, pour inclure toutes les personnes de la source. Les groupes vides sont retirés.
- La forme à plat `{ "match": "any", "rules": [...] }` est aussi acceptée et enregistrée comme un seul groupe.
- Un segment peut avoir jusqu’à 10 groupes et 50 règles au total.

### Champs

| Champ | Type | Remarques |
| --- | --- | --- |
| `email` | string | |
| `email_domain` | string | La partie de l’adresse après `@`. |
| `first_name`, `last_name` | string | |
| `status` | enum | `subscribed` (pas désinscrit de toutes les listes et abonné à au moins une liste : les campagnes peuvent donc atteindre le contact) ou `unsubscribed`. Opérateurs : `equals`, `not_equals`. |
| `created_at`, `updated_at` | datetime | Date de création ou de dernière modification du contact, comparée en UTC. |
| `audience` | audience | Appartenance avec abonnement. `in` correspond aux contacts abonnés à l’une des listes indiquées, `not_in` aux contacts abonnés à aucune d’elles. |
| `tags` | tags | Les [tags](/fr/docs/contacts/tags-and-score/) du contact. Les valeurs sont comparées en minuscules. |
| `score` | score | Le [score de lead](/fr/docs/contacts/tags-and-score/#lead-score) du contact. |
| `custom_fields.<key>` | selon le champ | Les champs texte sont de type `string`, les champs nombre `number`, les champs date `date` (`YYYY-MM-DD`), les champs booléens `boolean`, les listes déroulantes `enum` et les champs à choix multiple `multi`. |
| `orders_count`, `total_spent`, `average_order_value` | metric | Calculés à partir des [commandes](/fr/docs/commerce/) du contact. 0 pour les contacts sans commande. Les montants sont dans la devise des commandes du contact. |
| `first_order_at`, `last_order_at` | moment | Non définis pour les contacts sans commande. |
| `expected_next_order_at` | moment | La dernière commande plus l’intervalle moyen entre les commandes du contact. Défini à partir de la deuxième commande, et peut se situer dans le futur. |
| `churn_risk` | enum | `low`, `medium` ou `high` : le temps écoulé depuis la dernière commande comparé à l’intervalle habituel du contact (au moins 14 jours), ou à 90 jours pour les acheteurs d’une seule commande. Non défini sans commande. |
| `last_active_at` | moment | La dernière fois que le [script de suivi](/fr/docs/commerce/connect-your-shop/#the-tracking-script) a vu le contact sur votre site. |
| `purchased` | purchase | Les commandes, voir [Règles d’activité](#activity-rules). |
| `viewed_product` | view | Les consultations de produit enregistrées par le script de suivi. |
| `cart` | cart | Les paniers ouverts et abandonnés. |
| `used_coupon` | coupon | Les commandes qui ont utilisé un code de réduction. |
| `campaign_activity` | campaign_activity | Les e-mails de campagne reçus, ouverts ou cliqués. |

[Lister les champs de segment](/fr/docs/api-reference/segments/fields/) renvoie les champs de votre espace de travail, y compris ses champs personnalisés et ses listes, avec les opérateurs acceptés par chacun.

### Opérateurs

| Type | Opérateurs |
| --- | --- |
| 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` (contient l’une des valeurs), `contains_all` (contient toutes les valeurs), `not_in` (ne contient aucune des valeurs), `is_set`, `is_not_set` |
| audience | `in`, `not_in` |
| tags | `in` (contient l’un des tags), `contains_all` (contient tous les tags), `not_in` (ne contient aucun des tags), `is_set` (a au moins un tag), `is_not_set` (n’a aucun 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` |

### Valeurs

- Les comparaisons de texte sur les champs de type string ignorent la casse. Les valeurs des listes déroulantes et des champs à choix multiple doivent correspondre exactement.
- `not_equals`, `not_contains` et `not_in` correspondent aussi aux contacts sans valeur.
- `in`, `not_in` et `contains_all` acceptent une liste de 100 valeurs au maximum. Les valeurs texte peuvent compter jusqu’à 500 caractères.
- `between` accepte `[from, to]`, bornes incluses : deux nombres ou deux dates `YYYY-MM-DD`.
- `on`, `before` et `after` acceptent une date `YYYY-MM-DD`. `before` et `after` n’incluent pas ce jour.
- `in_last_days`, `more_than_days_ago` et `in_next_days` acceptent un nombre entier de jours compris entre 1 et 3650, compté à partir du moment où le segment est évalué. Les champs personnalisés de type date comparent des jours calendaires en UTC ; `created_at` et `updated_at` utilisent des heures exactes : `in_last_days` avec `7` désigne donc les 7 × 24 dernières heures.
- `is_set`, `is_not_set`, `is_true` et `is_false` n’acceptent pas de valeur. `is_true` correspond à `true`, `1`, `yes` et `on` ; `is_false` correspond à `false`, `0`, `no` et `off`.
- Une règle enregistrée qui ne s’applique plus, par exemple après un changement de type de son champ personnalisé, ne correspond à aucun contact. Les règles portant sur un champ personnalisé supprimé continuent de fonctionner avec les valeurs que les contacts possèdent encore, mais les nouvelles règles doivent utiliser un champ existant.

### Règles d’activité

`purchased`, `viewed_product`, `cart`, `used_coupon` et `campaign_activity` acceptent un objet comme `value`. Toutes les clés sont facultatives.

| Champ | Clés de la valeur |
| --- | --- |
| `purchased` | `days` : uniquement les commandes passées au cours des N derniers jours. `product_ids` : les commandes contenant l’un de ces produits (les ID de produit de votre boutique). `categories` : les commandes contenant un produit de l’une de ces catégories. `min_count` : au moins ce nombre de commandes correspondantes (1 par défaut, 1000 au maximum). Les commandes annulées ne comptent pas. |
| `viewed_product` | `days`, `product_ids`, `categories` et `min_count` comme ci-dessus, en comptant les consultations de produit. |
| `cart` | `days`, avec `has_abandoned_cart` uniquement : les paniers abandonnés au cours des N derniers jours. `has_open_cart` correspond à un panier actif, `has_no_open_cart` aux contacts sans panier actif ni abandonné. |
| `used_coupon` | `days`, et `coupon` : la clé d’un [coupon](/fr/docs/commerce/coupons/). Sans `coupon`, n’importe quel code compte. |
| `campaign_activity` | `campaign_id` : une campagne (`cmp_...`), n’importe quelle campagne s’il est absent. `days` : uniquement les N derniers jours, toute la période s’il est absent. |

`days` est un nombre entier compris entre 1 et 3650. `has_not` est l’inverse de `has` avec la même valeur.

```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` et `received_not_clicked` correspondent aux contacts qui ont reçu au moins un e-mail de campagne correspondant et n’en ont ouvert ou cliqué aucun. Les ouvertures sont approximatives : Apple Mail charge les images de chaque e-mail qu’il reçoit.

## Réponse

Renvoie `201 Created` avec l’[objet segment](/fr/docs/api-reference/segments/get/), y compris `contacts_count` et `subscribed_count`. Un nouveau segment avec suivi démarre avec `tracking.status` défini sur `syncing` pendant qu’Emailit enregistre ses membres actuels.

| Statut | Cas |
| --- | --- |
| `400` | `name` est absent, ou un champ a un type incorrect. |
| `403` | `tracked` vaut `true` et le forfait n’inclut pas les segments avec suivi. Le corps est `{"error": "plan_required", "required_plan": "pro", ...}`. |
| `422` | Un champ ou une règle est invalide : `errors` est indexé par son chemin, comme `conditions.groups.0.rules.1.value`, et `message` reprend le premier problème. Renvoyé aussi lorsque l’espace de travail a atteint la limite de segments de son forfait ; ce corps inclut alors `usage.used` et `usage.limit`. |

**Requête** `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 Validation**

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

---
Source: https://emailit.com/fr/docs/api-reference/segments/create/

## Récupérer un segment — GET /segments/{id}

> Récupérez un segment avec sa source, ses règles, l’état de son suivi et le nombre de ses contacts en direct. Alpha : réservé à l’équipe Emailit.

# Récupérer un segment

Récupère un segment et compte ses contacts au moment de l’appel. Nécessite une clé API avec la portée `full`.

`GET /segments/{id}`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du segment (`seg_…`).

## Réponse

Renvoie l’objet segment.

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

- `id` (string): ID du segment, préfixé par `seg_`.

- `name` (string): Nom du segment.

- `description` (string | null): Note pour votre équipe.

- `audience_ids` (string[]): Les listes sources. Vide : tous les contacts de l’espace de travail.

- `conditions` (object): Les règles, sous la forme `{ "match", "groups": [{ "match", "rules": [...] }] }`. Consultez [Créer un segment](/fr/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Indique si le segment enregistre ses membres et signale les entrées et les sorties. Consultez [Segments avec suivi](/fr/docs/segments/tracked/).

- `tracking` (object | null): `null` pour les segments sans suivi. Pour les segments avec suivi : - `status` : `active` lorsque les membres sont tenus à jour, `syncing` pendant qu’Emailit enregistre les membres actuels après la création du segment ou la reprise du suivi, ou `paused` lorsque le forfait de l’espace de travail n’inclut plus les segments avec suivi. - `synced_at` : date de la dernière comparaison de l’ensemble du segment avec ses règles, ou `null` avant la première comparaison.

- `contacts_count` (integer): Contacts qui correspondent en ce moment.

- `subscribed_count` (integer): La partie de `contacts_count` à laquelle les campagnes peuvent envoyer : les contacts qui ne sont pas désinscrits de toutes les listes et qui sont abonnés à au moins une liste. Les adresses bloquées sont tout de même comptées.

- `created_at, updated_at` (string): Horodatages en UTC.

Renvoie `404` si le segment n’existe pas.

**Requête** `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"
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/get/

## Mettre à jour un segment — POST /segments/{id}

> Modifiez le nom, la description, les listes sources ou les règles d’un segment. Le suivi d’un segment ne peut pas être modifié. Alpha : réservé à l’équipe Emailit.

# Mettre à jour un segment

Met à jour les champs transmis et laisse les autres inchangés. `audience_ids` et `conditions` sont remplacés dans leur intégralité. Nécessite une clé API avec la portée `full`.

Les campagnes évaluent un segment au moment de leur envoi : les nouvelles règles s’appliquent donc à toutes les campagnes qui n’ont pas encore été envoyées, y compris les campagnes programmées.

Sur un [segment avec suivi](/fr/docs/segments/tracked/), modifier `audience_ids` ou `conditions` compare les membres enregistrés avec les nouvelles règles. Les contacts qui entrent ou sortent à cause de la modification envoient des événements `segment.contact_added` et `segment.contact_removed` avec `reason` défini sur `segment_updated`. Les webhooks les reçoivent, mais ils ne démarrent pas d’automatisation.

`POST /segments/{id}`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du segment (`seg_…`).

## Paramètres du corps

- `name` (string): Nouveau nom, 191 caractères au maximum. Ne peut pas être vide.

- `description` (string | null): Note pour votre équipe, 1 000 caractères au maximum. `null` ou une chaîne vide l’efface.

- `audience_ids` (string[]): ID des listes sources. `[]` signifie tous les contacts de l’espace de travail.

- `conditions` (object): Les règles. Consultez [Créer un segment](/fr/docs/api-reference/segments/create/#conditions).

- `tracked` (boolean): Accepté uniquement avec la valeur actuelle du segment. Le suivi se choisit à la création d’un segment ; pour le modifier, créez un nouveau segment.

## Réponse

Renvoie l’[objet segment](/fr/docs/api-reference/segments/get/) mis à jour, avec des nombres actualisés.

| Statut | Cas |
| --- | --- |
| `404` | Le segment n’existe pas. |
| `422` | Un champ ou une règle est invalide, ou `tracked` diffère de la valeur actuelle du segment. `errors` est indexé par chemin de champ. |

**Requête** `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."
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/update/

## Lister les segments — GET /segments

> Listez les segments d’un espace de travail, du plus récent au plus ancien, avec en option le nombre de contacts en direct et l’utilisation des segments inclus dans le forfait. Alpha : réservé à l’équipe Emailit.

# Lister les segments

Renvoie les segments de l’espace de travail, du plus récent au plus ancien, avec le nombre de segments du forfait déjà utilisés. Nécessite une clé API avec la portée `full`.

`GET /segments`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de requête

- `page` (integer): Numéro de page, à partir de 1.

- `limit` (integer): Segments par page, de 1 à 100.

- `search` (string): Correspondance insensible à la casse sur une partie du nom du segment.

- `with_counts` (boolean): Ajoute `contacts_count` et `subscribed_count` à chaque segment. Le décompte évalue chaque segment de la page : il est donc désactivé par défaut.

- `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

### Clés de filtre

Les filtres utilisent des paramètres de requête `key.condition=value`, par exemple `name.contains=customers` ou `created_at.after=2026-09-01`. Pour les conditions disponibles selon le type, consultez [Filtrage et tri](/fr/docs/api-reference/filtering/).

| Clé | Type | Remarques |
| --- | --- | --- |
| `name` | chaîne | |
| `created_at` | date | |
| `updated_at` | date | |

Clés de tri pour `order` : `name`, `created_at`, `updated_at`.

## Réponse

- `data` (object[]): [Objets segment](/fr/docs/api-reference/segments/get/) de cette page. `contacts_count` et `subscribed_count` ne sont inclus qu’avec `with_counts`.

- `total_records` (integer): Nombre de segments qui correspondent à la requête.

- `usage` (object): Les segments de l’espace de travail par rapport à son forfait : `used` (tous les segments, avec ou sans suivi), `limit` (segments inclus dans le forfait) et `tracking_allowed` (indique si le forfait inclut les segments avec suivi). Consultez [Limites](/fr/docs/limits/#plan-limits).

- `next_page_url` (string | null): Chemin de la page suivante, ou `null` sur la dernière page. Il ne contient que `page` et `limit` ; ajoutez de nouveau votre recherche et vos filtres lorsque vous le suivez.

- `previous_page_url` (string | null): Chemin de la page précédente, ou `null` sur la première page.

**Requête** `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
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/list/

## Supprimer un segment — DELETE /segments/{id}

> Supprimez un segment. Les campagnes en brouillon qui lui sont envoyées le perdent ; les brouillons qui l’excluent ne peuvent pas être envoyés tant que vous n’avez pas remplacé l’exclusion. Les campagnes programmées ou en cours d’envoi et les automatisations qui utilisent le segment bloquent la suppression. Alpha : réservé à l’équipe Emailit.

# Supprimer un segment

Supprime un segment. Nécessite une clé API avec la portée `full`.

- Un segment qu’une campagne utilise alors qu’elle est programmée, en file d’attente, en cours d’envoi ou en test ne peut pas être supprimé. Modifiez d’abord les destinataires de la campagne.
- Un segment ne peut pas être supprimé tant qu’une automatisation non supprimée, quel que soit son statut, l’utilise : dans un déclencheur **Added to segment** ou **Removed from segment**, dans un objectif, une étape **Wait until** ou une condition de sortie sur ces événements, ou dans une règle **Segment** d’une condition. Modifiez d’abord ces automatisations.
- Les campagnes en brouillon qui sont envoyées au segment le perdent de leurs destinataires, et `removed_from_campaigns` indique combien. Les brouillons qui excluent le segment conservent l’exclusion : ils ne peuvent donc pas être envoyés tant que vous ne l’avez pas remplacée, car la retirer enverrait la campagne aux personnes que vous vouliez écarter. Les campagnes envoyées, annulées et archivées conservent la référence comme historique.
- Pour un segment avec suivi, ses membres enregistrés et son historique d’évolution sont également supprimés.

`DELETE /segments/{id}`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du segment (`seg_…`).

## Réponse

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

- `id` (string): ID du segment supprimé.

- `name` (string): Son nom.

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

- `removed_from_campaigns` (integer): Nombre de campagnes en brouillon qui ne sont plus envoyées au segment.

| Statut | Cas |
| --- | --- |
| `404` | Le segment n’existe pas. |
| `409` | Une campagne programmée, en file d’attente, en cours d’envoi ou en test utilise le segment, ou une automatisation démarre à partir de lui. Le message les nomme. |

**Requête** `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 Campagnes**

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

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

---
Source: https://emailit.com/fr/docs/api-reference/segments/delete/

## Lister les contacts d’un segment — GET /segments/{id}/contacts

> Listez les contacts qui correspondent à un segment en ce moment, avec une recherche, les filtres de la liste des contacts et, pour les segments avec suivi, la date d’entrée de chaque contact. Alpha : réservé à l’équipe Emailit.

# Lister les contacts d’un segment

Renvoie les contacts qui correspondent au segment au moment de l’appel, du plus récent au plus ancien. Nécessite une clé API avec la portée `full`.

`GET /segments/{id}/contacts`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du segment (`seg_…`).

## Paramètres de requête

- `page` (integer): Numéro de page, à partir de 1.

- `limit` (integer): Contacts par page, de 1 à 100.

- `search` (string): Correspondance insensible à la casse sur une partie de l’adresse e-mail, du prénom ou du nom.

- `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

### Clés de filtre

Les contacts d’un segment acceptent les mêmes clés de filtre et de tri que [Lister les contacts](/fr/docs/api-reference/contacts/list/), appliquées en plus du segment, par exemple `email.ends_with=acme.com`.

Clés de filtre et de tri : voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

## Réponse

- `data` (object[]): Contacts de cette page, chacun avec `object`, `id`, `email`, `first_name`, `last_name`, `custom_fields`, `unsubscribed`, `audiences` (`id`, `name`, `subscribed`), `created_at` et `updated_at`. Les contacts d’un [segment avec suivi](/fr/docs/segments/tracked/) ont aussi `joined_at`.

- `data[].joined_at` (string | null): Segments avec suivi uniquement : date de début de la présence actuelle du contact dans le segment. `null` tant que le suivi n’a pas enregistré le contact, par exemple juste après qu’il a commencé à correspondre, pendant que le segment est `syncing`, ou pendant que le suivi est `paused`.

- `total_records` (integer): Nombre de contacts qui correspondent au segment, à la recherche et aux filtres.

- `subscribed_count` (integer): Combien d’entre eux les campagnes peuvent atteindre : ceux qui ne sont pas désinscrits de toutes les listes et qui sont abonnés à au moins une liste.

- `next_page_url` (string | null): Chemin de la page suivante, ou `null` sur la dernière page. Il contient `page`, `limit` et `search` ; ajoutez de nouveau vos filtres lorsque vous le suivez.

- `previous_page_url` (string | null): Chemin de la page précédente, ou `null` sur la première page.

Renvoie `404` si le segment n’existe pas.

**Requête** `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"
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/contacts/

## Récupérer l’évolution d’un segment — GET /segments/{id}/growth

> Nombre quotidien de membres, entrées et sorties d’un segment avec suivi, une ligne par jour UTC sur 365 jours au maximum. Alpha : réservé à l’équipe Emailit.

# Récupérer l’évolution d’un segment

Renvoie l’historique d’un [segment avec suivi](/fr/docs/segments/tracked/) : une ligne par jour UTC, du plus ancien au plus récent, jusqu’à aujourd’hui. Ce sont les données du graphique **Growth** de la page du segment. Nécessite une clé API avec la portée `full`.

L’historique commence au démarrage du suivi. Les contacts enregistrés par le premier décompte après la création du segment, ou après la reprise du suivi, comptent comme membres mais pas comme entrées.

`GET /segments/{id}/growth`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres de chemin

- `id` (string, obligatoire): L’ID du segment (`seg_…`).

## Paramètres de requête

- `days` (integer): Nombre de jours à renvoyer, de 1 à 365, jusqu’à aujourd’hui.

## Réponse

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

- `segment_id` (string): L’ID du segment.

- `data` (object[]): Une ligne par jour.

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

- `data[].members_count` (integer | null): Membres à la fin de la journée, ou le dernier décompte pour aujourd’hui. Les jours sans nouveau décompte reprennent la valeur précédente, par exemple pendant que le suivi est en pause. `null` avant le démarrage du suivi.

- `data[].joined_count` (integer): Contacts entrés dans le segment ce jour-là.

- `data[].left_count` (integer): Contacts sortis du segment ce jour-là.

| Statut | Cas |
| --- | --- |
| `404` | Le segment n’existe pas. |
| `422` | Le segment n’est pas un segment avec suivi. |

**Requête** `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"
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/growth/

## Prévisualiser un segment — POST /segments/preview

> Comptez et échantillonnez les contacts que contiendrait une définition de segment, sans l’enregistrer. Alpha : réservé à l’équipe Emailit.

# Prévisualiser un segment

Vérifie une définition de segment sans l’enregistrer : renvoie le nombre de contacts qui correspondent et un échantillon de ces contacts. La définition est validée comme pour [Créer un segment](/fr/docs/api-reference/segments/create/), et une prévisualisation ne compte pas dans la limite de segments du forfait. Nécessite une clé API avec la portée `full`.

`POST /segments/preview`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Paramètres du corps

- `audience_ids` (string[]): ID des listes dans lesquelles le segment puiserait. Vide ou omis : tous les contacts.

- `conditions` (object): Les règles. Consultez [Créer un segment](/fr/docs/api-reference/segments/create/#conditions).

- `limit` (integer): Nombre de contacts de l’échantillon, de 1 à 25.

## Réponse

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

- `audience_ids` (string[]): Les listes sources, sans doublons.

- `conditions` (object): Les règles telles qu’elles seraient enregistrées : un `{ match, rules }` à plat devient un seul groupe et les groupes vides sont retirés.

- `contacts_count` (integer): Contacts qui correspondent.

- `subscribed_count` (integer): Combien d’entre eux les campagnes peuvent atteindre.

- `contacts` (object[]): Les contacts correspondants les plus récents, sous la même forme que dans [Lister les contacts d’un segment](/fr/docs/api-reference/segments/contacts/).

Renvoie `422` avec `errors` indexé par chemin de champ si la définition est invalide.

**Requête** `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."
    ]
  }
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/preview/

## Lister les champs de segment — GET /segments/fields

> Listez les champs de contact, les champs personnalisés et les listes que les règles de segment peuvent utiliser, avec les opérateurs et les valeurs acceptés par chacun. Alpha : réservé à l’équipe Emailit.

# Lister les champs de segment

Renvoie les champs que les règles de segment peuvent utiliser dans cet espace de travail : les champs de contact, chaque champ personnalisé (typé selon son type de champ personnalisé), l’appartenance aux listes, les données d’achat et l’engagement envers les campagnes. Nécessite une clé API avec la portée `full`.

`GET /segments/fields`

> **Les segments sont en alpha:** Les segments sont réservés à l’équipe Emailit pendant que nous les testons. Les autres requêtes, y compris toutes celles effectuées avec une clé API, renvoient `403` avec `error: "segments_alpha"`. Consultez [Qui peut utiliser les segments](/fr/docs/segments/#who-can-use-segments).

## Réponse

- `data` (object[]): Un élément par champ.

- `data[].key` (string): La valeur à utiliser comme `field` d’une règle, par exemple `email_domain` ou `custom_fields.plan`.

- `data[].label` (string): Nom affiché. Pour les champs personnalisés, le nom du champ personnalisé.

- `data[].type` (string): `string`, `number`, `date`, `datetime`, `boolean`, `enum`, `multi`, `audience`, `metric`, `moment`, `purchase`, `view`, `cart`, `coupon` ou `campaign_activity`. Consultez [Créer un segment](/fr/docs/api-reference/segments/create/#fields). Les champs d’activité comme `purchased` acceptent un objet comme valeur : consultez [Règles d’activité](/fr/docs/api-reference/segments/create/#activity-rules).

- `data[].group` (string): `contact`, `custom_fields`, `audiences`, `commerce` (données d’achat) ou `engagement` (activité liée aux campagnes).

- `data[].operators` (string[]): Opérateurs acceptés par le champ.

- `data[].values` (object[]): Valeurs autorisées sous la forme `value` et `label` : les options des champs personnalisés à liste déroulante et à choix multiple, `subscribed` et `unsubscribed` pour `status`, et les listes de l’espace de travail pour `audience`. Absent pour les autres champs.

**Requête** `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"]
    }
  ]
}
```

---
Source: https://emailit.com/fr/docs/api-reference/segments/fields/