Audience: Segmentazione

Un' audience è un gruppo di contatti definito da regole. Usa le audience per segmentare i tuoi contatti per campagne e flussi mirati.

Crea un'Audience

Definisci un'audience usando regole di filtraggio.

cURL

curl -X POST https://api.tratto.email/v1/audiences \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Iscritti Newsletter VIP",
    "rules":[
      {"field":"status","operator":"equals","value":"subscribed"},
      {"field":"tags","operator":"array_contains","value":"vip"}
    ]
  }'

Risposta:

{
  "data": {
    "id": "aud_abc123"
  }
}

Le audience con rules vengono materializzate in modo asincrono subito dopo la creazione — chiama GET /v1/audiences/{id} poco dopo per ottenere il contactCount risolto.

Tipi di Regole

Ogni regola è { field, operator, value }. Operatori disponibili: equals, not_equals, contains, not_contains, array_contains.

Campo	Operatori validi	Esempio
`status`	`equals`, `not_equals`	`subscribed`, `bounced`
`tags`	solo `array_contains`	L'audience ha contatti taggati "vip": `tags` è una lista, quindi solo `array_contains` produce un match reale. `equals`/`contains` non corrispondono mai a una lista e restituiscono silenziosamente zero risultati.

contains/not_contains/array_contains confrontano le stringhe senza distinguere maiuscole/minuscole.

Regole Multiple (Logica AND)

Tutte le regole devono corrispondere:

{
  "rules": [
    {"field": "status", "operator": "equals", "value": "subscribed"},
    {"field": "tags", "operator": "array_contains", "value": "newsletter"}
  ]
}

Questa audience include contatti che sono:

Status: subscribed E
Hanno tag: newsletter

Aggiungi Contatti Manualmente

In aggiunta alle regole, aggiungi manualmente contatti specifici.

cURL

curl -X POST https://api.tratto.email/v1/audiences/aud_abc123/contacts \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds":["cont_abc123","cont_def456"]
  }'

Risposta:

{
  "data": {
    "added": 2,
    "alreadyInAudience": 0,
    "notFound": 0
  }
}

Dinamica vs Statica

Dinamica (ha rules): l'appartenenza viene riconciliata automaticamente a ogni create/update/delete di un contatto — un contatto che inizia (o smette) a corrispondere alle regole di un'audience vi entra (o ne esce) subito, senza azione manuale.
Statica (nessuna rules, contatti aggiunti tramite l'endpoint sopra): elenco fisso, non cambia mai da solo.

Un'audience è dinamica se ha rules, statica altrimenti — non esiste un campo type separato, viene dedotto da se rules è vuoto o no.

Elenca le Audience

Ottieni tutte le audience per il tuo tenant.

cURL

curl https://api.tratto.email/v1/audiences \
  -H "Authorization: Bearer tratto_live_..."

Ottieni Dettagli dell'Audience

Recupera un'audience specifica.

cURL

curl https://api.tratto.email/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": {
    "id": "aud_abc123",
    "name": "Iscritti Newsletter VIP",
    "description": "",
    "rules": [...],
    "contactCount": 1250,
    "createdAt": "2025-06-30T12:00:00Z"
  }
}

Modifica un'Audience

Cambia il nome, la descrizione o le regole. Tutti i campi sono facoltativi: un campo omesso mantiene il suo valore. Richiede contacts:write.

cURL

curl -X PATCH https://api.tratto.email/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Iscritti VIP",
    "rules":[
      {"field":"status","operator":"equals","value":"subscribed"},
      {"field":"tags","operator":"array_contains","value":"vip"}
    ]
  }'

La risposta è l'audience aggiornata, con la stessa forma di Ottieni Dettagli dell'Audience. name va da 1 a 100 caratteri, description fino a 500.

