Vai al contenuto
Docs

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

URL di basehttps://api.emailit.com/v2AutenticazioneErroriLimiti di frequenza

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.

POST/segments

Parametri del corpo

namestringobbligatorio
Nome del segmento, fino a 191 caratteri.
descriptionstring | null
Nota per il team, fino a 1000 caratteri.
audience_idsstring[]
L’origine: ID di liste (aud_…) di questo workspace, fino a 100. Il segmento contiene solo i contatti iscritti ad almeno una di esse. Vuoto o omesso significa tutti i contatti del workspace.
conditionsobject
Le regole che i contatti devono soddisfare, descritte in Condizioni. Omettilo per includere tutti i contatti dell’origine.
trackedbooleanpredefinito: false
Memorizza i membri del segmento, così i contatti che entrano ed escono diventano eventi per le automazioni e i webhook. Incluso nei piani Pro, Business e Custom. Lo scegli qui e non puoi cambiarlo in seguito. Vedi Segmenti tracciati.

Condizioni

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

JSON
{
  "match": "all",
  "groups": [
    { "match": "any", "rules": [{ "field": "email_domain", "operator": "in", "value": ["acme.com", "globex.io"] }] },
    { "match": "all", "rules": [{ "field": "status", "operator": "equals", "value": "subscribed" }] }
  ]
}
  • match vale all (predefinito) o any, al primo livello e in ogni gruppo.
  • Ometti conditions, o non inviare gruppi, per includere tutti i contatti dell’origine. I gruppi vuoti vengono scartati.
  • Viene accettata anche la forma piatta { "match": "any", "rules": [...] }, salvata come un unico gruppo.
  • Un segmento può avere fino a 10 gruppi e 50 regole in tutto.

Campi

Campo Tipo Note
email string
email_domain string La parte dell’indirizzo dopo @.
first_name, last_name string
status enum subscribed (non disiscritto a livello globale e iscritto ad almeno una lista, quindi raggiungibile dalle campagne) o unsubscribed. Operatori: equals, not_equals.
created_at, updated_at datetime Quando il contatto è stato creato o modificato l’ultima volta, con il confronto in UTC.
audience audience Iscrizione attiva alle liste. in corrisponde ai contatti iscritti ad almeno una delle liste indicate, not_in ai contatti non iscritti a nessuna di esse.
tags tags I tag 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_contains e not_in corrispondono anche ai contatti che non hanno un valore.
  • in, not_in e contains_all accettano un elenco di fino a 100 valori. I valori di testo possono arrivare a 500 caratteri.
  • between accetta [from, to], estremi inclusi: due numeri o due date YYYY-MM-DD.
  • on, before e after accettano una data YYYY-MM-DD. before e after non includono quel giorno.
  • in_last_days, more_than_days_ago e in_next_days accettano un numero intero di giorni da 1 a 3650, contati dal momento in cui il segmento viene valutato. I campi personalizzati di tipo data confrontano giorni di calendario in UTC; created_at e updated_at usano orari esatti, quindi in_last_days con 7 significa le ultime 7 × 24 ore.
  • is_set, is_not_set, is_true e is_false non accettano valori. is_true corrisponde a true, 1, yes e on; is_false corrisponde a false, 0, no e off.
  • Una regola salvata che non è più applicabile, ad esempio perché il suo campo personalizzato ha cambiato tipo, non corrisponde a nessun contatto. Le regole su un campo personalizzato eliminato continuano a funzionare con i valori che i contatti hanno ancora, ma le nuove regole devono usare un campo esistente.

Regole di attività

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

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

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

JSON
{
  "match": "all",
  "groups": [
    { "match": "all", "rules": [
      { "field": "purchased", "operator": "has", "value": { "categories": ["Shoes"], "days": 180 } },
      { "field": "churn_risk", "operator": "in", "value": ["medium", "high"] },
      { "field": "campaign_activity", "operator": "clicked", "value": { "days": 90 } }
    ] }
  ]
}

received_not_opened e received_not_clicked corrispondono ai contatti che hanno ricevuto almeno un’email di campagna corrispondente e non ne hanno aperta o cliccata nessuna. Le aperture sono approssimative: Apple Mail carica le immagini di ogni email che riceve.

Restituisce

Restituisce 201 Created con l’oggetto segmento, 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.
POST/segments
Terminal
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
  }'
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"
}

Recupera un segmento

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

GET/segments/{id}

Parametri di percorso

idstringobbligatorio
L’ID del segmento (seg_…).

Restituisce

Restituisce l’oggetto segmento.

