Campagne: Draft, Programma e Invia

Una campagna è una trasmissione email una tantum a un'audience. Crea una campagna, opzionalmente testala, poi inviala a centinaia o migliaia di destinatari.

Crea una Campagna (Draft)

Crea una campagna in status draft. name, subjectA ed esattamente uno fra templateId e html sono obbligatori: se ometti subjectA la richiesta fallisce con 422.

cURL

curl -X POST https://api.tratto.email/v1/campaigns \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Saldi Estivi Q3",
    "subjectA":"I saldi estivi iniziano oggi",
    "templateId":"tmpl_abc123",
    "audienceId":"aud_abc123"
  }'

Risposta: l'id, e nient'altro.

{
  "data": {
    "id": "camp_xyz789"
  }
}

Usa GET /v1/campaigns/{id} per leggerne status, contenuto e statistiche.

Campi del body:

Se né il body né il workspace forniscono un mittente, la richiesta fallisce con 422 e un messaggio che ti dice di impostare un mittente di default.

Dalla creazione in poi la campagna possiede una copia del contenuto del template: modificare il template dopo non cambia una campagna già creata da esso, e modificare la campagna non tocca il template.

Invio di Test

Invia un'email di test prima del lancio per assicurarti che tutto appaia corretto.

cURL

curl -X POST https://api.tratto.email/v1/campaigns/camp_xyz789/test-send \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]"}'

Un'email di test viene inviata al tuo indirizzo immediatamente.

Invia Immediatamente

Invia la campagna a tutti i contatti nell'audience proprio adesso.

cURL

curl -X POST https://api.tratto.email/v1/campaigns/camp_xyz789/send \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": {
    "status": "sending"
  }
}

Lo status della campagna diventa sending, poi completed a invio concluso.

L'invio è rifiutato con 409 se la campagna non è draft o paused, e prima di partire viene confrontato con la quota mensile residua.

Programma per Dopo

Programma la campagna con scheduledAt (ISO 8601). Il campo non si chiama sendAt.

cURL

curl -X POST https://api.tratto.email/v1/campaigns/camp_xyz789/send \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-10-01T09:00:00Z"}'

Lo status della campagna diventa scheduled e l'invio parte automaticamente a quell'orario. Uno scheduledAt nel passato equivale a «invia adesso».

Per annullare la programmazione e riportare la campagna a draft:

curl -X POST https://api.tratto.email/v1/campaigns/camp_xyz789/unschedule \
  -H "Authorization: Bearer tratto_live_..."

Risponde 409 se il dispatcher ha già iniziato l'invio: in quel caso metti in pausa.

Ciclo di Vita dello Status della Campagna

Gli status sono cinque: draft, scheduled, sending, paused e completed. sent non esiste.

draft
  ├─→ (test-send)
  ├─→ send                 → sending → completed
  └─→ send + scheduledAt   → scheduled → sending → completed
                                └─→ unschedule → draft

sending / scheduled  ─→ pause → paused ─→ send (ripresa) → sending

Pausa una Campagna

Interrompi una campagna programmata o in corso. Si può mettere in pausa solo una campagna sending o scheduled: qualsiasi altro status è un 409.

cURL

curl -X POST https://api.tratto.email/v1/campaigns/camp_xyz789/pause \
  -H "Authorization: Bearer tratto_live_..."

La ripresa è una nuova POST /:id/send sulla campagna in pausa: non esiste un endpoint di ripresa separato. Riparte dai soli destinatari mai raggiunti, quindi nessuno riceve l'email due volte.

Una campagna può anche essere messa in pausa per te: se l'invio esaurisce la quota mensile a metà strada, il dispatcher la mette in pausa e imposta pausedReason a "quota_exceeded". Su una campagna che hai messo in pausa tu, pausedReason è null: quel campo è l'unico modo per distinguere i due casi.

Una campagna in pausa può essere ripresa; solo una in draft può essere eliminata.

Ottieni Statistiche Campagna

Visualizza le statistiche di consegna dopo l'invio.

cURL

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

Risposta: conteggi e tassi sono due oggetti distinti.

{
  "data": {
    "campaignId": "camp_xyz789",
    "status": "completed",
    "stats": {
      "total": 5000,
      "sent": 5000,
      "delivered": 4950,
      "opened": 2475,
      "clicked": 742,
      "bounced": 40,
      "skipped": 12,
      "untracked": 130
    },
    "rates": {
      "deliveryRate": 99,
      "openRate": 50.82,
      "clickRate": 15.24,
      "bounceRate": 0.8,
      "untracked": 130
    }
  }
}

Note sui campi:

• total è il numero di destinatari; sent conta quelli effettivamente inviati
• skipped — invii annullati perché il contatto si è disiscritto dopo il dispatch. Non sono mai avvenuti, quindi non alimentano nessun tasso
• untracked — destinatari che hanno rifiutato il tracciamento di aperture e click. Sono esclusi dal denominatore di openRate e clickRate, mai stimati. La chiave untracked dentro rates è quello stesso conteggio, non un tasso
• stats.variants e rates.variants compaiono solo su una campagna che ha fatto un test A/B sull'oggetto
• Non esiste un campo complained, né totalSent

Elenca le Campagne

Ottieni tutte le campagne.

cURL

curl "https://api.tratto.email/v1/campaigns?status=completed&limit=50" \
  -H "Authorization: Bearer tratto_live_..."

Parametri di query:

• status: Filtra per status — draft, scheduled, sending, paused, completed. sent non è un valore valido e restituisce 422
• q: Ricerca per prefisso del nome, case-insensitive ma sensibile agli accenti (sal trova Saldi estate, estate no). Finché è attiva, l'ordinamento è per nome invece che dal più recente
• limit: Risultati per pagina (default 50, max 100)
• after: Cursor per paginazione

Ottieni Dettagli Campagna

Recupera una campagna specifica.

cURL

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

Best Practice per le Campagne

1. Testa Sempre Prima

Invia un'email di test a te stesso prima del lancio a qualsiasi audience.

2. Usa Nomi Descrittivi

✅ Saldi Estivi Q3 - Segmento Newsletter
❌ Campagna 1, Test

3. Rivedi la Dimensione dell'Audience

Conta i destinatari prima dell'invio: GET /v1/contacts?status=subscribed&audienceId=… restituisce lo stesso pagination.total che conta il gate d'invio. Un'audience senza contatti iscritti significa che nessuno la riceve.

4. Programma Durante i Tempi Ottimali

Considera il fuso orario della tua audience quando programmi. Inizio mattina o pausa pranzo di solito vedono tassi di apertura più alti.

5. Monitora le Statistiche di Consegna

Dopo l'invio, esamina i tassi di rimbalzo, reclamo e apertura per comprendere l'engagement.

6. Crea Nuove Campagne, Non Reinviare

Una campagna raggiunge ogni destinatario una volta sola. Reinviare una campagna completed è un 409; riprendere una paused copre solo i destinatari mai raggiunti. Per scrivere di nuovo alla stessa audience, crea una nuova campagna.

Prossimi Passi

• Tracciare gli eventi della campagna? Configura Webhook
• Automatizzare l'invio? Usa Flussi
• Analizzare le prestazioni? Controlla Analytics