Analytics: Riepilogo e Timeseries

Usa gli endpoint analytics per comprendere le prestazioni email nelle tue campagne e flussi.

Metriche di Riepilogo

Ottieni metriche aggregate per un periodo di tempo.

cURL

curl "https://api.tratto.email/v1/analytics/summary?period=30d" \
  -H "Authorization: Bearer tratto_live_..."

Parametri di Query:

• period: Intervallo di tempo — 7d, 30d, 90d (default 30d), 180d, o 1y

Risposta:

{
  "data": {
    "period": "30d",
    "totalSent": 50000,
    "delivered": 49500,
    "opened": 24750,
    "clicked": 7425,
    "bounced": 400,
    "complained": 100,
    "deliveryRate": 99,
    "openRate": 50,
    "clickRate": 15,
    "bounceRate": 0.8,
    "avgDeliveryLatencySeconds": 4.2
  }
}

Definizioni Metriche

unsubscribed non fa parte di questo endpoint — è tracciato sul contatto, non sulla singola email. Controlla lo status di un contatto. Nemmeno una campagna ha un conteggio unsubscribed: la cosa più vicina è stats.skipped, gli invii annullati perché il contatto si è disiscritto fra il dispatch e la consegna (vedi Campagne).

Tassi

Tutti i tassi sono percentuali (98.5 significa 98.5%, non 0.985).

Questi sono tassi dell'intero workspace. Per una singola campagna, compresi i risultati per oggetto di un test A/B, usa GET /v1/campaigns/:id/stats: i suoi tassi di apertura e di click escludono i destinatari che hanno rifiutato il tracciamento.

Dati Timeseries

Ottieni scomposizione giornaliera delle metriche.

cURL

curl "https://api.tratto.email/v1/analytics/timeseries?period=7d" \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": [
    {
      "date": "2026-07-30",
      "sent": 5000,
      "delivered": 4950,
      "opened": 2475,
      "bounced": 40
    },
    {
      "date": "2026-07-29",
      "sent": 4800,
      "delivered": 4752,
      "opened": 2376,
      "bounced": 38
    }
  ]
}

Nota lo shape più stretto rispetto all'endpoint di riepilogo: solo sent/delivered/opened/bounced, niente clicked o complained per giorno.

Link Più Cliccati

Ottieni i link più cliccati per una campagna specifica.

cURL

curl "https://api.tratto.email/v1/campaigns/camp_abc123/links?limit=20" \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": [
    { "linkUrl": "https://example.com/pricing", "clicks": 142, "uniqueClicks": 98 },
    { "linkUrl": "https://example.com/docs", "clicks": 37, "uniqueClicks": 30 }
  ]
}

limit è opzionale, 1-50, default 20.

Dati Live e di Test

Le analytics seguono l'ambiente della chiave che le chiede. Una chiave tratto_live_... legge solo gli invii live, una chiave tratto_test_... solo quelli di test.

Entrambi gli endpoint accettano anche un parametro di query livemode (true o false). È l'interruttore di vista della dashboard e per le chiavi API viene ignorato: vince sempre l'ambiente della chiave, quindi una chiave live non legge i numeri di test e una chiave di test non legge quelli live, qualunque valore passi.

La vista di test è limitata a 7d, 30d e 90d. I periodi più lunghi leggono un aggregato che contiene solo dati live, quindi una chiave di test che chiede 180d o 1y riceve 422 VALIDATION_ERROR invece di una serie di zeri:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Analytics for the test environment are not available for the '180d' period.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "suggestion": "Periods longer than 90 days read the long-term aggregate, which contains live data only. Use period=90d or shorter for the test view."
  }
}

Finestre Dati: Firestore vs BigQuery

• 7d/30d/90d sono servite da Firestore in tempo reale — nessun ritardo di aggregazione, ma Firestore conserva i documenti email solo per 90 giorni.
• 180d/1y sono servite invece da un aggregato BigQuery notturno. L'aggregazione gira una volta al giorno (intorno alle 02:30 UTC) — i dati molto recenti (oggi, e a volte ieri a seconda di quando controlli) non sono ancora riflessi per queste due finestre più lunghe. Usa 90d o meno se ti servono numeri dello stesso giorno.

Best Practice

1. Monitora il Tasso di Consegna

Target 99%+. Tassi più bassi indicano problemi di dominio o igiene dell'elenco.

if (data.deliveryRate < 95) {
  alert('Low delivery rate detected');
}

2. Traccia i Tassi di Apertura e Clic

Benchmark tipici:

• Tasso di apertura: 20-50% (varia per settore)
• Tasso di clic: 5-20% (varia per settore)

Tassi bassi suggeriscono problemi di contenuto o tempistica.

3. Monitora i Tassi di Rimbalzo e Reclamo

• Tasso di rimbalzo: < 2% accettabile (< 5% è OK)
• Tasso di reclamo: complained / totalSent — tienilo sotto lo 0.1%

Tassi alti danneggiano la reputazione del mittente e la deliverability.

Prossimi Passi

• Visualizzare gli eventi a livello di email? Usa l'API Stato Email
• Tracciare gli eventi in tempo reale? Configura Webhook
• Comprendere la deliverability? Vedi Deliverability