> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lekalao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segments

> Décrire un public en JSON : groupes, règles et opérateurs.

Un segment est un filtre enregistré sur une liste. Il se construit dans l'interface ([Segments](/fr/contacts/segments)) ou ici, en JSON.

## Créer un segment

« Les clients VIP, ou ceux qui ont ouvert la campagne de rentrée, et actifs depuis 60 jours » :

```bash theme={null}
curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/segments \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "VIP actifs",
    "conditions": {
      "operator": "and",
      "rules": [
        {
          "operator": "or",
          "rules": [
            { "type": "tags", "operator": "has_any", "value": ["vip"] },
            { "type": "campaign", "operator": "opened", "value": "0c9e3f5a-6b1d-4d2e-8a7f-1e2d3c4b5a69" }
          ]
        },
        { "type": "engagement", "operator": "active_within_days", "value": 60 }
      ]
    }
  }'
```

La réponse `201` contient le segment et `subscribers_count`, le nombre de personnes qu'il désigne à cet instant. Les membres sont recalculés à chaque envoi : un segment n'est jamais figé.

## La forme

* Un **groupe** : `{ "operator": "and" | "or", "rules": [ … ] }`.
* Une **règle** : `{ "type", "operator", "value", "key" }`.
* Un groupe peut contenir des règles et des groupes, sur **deux niveaux** au plus.
* **50 règles** au plus en tout.

Seuls les abonnés au statut `subscribed` de la liste sont comptés.

## Les règles

### Champs de la fiche

`type` : `email`, `first_name`, `last_name`.

| `operator`                                             | `value`                       |
| ------------------------------------------------------ | ----------------------------- |
| `equals`, `not_equals`                                 | Texte. Insensible à la casse. |
| `contains`, `not_contains`, `starts_with`, `ends_with` | Texte.                        |
| `is_empty`, `is_not_empty`                             | Aucune.                       |

```json theme={null}
{ "type": "email", "operator": "ends_with", "value": "@maboulangerie.fr" }
```

### Tags

`type` : `tags`.

| `operator` | `value`                  |
| ---------- | ------------------------ |
| `has_any`  | Au moins un de ces tags. |
| `has_all`  | Tous ces tags.           |
| `has_none` | Aucun de ces tags.       |

`value` est un tableau de **noms** ou d'**ids** de tags de la liste. Un tag inconnu est refusé.

### Langue

`type` : `language`. `operator` : `equals` ou `not_equals`. `value` : un code comme `fr` ou `pt-BR`.

### Attributs

`type` : `attribute`, avec `key` le nom de l'attribut (lettres, chiffres, `_`, `.`, `-`).

| `operator`                         | `value`            |
| ---------------------------------- | ------------------ |
| `equals`, `not_equals`, `contains` | Texte.             |
| `greater_than`, `less_than`        | Nombre.            |
| `date_before`, `date_after`        | Date `AAAA-MM-JJ`. |
| `is_set`, `is_not_set`             | Aucune.            |

```json theme={null}
{
    "type": "attribute",
    "key": "points",
    "operator": "greater_than",
    "value": 100
}
```

### Date d'inscription

`type` : `subscribed_at`.

| `operator`                               | `value`            |
| ---------------------------------------- | ------------------ |
| `before`, `after`                        | Date `AAAA-MM-JJ`. |
| `within_last_days`, `more_than_days_ago` | Nombre de jours.   |

### Activité

| `type`            | `operator`                                                                    | `value`                            |
| ----------------- | ----------------------------------------------------------------------------- | ---------------------------------- |
| `campaign`        | `received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked`  | Uuid de la campagne.               |
| `automation_mail` | les mêmes                                                                     | Uuid de l'e-mail d'automatisation. |
| `link`            | `clicked`, `not_clicked`                                                      | Uuid du lien.                      |
| `engagement`      | `active_within_days` (a ouvert ou cliqué), `inactive_within_days` (rien fait) | Nombre de jours.                   |

### Autres listes

`type` : `list`. `operator` : `subscribed_to` ou `not_subscribed_to`. `value` : l'`id` d'une **autre** liste de l'équipe.

```json theme={null}
{ "type": "list", "operator": "not_subscribed_to", "value": "3e7d…" }
```

## Lire, modifier, supprimer

| Appel                      | Effet                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `GET /lists/{id}/segments` | Les segments de la liste, sans compte.                                              |
| `GET /segments/{id}`       | Un segment, avec `subscribers_count`.                                               |
| `PUT /segments/{id}`       | Change `name` et/ou `conditions`. Les conditions envoyées remplacent les anciennes. |
| `DELETE /segments/{id}`    | Supprime le segment. Les campagnes déjà envoyées gardent leurs statistiques.        |

Dans les réponses, les tags sont rendus par leur nom et les autres références par leur `id`, comme vous les avez envoyés.

## Erreurs

Une règle invalide renvoie `422` avec le chemin exact :

```json theme={null}
{
    "message": "Il n'y a pas de tag « vipp » sur cette liste.",
    "errors": {
        "conditions.rules.0.rules.0.value": [
            "Il n'y a pas de tag « vipp » sur cette liste."
        ]
    }
}
```