Se mandi una lista rules non vuota, l'appartenenza viene ricalcolata su tutti i contatti prima della risposta, quindi contactCount è già quello nuovo. Da lì in poi conta solo la regola: un contatto che avevi aggiunto a mano e che non la soddisfa viene tolto. Con "rules": [] l'audience diventa statica: le regole si azzerano, i membri attuali restano e non si ricalcola niente.

Un id inesistente risponde 404.

Ricalcola un'Audience Dinamica

Ricalcola un'audience dinamica sui contatti come sono adesso e restituisce il conteggio risultante. Richiede contacts:write.

cURL

curl -X POST https://api.tratto.email/v1/audiences/aud_abc123/refresh \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": {
    "contactCount": 1250
  }
}

Come un cambio di regole, il ricalcolo aggiunge ogni contatto che soddisfa le regole e toglie ogni membro che non le soddisfa, compresi quelli aggiunti a mano. Su un'audience statica (senza rules) non c'è niente da ricalcolare e la chiamata risponde 422 VALIDATION_ERROR. Un id inesistente risponde 404.

Elenca i Membri di un'Audience

Legge i contatti di un'audience, dal contatto più recente. Richiede contacts:read.

cURL

curl "https://api.tratto.email/v1/audiences/aud_abc123/contacts?limit=50" \
  -H "Authorization: Bearer tratto_live_..."

Parametri di query:

limit: risultati per pagina, da 1 a 100 (default 50)
after: il nextCursor della pagina precedente

Risposta:

{
  "data": [
    {
      "id": "cont_abc123",
      "email": "alice@example.com",
      "firstName": "Alice",
      "lastName": "Rossi",
      "status": "subscribed"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cont_abc123"
  }
}

Continua a passare nextCursor come after finché hasMore è false; a quel punto nextCursor è null. Un cursore che non corrisponde a un contatto esistente viene ignorato e l'elenco riparte dalla prima pagina. Un id di audience inesistente risponde 404.

Togli un Contatto da un'Audience

Toglie un contatto da un'audience. Il contatto in sé non cambia in nessun altro modo. Richiede contacts:write.

cURL

curl -X DELETE https://api.tratto.email/v1/audiences/aud_abc123/contacts/cont_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Restituisce 204 No Content, anche quando il contatto non era membro: ripetere la chiamata non fa danni. Un id di contatto inesistente risponde 404.

Su un'audience dinamica la rimozione non è definitiva: il prossimo ricalcolo o cambio di regole rimette dentro il contatto se le soddisfa ancora. Per tenerlo fuori davvero, cambia qualcosa che le regole guardano, per esempio un tag.

Elimina un'Audience

Elimina definitivamente l'audience stessa. I contatti non vengono mai toccati: eliminare un'audience rimuove solo quel raggruppamento; ogni contatto che ne era membro continua a esistere intatto, con tutti i suoi dati, tag e stato.

cURL

curl -X DELETE https://api.tratto.email/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Restituisce 204 No Content in caso di successo.

Se l'audience è ancora referenziata da una campagna che non ha finito l'invio (draft, scheduled, sending o paused), la richiesta viene rifiutata con 409 Conflict. Rimuovi prima l'audience da quelle campagne, oppure aspetta che completino.

Usare le Audience nelle Campagne

Invia una campagna a un'intera audience.

cURL

curl -X POST https://api.tratto.email/v1/campaigns \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Offerta Q3 VIP",
    "templateId":"tmpl_abc123",
    "audienceId":"aud_abc123"
  }'

Usare le Audience nei Flussi

Attiva un flusso quando un contatto si unisce a un'audience.

{
  "name": "Benvenuto VIP",
  "trigger": {
    "type": "contact_joins_audience",
    "audienceId": "aud_abc123"
  },
  "steps": [...]
}

Vedi Flussi per i dettagli.

Prossimi Passi

Inviare a un'audience? Vai a Campagne
Attivare flussi all'unione dell'audience? Vedi Flussi
Taggare contatti? Torna a Contatti

Audience: Segmentazione

In questa pagina