Segmenti
Salva filtri sui contatti, elenca chi corrisponde e segui nel tempo i segmenti tracciati.
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.
Ogni piano include un certo numero di segmenti per workspace, tracciati o no. Vedi Limiti e quote.
/segmentsParametri del corpo
namestringobbligatoriodescriptionstring | nullaudience_idsstring[]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.conditionsobjecttrackedbooleanpredefinito: falseCondizioni
conditions contiene gruppi di regole. Il match di primo livello combina i gruppi, e il match di ogni gruppo combina le sue regole:
{
"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" }] }
]
}matchvaleall(predefinito) oany, 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 del contatto. I valori vengono confrontati in minuscolo. |
score |
score | Il 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 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 ha visto il contatto sul tuo sito. |
purchased |
purchase | Ordini, vedi Regole di attività. |
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 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_containsenot_incorrispondono anche ai contatti che non hanno un valore.in,not_inecontains_allaccettano un elenco di fino a 100 valori. I valori di testo possono arrivare a 500 caratteri.betweenaccetta[from, to], estremi inclusi: due numeri o due dateYYYY-MM-DD.on,beforeeafteraccettano una dataYYYY-MM-DD.beforeeafternon includono quel giorno.in_last_days,more_than_days_agoein_next_daysaccettano 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_ateupdated_atusano orari esatti, quindiin_last_dayscon7significa le ultime 7 × 24 ore.is_set,is_not_set,is_trueeis_falsenon accettano valori.is_truecorrisponde atrue,1,yeseon;is_falsecorrisponde afalse,0,noeoff.- 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. 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.
{
"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, 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. |
{
"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
}
}Recupera un segmento
Recupera un segmento e ne conta i contatti nel momento in cui lo chiami. Richiede una chiave API full.
/segments/{id}Parametri di percorso
idstringobbligatorioseg_…).Restituisce
Restituisce l’oggetto segmento.
objectstringsegment.idstringseg_.namestringdescriptionstring | nullaudience_idsstring[]conditionsobject{ "match", "groups": [{ "match", "rules": [...] }] }. Vedi Crea un segmento.trackedbooleantrackingobject | nullnull per i segmenti non tracciati. Per i segmenti tracciati:
status:activequando i membri sono aggiornati,syncingmentre Emailit registra i membri attuali dopo la creazione del segmento o la ripresa del tracciamento, oppurepausedquando 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, oppurenullprima del primo confronto.
contacts_countintegersubscribed_countintegercontacts_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_atstringRestituisce 404 se il segmento non esiste.
{
"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"
}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, 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.
/segments/{id}Parametri di percorso
idstringobbligatorioseg_…).Parametri del corpo
namestringdescriptionstring | nullnull o una stringa vuota la cancellano.audience_idsstring[][] significa tutti i contatti del workspace.conditionsobjecttrackedbooleanRestituisce
Restituisce l’oggetto segmento 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. |
{
"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."
]
}
}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.
/segmentsParametri di query
pageintegerpredefinito: 1limitintegerpredefinito: 10searchstringwith_countsbooleanpredefinito: falsecontacts_count e subscribed_count a ogni segmento. Il conteggio valuta ogni segmento della pagina, quindi è disattivato per impostazione predefinita.matchstringall (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.
orderstringChiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.
directionstringasc o desc.
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.
| Chiave | Tipo | Note |
|---|---|---|
name |
string | |
created_at |
date | |
updated_at |
date |
Chiavi di ordinamento per order: name, created_at, updated_at.
Restituisce
dataobject[]contacts_count e subscribed_count sono presenti solo con with_counts.total_recordsintegerusageobjectused (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.next_page_urlstring | nullnull sull’ultima pagina. Contiene solo page e limit; quando lo segui, aggiungi di nuovo la ricerca e i filtri.previous_page_urlstring | nullnull sulla prima pagina.{
"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
}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_campaignsindica 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.
/segments/{id}Parametri di percorso
idstringobbligatorioseg_…).Restituisce
objectstringsegment.idstringnamestringdeletedbooleantrue.removed_from_campaignsinteger| 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. |
{
"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"
}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.
/segments/{id}/contactsParametri di percorso
idstringobbligatorioseg_…).Parametri di query
pageintegerpredefinito: 1limitintegerpredefinito: 25searchstringmatchstringall (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.
orderstringChiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.
directionstringasc o desc.
Chiavi di filtro
I contatti di un segmento accettano le stesse chiavi di filtro e di ordinamento di Elenca i contatti, applicate in aggiunta al segmento, ad esempio email.ends_with=acme.com.
I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.
Chiavi di filtro
| Chiave | Tipo | Condizioni | Note |
|---|---|---|---|
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 | Nome più cognome, senza spazi iniziali e finali. |
audiences | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Corrisponde al nome della lista del contatto che viene prima in ordine alfabetico. |
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 | Solo exact e not_exact. Il valore è un ID di lista (aud_...). |
custom_fields.* | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | Sostituisci * con la chiave di un campo personalizzato, ad esempio custom_fields.company.contains=Acme. |
Chiavi di ordinamento
Passa in order una di queste chiavi e in direction il valore asc o desc: email, first_name, last_name, name, audiences, created_at, updated_at, unsubscribed
Restituisce
dataobject[]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 hanno anche joined_at.data[].joined_atstring | nullnull 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_recordsintegersubscribed_countintegernext_page_urlstring | nullnull sull’ultima pagina. Contiene page, limit e search; quando lo segui, aggiungi di nuovo i filtri.previous_page_urlstring | nullnull sulla prima pagina.Restituisce 404 se il segmento non esiste.
{
"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"
}Recupera la crescita di un segmento
Restituisce la cronologia di un segmento tracciato: 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.
/segments/{id}/growthParametri di percorso
idstringobbligatorioseg_…).Parametri di query
daysintegerpredefinito: 30Restituisce
objectstringsegment_growth.segment_idstringdataobject[]data[].datestringYYYY-MM-DD.data[].members_countinteger | nullnull prima dell’inizio del tracciamento.data[].joined_countintegerdata[].left_countinteger| Stato | Quando |
|---|---|
404 |
Il segmento non esiste. |
422 |
Il segmento non è tracciato. |
{
"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"
}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, e un’anteprima non rientra nel limite di segmenti del piano. Richiede una chiave API full.
/segments/previewParametri del corpo
audience_idsstring[]conditionsobjectlimitintegerpredefinito: 10Restituisce
objectstringsegment_preview.audience_idsstring[]conditionsobject{ match, rules } piatto diventa un unico gruppo e i gruppi vuoti vengono scartati.contacts_countintegersubscribed_countintegercontactsobject[]Restituisce 422 con errors, che ha come chiavi i percorsi dei campi, se la definizione non è valida.
{
"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."
]
}
}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.
/segments/fieldsRestituisce
dataobject[]data[].keystringfield di una regola, ad esempio email_domain o custom_fields.plan.data[].labelstringdata[].typestringstring, number, date, datetime, boolean, enum, multi, audience, metric, moment, purchase, view, cart, coupon o campaign_activity. Vedi Crea un segmento. I campi di attività come purchased accettano un oggetto come valore, vedi Regole di attività.data[].groupstringcontact, custom_fields, audiences, commerce (dati di acquisto) o engagement (attività sulle campagne).data[].operatorsstring[]data[].valuesobject[]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.{
"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"]
}
]
}