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. Il mittente viene scritto sulla campagna al momento della creazione: vedi Mittenti.

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. Per una campagna Markdown vedi Modificare il markdown dentro una campagna.

Test A/B sull'oggetto

Imposta subjectB per mettere alla prova un secondo oggetto contro subjectA. Contenuto, mittente e audience restano gli stessi: cambia solo l'oggetto.

• Come si dividono i destinatari. Gli oggetti si alternano un destinatario alla volta: il primo riceve subjectA, il secondo subjectB, e così via. Ogni oggetto raggiunge metà dell'audience, con uno in più per A se il numero è dispari.
• Dopo una pausa. Una campagna ripresa continua l'alternanza dal punto in cui si era fermata invece di ripartire da A, così la divisione resta pari.
• Invii di prova. POST /v1/campaigns/:id/test-send usa sempre subjectA, preceduto da [TEST].
• Togliere B. Manda "subjectB": null con PATCH /v1/campaigns/:id. Come ogni modifica, funziona solo su una campagna draft: con qualunque altro stato la risposta è 409 Campaign is '<status>'. Only draft campaigns can be edited.
• Nessun vincitore automatico. Tratto non sceglie un oggetto e non manda il migliore al resto della lista: escono entrambi fino alla fine della campagna. Il confronto e la scelta spettano a te.

Leggere il risultato

GET /v1/campaigns/:id/stats aggiunge un oggetto variants con una voce per oggetto, sia in stats (conteggi) sia in rates (percentuali):

{
  "stats": {
    "variants": {
      "a": { "sent": 2500, "delivered": 2475, "opened": 1300, "clicked": 390, "bounced": 20, "untracked": 70 },
      "b": { "sent": 2500, "delivered": 2475, "opened": 1175, "clicked": 352, "bounced": 20, "untracked": 60 }
    }
  },
  "rates": {
    "variants": {
      "a": { "deliveryRate": 99, "openRate": 53.5, "clickRate": 16.05, "bounceRate": 0.8 },
      "b": { "deliveryRate": 99, "openRate": 48.16, "clickRate": 14.43, "bounceRate": 0.8 }
    }
  }
}

I tassi di ogni variante sono calcolati sul sent di quella variante, e i tassi di apertura e di click escludono i suoi destinatari untracked: la stessa regola dei totali della campagna (più sotto). variants c'è solo su una campagna che ha iniziato l'invio con un subjectB: su ogni altra campagna la chiave manca, non è riempita di zeri.

Variabili di una Campagna

Una campagna valorizza esattamente quattro variabili, risolte per destinatario al momento dell'invio:

Scrivile con le graffe doppie, nell'oggetto e nel corpo:

<p>Ciao {{firstName}}, i saldi estivi iniziano oggi.</p>
<p><a href="{{unsubscribe_url}}">Disiscriviti</a></p>

Tre cose decidono se funzionano.

Maiuscole e minuscole contano. {{firstName}} viene valorizzata, {{firstname}} no. La grafia della tabella qui sopra è l'unica che funziona.

Una graffa singola non è una variabile. {firstName} resta intatta e il destinatario la legge come testo. Solo {{firstName}} viene sostituita.

Un nome fuori da quei quattro diventa una stringa vuota. {{companyName}} in una campagna non fa fallire l'invio, e non lascia nemmeno il segnaposto a schermo. Sparisce, e la frase intorno arriva con un buco: Ciao {{companyName}} cliente viene consegnato come Ciao cliente. Niente, nella casella del destinatario, dice che lì c'era una variabile: è per questo che il punto in cui accorgersene è la bozza.

Perché il controllo esiste sulle campagne e non sui template

Una campagna viene inviata a dei contatti, quindi Tratto conosce i quattro nomi qui sopra e può segnalare tutto ciò che ne sta fuori mentre la campagna è ancora in bozza. Un template inviato con POST /v1/emails prende le variabili da chi chiama l'API, quindi non esiste un insieme chiuso contro cui verificarle e ogni controllo sarebbe un'ipotesi. Su un template l'unica difesa è passare a ogni invio tutti i segnaposto che il template usa. Vedi 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":"your-email@example.com"}'

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

