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).

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.

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