objectstring
Sempre segment.
idstring
ID del segmento, con prefisso seg_.
namestring
Nome del segmento.
descriptionstring | null
Nota per il team.
audience_idsstring[]
Le liste di origine. Vuoto significa tutti i contatti del workspace.
conditionsobject
Le regole, nella forma { "match", "groups": [{ "match", "rules": [...] }] }. Vedi Crea un segmento.
trackedboolean
Indica se il segmento memorizza i suoi membri e segnala ingressi e uscite. Vedi Segmenti tracciati.
trackingobject | null

null per i segmenti non tracciati. Per i segmenti tracciati:

  • status: active quando i membri sono aggiornati, syncing mentre Emailit registra i membri attuali dopo la creazione del segmento o la ripresa del tracciamento, oppure paused quando il piano del workspace non include più i segmenti tracciati.
  • synced_at: quando l’intero segmento è stato confrontato l’ultima volta con le sue regole, oppure null prima del primo confronto.
contacts_countinteger
Contatti che corrispondono in questo momento.
subscribed_countinteger
La parte di contacts_count a cui le campagne possono inviare: i contatti non disiscritti a livello globale e iscritti ad almeno una lista. Gli indirizzi soppressi vengono comunque contati.
created_at, updated_atstring
Timestamp in UTC.

Restituisce 404 se il segmento non esiste.

GET/segments/{id}
Terminal
curl https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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"
}

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.

POST/segments/{id}

Parametri di percorso

idstringobbligatorio
L’ID del segmento (seg_…).

Parametri del corpo

namestring
Nuovo nome, fino a 191 caratteri. Non può essere vuoto.
descriptionstring | null
Nota per il team, fino a 1000 caratteri. null o una stringa vuota la cancellano.
audience_idsstring[]
ID delle liste di origine. [] significa tutti i contatti del workspace.
conditionsobject
Le regole. Vedi Crea un segmento.
trackedboolean
Accettato solo con il valore attuale del segmento. Il tracciamento si sceglie quando si crea un segmento; per cambiarlo, crea un nuovo segmento.

Restituisce

Restituisce l’oggetto segmento 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.
POST/segments/{id}
Terminal
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" }'
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"
}

Elenca i segmenti

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

GET/segments

Parametri di query

pageintegerpredefinito: 1
Numero della pagina, a partire da 1.
limitintegerpredefinito: 10
Segmenti per pagina, da 1 a 100.
with_countsbooleanpredefinito: false
Aggiunge contacts_count e subscribed_count a ogni segmento. Il conteggio valuta ogni segmento della pagina, quindi è disattivato per impostazione predefinita.
matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc 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[]
Gli oggetti segmento di questa pagina. contacts_count e subscribed_count sono presenti solo con with_counts.
total_recordsinteger
Numero di segmenti che corrispondono alla query.
usageobject
I segmenti del workspace rispetto al piano: used (tutti i segmenti, tracciati o no), limit (i segmenti inclusi nel piano) e tracking_allowed (indica se il piano include i segmenti tracciati). Vedi Limiti e quote.
next_page_urlstring | null
Percorso della pagina successiva, oppure null sull’ultima pagina. Contiene solo page e limit; quando lo segui, aggiungi di nuovo la ricerca e i filtri.
previous_page_urlstring | null
Percorso della pagina precedente, oppure null sulla prima pagina.
GET/segments
Terminal
curl -G https://api.emailit.com/v2/segments \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d with_counts=true
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
}

Elimina un segmento

Elimina un segmento. Richiede una chiave API full.

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

Parametri di percorso

idstringobbligatorio
L’ID del segmento (seg_…).

Restituisce

objectstring
Sempre segment.
idstring
ID del segmento eliminato.
namestring
Il suo nome.
deletedboolean
Sempre true.
removed_from_campaignsinteger
Numero di bozze di campagna che non inviano più al segmento.
Stato Quando
404 Il segmento non esiste.
409 Una campagna programmata, in coda, in invio o in test usa il segmento, oppure un’automazione parte dal segmento. Il messaggio le indica per nome.
DELETE/segments/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "segment",
  "id": "seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p",
  "name": "Pro customers renewing soon",
  "deleted": true,
  "removed_from_campaigns": 1
}

Elenca i contatti di un segmento

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

GET/segments/{id}/contacts

Parametri di percorso

idstringobbligatorio
L’ID del segmento (seg_…).

Parametri di query

pageintegerpredefinito: 1
Numero della pagina, a partire da 1.
limitintegerpredefinito: 25
Contatti per pagina, da 1 a 100.
matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc 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