Se Tratto non riesce a mettere in coda l'email di test, l'API restituisce 503 SERVICE_UNAVAILABLE con l'header Retry-After: non è partito niente e non è stata creata alcuna email, quindi puoi riprovare. Vedi Codici di Errore.

Gratis, con un tetto giornaliero

I test-send sono gratuiti: non contano sulla quota mensile. Ogni chiamata invia a un solo destinatario. Con l'API 0.24.0 o successiva, un workspace può fare 20 test-send al giorno su Free, 100 su Starter e Growth e 200 su Scale, fra template e campagne insieme, e il conteggio si azzera a mezzanotte UTC. Oltre il tetto l'API risponde 429 QUOTA_EXCEEDED e non parte niente: non riprovare prima dell'azzeramento. Una chiamata rifiutata con 404 o 422 non consuma il tetto; una chiamata accettata sì, anche se poi risponde 503, perché il tetto si conta prima della consegna alla coda.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Test send daily limit of 20 per workspace reached.",
    "suggestion": "The limit resets at midnight UTC. Test sends are free and do not count against your monthly quota. Starter raises the test-send limit to 100 a day. The account owner can upgrade at https://app.tratto.email/settings/billing.",
    "docs": "https://docs.tratto.email/en/docs/error-codes"
  }
}

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 (quel rifiuto è un 429, non un 409). Anche una campagna paused riceve un 409 finché la sua ondata di prova è ancora in misura: vedi Riprendere durante l'attesa dell'ondata.

L'invio è progressivo, non istantaneo. Le email escono con un tetto al secondo, quindi una campagna con molti destinatari resta sending per un po' prima di completarsi. È l'invio che lavora, non un guasto. Il tetto è un parametro operativo e può cambiare: non costruire un timeout su un numero misurato una volta sola.

In più, una campagna abbastanza grande parte con un'ondata di prova e si ferma a metà di proposito.

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_..."

Qui rispondono 409 due situazioni diverse, e il messaggio le distingue:

• l'invio è già partito (status è sending): il dispatcher ha preso la campagna prima che tu la annullassi
• la campagna sta aspettando la sua ondata di prova: risulta scheduled con scheduledReason: "bounce_check", ma una parte della lista ha già ricevuto l'email, quindi non c'è più niente da riportare a draft

In entrambi i casi metti in pausa: i destinatari già raggiunti non si possono disinviare. Mettere in pausa una campagna che sta aspettando la sua ondata non ti libera però dall'attesa: riprenderla è rifiutato finché l'attesa non è finita, ed è il 409 successivo da conoscere.

L'Ondata di Prova

Una campagna abbastanza grande non parte verso tutta la lista in una volta. Il primo invio raggiunge un'ondata di prova: il 5% dei destinatari rimanenti, mai meno di 50 e mai più di 500. Tratto aspetta poi 15 minuti, conta quanti di quegli indirizzi hanno rimbalzato in modo permanente, e solo allora fa partire il resto.

Perché esiste. Tratto invia su un pool condiviso (IP Warming) e il tasso di rimbalzi permanenti è ciò che decide se l'invio viene bloccato su quel pool, per tutti i workspace che lo usano. Una lista mai pulita non costa solo a chi la possiede. L'ondata limita quel costo a poche decine di email invece che all'intera lista.

Cosa vedi mentre è in corso. Dopo l'ondata la campagna torna scheduled per quei 15 minuti, con uno scheduledAt fra un quarto d'ora. Una campagna che non hai mai programmato può quindi risultare scheduled poco dopo che l'hai inviata. Riparte da sola, e stats.sent conta già l'ondata. Per tutta l'attesa scheduledReason vale "bounce_check", ed è quello che distingue questo caso da una data impostata da te: vedi Quale dei due scheduled.

