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.

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"
  }
}

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