Segments
Enregistrez des filtres sur vos contacts, listez ceux qui correspondent et suivez l’évolution des segments avec suivi.
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.
Chaque forfait inclut un nombre de segments par espace de travail, avec ou sans suivi. Consultez Limites.
/segmentsParamètres du corps
namestringobligatoiredescriptionstring | nullaudience_idsstring[]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.conditionsobjecttrackedbooleanpar défaut : falseConditions
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 :
{
"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" }] }
]
}matchvautall(par défaut) ouany, 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 du contact. Les valeurs sont comparées en minuscules. |
score |
score | Le score de lead 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 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 a vu le contact sur votre site. |
purchased |
purchase | Les commandes, voir Règles d’activité. |
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 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_containsetnot_incorrespondent aussi aux contacts sans valeur.in,not_inetcontains_allacceptent une liste de 100 valeurs au maximum. Les valeurs texte peuvent compter jusqu’à 500 caractères.betweenaccepte[from, to], bornes incluses : deux nombres ou deux datesYYYY-MM-DD.on,beforeetafteracceptent une dateYYYY-MM-DD.beforeetaftern’incluent pas ce jour.in_last_days,more_than_days_agoetin_next_daysacceptent 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_atetupdated_atutilisent des heures exactes :in_last_daysavec7désigne donc les 7 × 24 dernières heures.is_set,is_not_set,is_trueetis_falsen’acceptent pas de valeur.is_truecorrespond àtrue,1,yeseton;is_falsecorrespond àfalse,0,noetoff.- 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. 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.
{
"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, 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. |
{
"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"
}{
"error": "plan_required",
"message": "Tracked segments are included with Pro and Business.",
"required_plan": "pro"
}{
"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."
]
}
}{
"error": "Pay as you go includes 3 segments.",
"message": "Pay as you go includes 3 segments.",
"usage": {
"used": 3,
"limit": 3
}
}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.
/segments/{id}Paramètres de chemin
idstringobligatoireseg_…).Réponse
Renvoie l’objet segment.
objectstringsegment.idstringseg_.namestringdescriptionstring | nullaudience_idsstring[]conditionsobject{ "match", "groups": [{ "match", "rules": [...] }] }. Consultez Créer un segment.trackedbooleantrackingobject | nullnull pour les segments sans suivi. Pour les segments avec suivi :
status:activelorsque les membres sont tenus à jour,syncingpendant qu’Emailit enregistre les membres actuels après la création du segment ou la reprise du suivi, oupausedlorsque 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, ounullavant la première comparaison.
contacts_countintegersubscribed_countintegercontacts_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_atstringRenvoie 404 si le segment n’existe pas.
{
"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"
}{
"error": "Segment not found"
}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, 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.
/segments/{id}Paramètres de chemin
idstringobligatoireseg_…).Paramètres du corps
namestringdescriptionstring | nullnull ou une chaîne vide l’efface.audience_idsstring[][] signifie tous les contacts de l’espace de travail.conditionsobjecttrackedbooleanRéponse
Renvoie l’objet segment 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. |
{
"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"
}{
"error": "Segment not found"
}{
"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."
]
}
}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.
/segmentsParamètres de requête
pageintegerpar défaut : 1limitintegerpar défaut : 10searchstringwith_countsbooleanpar défaut : falsecontacts_count et subscribed_count à chaque segment. Le décompte évalue chaque segment de la page : il est donc désactivé par défaut.matchstringall (par défaut) exige que tous les filtres correspondent. Avec or, il suffit qu’un filtre corresponde. Consultez Filtrage et tri.
orderstringClé de tri de cette liste. Consultez les clés de tri ci-dessous.
directionstringasc ou desc.
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.
| 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
dataobject[]contacts_count et subscribed_count ne sont inclus qu’avec with_counts.total_recordsintegerusageobjectused (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.next_page_urlstring | nullnull 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_urlstring | nullnull sur la première page.{
"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
}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_campaignsindique 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.
/segments/{id}Paramètres de chemin
idstringobligatoireseg_…).Réponse
objectstringsegment.idstringnamestringdeletedbooleantrue.removed_from_campaignsinteger| 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. |
{
"object": "segment",
"id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
"name": "Pro customers renewing soon",
"deleted": true,
"removed_from_campaigns": 1
}{
"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."
}{
"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."
}{
"error": "Segment not found"
}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.
/segments/{id}/contactsParamètres de chemin
idstringobligatoireseg_…).Paramètres de requête
pageintegerpar défaut : 1limitintegerpar défaut : 25searchstringmatchstringall (par défaut) exige que tous les filtres correspondent. Avec or, il suffit qu’un filtre corresponde. Consultez Filtrage et tri.
orderstringClé de tri de cette liste. Consultez les clés de tri ci-dessous.
directionstringasc ou desc.
Clés de filtre
Les contacts d’un segment acceptent les mêmes clés de filtre et de tri que Lister les contacts, appliquées en plus du segment, par exemple email.ends_with=acme.com.
Les filtres de liste sont des paramètres de requête key.condition=value sur un seul niveau. Consultez Filtrage et tri pour match, order, direction et la liste des conditions par type.
Clés de filtre
| Clé | Type | Conditions | Remarques |
|---|---|---|---|
email | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
first_name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
last_name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Prénom suivi du nom, sans espaces superflus. |
audiences | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Correspond au premier nom de liste du contact, par ordre alphabétique. |
created_at | date | exact, before, after, empty, not_empty | |
updated_at | date | exact, before, after, empty, not_empty | |
unsubscribed | boolean | exact, not_exact | |
audience_id | string | exact, not_exact | Uniquement exact et not_exact. La valeur est un ID de liste (aud_...). |
custom_fields.* | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Remplacez * par la clé d’un champ personnalisé, par exemple custom_fields.company.contains=Acme. |
Clés de tri
Passez dans order l’une de ces clés et dans direction la valeur asc ou desc : email, first_name, last_name, name, audiences, created_at, updated_at, unsubscribed
Réponse
dataobject[]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 ont aussi joined_at.data[].joined_atstring | nullnull 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_recordsintegersubscribed_countintegernext_page_urlstring | nullnull sur la dernière page. Il contient page, limit et search ; ajoutez de nouveau vos filtres lorsque vous le suivez.previous_page_urlstring | nullnull sur la première page.Renvoie 404 si le segment n’existe pas.
{
"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
}{
"error": "Segment not found"
}Récupérer l’évolution d’un segment
Renvoie l’historique d’un segment avec suivi : 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.
/segments/{id}/growthParamètres de chemin
idstringobligatoireseg_…).Paramètres de requête
daysintegerpar défaut : 30Réponse
objectstringsegment_growth.segment_idstringdataobject[]data[].datestringYYYY-MM-DD.data[].members_countinteger | nullnull avant le démarrage du suivi.data[].joined_countintegerdata[].left_countinteger| Statut | Cas |
|---|---|
404 |
Le segment n’existe pas. |
422 |
Le segment n’est pas un segment avec suivi. |
{
"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 }
]
}{
"error": "Growth is recorded for tracked segments only.",
"message": "Growth is recorded for tracked segments only."
}{
"error": "Segment not found"
}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, et une prévisualisation ne compte pas dans la limite de segments du forfait. Nécessite une clé API avec la portée full.
/segments/previewParamètres du corps
audience_idsstring[]conditionsobjectlimitintegerpar défaut : 10Réponse
objectstringsegment_preview.audience_idsstring[]conditionsobject{ match, rules } à plat devient un seul groupe et les groupes vides sont retirés.contacts_countintegersubscribed_countintegercontactsobject[]Renvoie 422 avec errors indexé par chemin de champ si la définition est invalide.
{
"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"
}
]
}{
"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."
]
}
}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.
/segments/fieldsRéponse
dataobject[]data[].keystringfield d’une règle, par exemple email_domain ou custom_fields.plan.data[].labelstringdata[].typestringstring, number, date, datetime, boolean, enum, multi, audience, metric, moment, purchase, view, cart, coupon ou campaign_activity. Consultez Créer un segment. Les champs d’activité comme purchased acceptent un objet comme valeur : consultez Règles d’activité.data[].groupstringcontact, custom_fields, audiences, commerce (données d’achat) ou engagement (activité liée aux campagnes).data[].operatorsstring[]data[].valuesobject[]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.{
"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"]
}
]
}