Mettere in pausa durante l'attesa non salta l'attesa. La scadenza è fissata quando l'ondata esce e non si sposta, quindi la pausa tiene ferma la campagna dov'è invece di chiudere il controllo prima del tempo. Finché quella scadenza non passa, inviare di nuovo la campagna risponde 409: vedi Riprendere durante l'attesa dell'ondata.

Quando l'ondata non c'è:

• l'ondata coprirebbe comunque tutta la lista rimanente. Non dimostrerebbe niente, quindi la campagna parte e si completa come prima. Le campagne piccole non cambiano comportamento
• la campagna ha già raggiunto qualcuno. L'ondata si fa una volta per campagna: una ripresa dopo una pausa, un orario mancato o una quota esaurita riparte da dove si era fermata, senza una seconda attesa

Se il tasso di rimbalzi dell'ondata supera la soglia la campagna si mette in pausa da sola: vedi Perché una campagna è 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 ─→ ondata di prova ─→ scheduled (15 min) ─→ sending → completed
                                                └─→ paused (bounce_rate)

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

scheduled significa quindi due cose: un invio che hai programmato tu, oppure una campagna che sta aspettando la sua ondata di prova. Per l'ondata non è stato aggiunto nessuno status, quindi un client che ragiona solo su status non riesce a distinguere i due casi. Il campo che li distingue è scheduledReason.

Quale dei due scheduled

scheduledReason è di sola lettura, string | null, e torna in GET /v1/campaigns/{id} e in GET /v1/campaigns. Oggi ha un solo valore:

Il campo è additivo e nullable: si aggiunge a campi che c'erano già, quindi nessun client esistente si rompe ignorandolo. Quello che si rompe è dare per scontato che ogni campagna scheduled si possa ancora deprogrammare.

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. Un caso risponde 409 invece di riprendere, per un quarto d'ora al massimo: vedi Riprendere durante l'attesa dell'ondata.

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

Riprendere durante l'attesa dell'ondata

Metti in pausa una campagna a metà della sua ondata di prova, poi inviala di nuovo, e faresti partire il resto della lista prima che qualcuno abbia guardato come ha rimbalzato l'ondata. Due clic, e il controllo per cui l'ondata esiste non avviene mai. Per questo quell'invio è rifiutato: finché i 15 minuti di attesa hanno ancora tempo da scorrere, la POST /:id/send su quella campagna risponde 409, e il messaggio dice quante email l'ondata ha già raggiunto e quanti minuti restano, più o meno.

La forma programmata è rifiutata allo stesso modo. Una POST /:id/send con scheduledAt durante l'attesa non la aggira, quindi nemmeno una data nuova è una via d'uscita.

Le cose da fare sono due, e solo due. Invia di nuovo la campagna quando l'attesa è finita, e il resto della lista parte. Oppure lasciala in pausa e fermati lì. unschedule non è la terza: su una campagna in pausa risponde a sua volta 409, quindi non porta da nessuna parte.

In entrambi i casi i destinatari che l'ondata ha già raggiunto si tengono l'email. Non si richiamano indietro, ed è la parte che conviene sapere prima di decidere di fermarsi.

Il 409 costa l'attesa, non la campagna: si scioglie da solo quando la scadenza passa, e l'invio va a buon fine. Da notare che porta lo stesso codice CONFLICT di ogni altro conflitto di stato su queste rotte, quindi un client non lo distingue da «la campagna sta già spedendo» se non leggendo message.

Perché una campagna è in pausa