ChiaveTipoCondizioniNote
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
first_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
last_namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyNome più cognome, senza spazi iniziali e finali.
audiencesstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptyCorrisponde al nome della lista del contatto che viene prima in ordine alfabetico.
created_atdateexact, before, after, empty, not_empty
updated_atdateexact, before, after, empty, not_empty
unsubscribedbooleanexact, not_exact
audience_idstringexact, not_exactSolo exact e not_exact. Il valore è un ID di lista (aud_...).
custom_fields.*stringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_emptySostituisci * 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[]
I contatti di questa pagina, ciascuno con object, id, email, first_name, last_name, custom_fields, unsubscribed, audiences (id, name, subscribed), created_at e updated_at. I contatti di un segmento tracciato hanno anche joined_at.
data[].joined_atstring | null
Solo per i segmenti tracciati: quando è iniziata la permanenza attuale del contatto nel segmento. null finché il tracciamento non ha registrato il contatto, ad esempio subito dopo che ha iniziato a corrispondere, mentre il segmento è syncing o mentre il tracciamento è paused.
total_recordsinteger
Numero di contatti che corrispondono al segmento, alla ricerca e ai filtri.
subscribed_countinteger
A quanti di loro le campagne possono inviare: non disiscritti a livello globale e iscritti ad almeno una lista.
next_page_urlstring | null
Percorso della pagina successiva, oppure null sull’ultima pagina. Contiene page, limit e search; quando lo segui, aggiungi di nuovo i filtri.
previous_page_urlstring | null
Percorso della pagina precedente, oppure null sulla prima pagina.

Restituisce 404 se il segmento non esiste.

GET/segments/{id}/contacts
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d email.ends_with=acme.com
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
}

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.

GET/segments/{id}/growth

Parametri di percorso

idstringobbligatorio
L’ID del segmento (seg_…).

Parametri di query

daysintegerpredefinito: 30
Numero di giorni da restituire, da 1 a 365, fino a oggi.

Restituisce

objectstring
Sempre segment_growth.
segment_idstring
L’ID del segmento.
dataobject[]
Una riga per giorno.
data[].datestring
Il giorno UTC, YYYY-MM-DD.
data[].members_countinteger | null
I membri alla fine del giorno, oppure il conteggio più recente per oggi. I giorni senza un nuovo conteggio riportano il valore precedente, ad esempio mentre il tracciamento è in pausa. null prima dell’inizio del tracciamento.
data[].joined_countinteger
Contatti entrati nel segmento quel giorno.
data[].left_countinteger
Contatti usciti dal segmento quel giorno.
Stato Quando
404 Il segmento non esiste.
422 Il segmento non è tracciato.
GET/segments/{id}/growth
Terminal
curl -G https://api.emailit.com/v2/segments/seg_2nYs9Kd1Lq3vB8wXcE4fT7uRm0p/growth \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d days=7
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 }
  ]
}

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.

POST/segments/preview

Parametri del corpo

audience_idsstring[]
ID delle liste da cui attingerebbe il segmento. Vuoto o omesso significa tutti i contatti.
conditionsobject
Le regole. Vedi Crea un segmento.
limitintegerpredefinito: 10
Numero di contatti del campione, da 1 a 25.

Restituisce

objectstring
Sempre segment_preview.
audience_idsstring[]
Le liste di origine, senza duplicati.
conditionsobject
Le regole come verrebbero salvate: un { match, rules } piatto diventa un unico gruppo e i gruppi vuoti vengono scartati.
contacts_countinteger
Contatti che corrispondono.
subscribed_countinteger
A quanti di loro le campagne possono inviare.
contactsobject[]
I contatti corrispondenti più recenti, nella stessa forma di Elenca i contatti di un segmento.

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

POST/segments/preview
Terminal
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
  }'
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"
    }
  ]
}

Elenca i campi dei segmenti

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

GET/segments/fields

Restituisce

dataobject[]
Un elemento per campo.
data[].keystring
Il valore da usare come field di una regola, ad esempio email_domain o custom_fields.plan.
data[].labelstring
Nome visualizzato. Per i campi personalizzati, il nome del campo personalizzato.
data[].typestring
string, 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[].groupstring
contact, custom_fields, audiences, commerce (dati di acquisto) o engagement (attività sulle campagne).
data[].operatorsstring[]
Gli operatori accettati dal campo.
data[].valuesobject[]
Valori consentiti, come value e label: le opzioni dei campi personalizzati a selezione e a selezione multipla, subscribed e unsubscribed per status e le liste del workspace per audience. Assente per gli altri campi.
GET/segments/fields
Terminal
curl https://api.emailit.com/v2/segments/fields \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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"]
    }
  ]
}

Questa pagina ti è stata utile?

Grazie del feedback.

Grazie, leggiamo ogni messaggio.