Una campagna può anche essere messa in pausa per te, e paused da solo non dice da chi. pausedReason è il campo che distingue i casi (l'equivalente di scheduledReason per una campagna scheduled), e ha quattro valori più null:

schedule_missed vale solo per una data impostata da te. Anche una campagna parcheggiata per la sua ondata di prova risulta scheduled, ma non viene messa in pausa così per quanto l'attesa sfori l'ora: il resto della lista non è un invio che nessuno si aspetta più, è la fine di quello che hai chiesto, quindi parte. Li distingue scheduledReason: "bounce_check" non viene mai messa in pausa per un orario mancato, null sì.

null copre due pause che si comportano in modo diverso. Una è la campagna che hai messo in pausa tu e che riprendi quando vuoi. L'altra è una campagna messa in pausa mentre la sua ondata di prova era in misura, e quella non si riprende finché l'attesa non è finita. Niente nella risposta la distingue: pause non scrive pausedReason, e scheduledReason vale "bounce_check" solo mentre lo status è scheduled, quindi su una campagna in pausa è null anche lui. Te lo dice la ripresa, che risponde 409 con i minuti che restano. Vedi Riprendere durante l'attesa dell'ondata.

La POST /:id/send successiva azzera pausedReason: leggilo prima di riprendere.

Fermata sul tasso di rimbalzi

Tratto conta i rimbalzi permanenti delle email che una campagna ha effettivamente fatto uscire: quelli temporanei non contano. Oltre il 5%, con un minimo di 3 rimbalzi, la campagna si mette in pausa da sola con pausedReason: "bounce_rate" e un'email arriva al proprietario del workspace. (I due numeri sono la stessa decisione vista due volte: 3 è il 5% di 50, cioè dell'ondata di prova più piccola.)

Il 5% si misura su tutto quello che la campagna ha spedito, contato dalla sua prima email e attraverso ogni ripresa, non sull'ondata o sul batch che è in volo. Quel numero è stats.sent: i rimbalzi che fermano la campagna sono il 5% di quello, mai meno di 3. Si muove mentre la campagna spedisce: più è avanti, più rimbalzi permanenti servono perché il freno scatti.

Il 5% è la stessa linea su cui viene giudicato il pool di invio condiviso: per questo ci fermiamo lì e non più tardi.

Niente riparte da solo. Non c'è nessun tentativo automatico e nessun timer: la campagna resta paused finché non la reinvii tu. È una scelta: una lista che ha rimbalzato a quel ritmo rimbalzerà di nuovo, a meno che la lista non cambi.

Prima di riprendere, togli gli indirizzi che hanno rimbalzato (Tratto li sopprime per gli invii futuri, ma restano nella tua lista finché non li elimini) e controlla da dove arriva la lista.

Quello che la ripresa ti dà è una misura nuova, non una garanzia da 50 email. Una campagna che riparte dopo uno stop per bounce_rate manda una nuova ondata di prova da 50 destinatari e aspetta gli stessi 15 minuti prima di far partire il resto. Se quei 50 bastino a prendere una lista che non hai pulito dipende dalla soglia su cui vengono misurati, e quella soglia è il 5% di tutto quello che la campagna ha già spedito:

• Una campagna fermata presto ha spedito poco, quindi la sua soglia è ancora al minimo di 3 o vicina. L'ondata la supera da sola, e non esce niente altro.
• Una campagna già avanti nella lista ha alzato la propria soglia sopra qualunque cifra 50 destinatari possano produrre. L'ondata passa il controllo, il resto della lista comincia a uscire, e lo stop arriva da un batch successivo.

Anche nel secondo caso il freno scatta, solo più tardi e dopo che è uscita più posta. Per sapere dove sei, leggi stats.sent e prendine il 5%: sono i rimbalzi permanenti che oggi fermano questa campagna. Pulire la lista è l'unica cosa che le evita di fermarsi una seconda volta.

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 avevano rifiutato il tracciamento di aperture e click quando la campagna li ha raggiunti. Le loro aperture e i loro click non vengono mai registrati, quindi sono esclusi dal denominatore di openRate e clickRate, mai stimati: openRate è opened / (total - untracked). Contarli abbasserebbe i tassi per persone che di proposito non misuriamo. 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