Campagne

Stati, audience filter, fan-out asincrono e statistiche.

Le campagne inviano un template a un segmento dell'audience tramite fan-out asincrono. Ogni tenant gestisce le proprie campagne in isolamento.

Scope richiesti: campaigns:read e campaigns:write. Vedi API key e scope.

Stati della campagna

Stato	Descrizione
`DRAFT`	Bozza; modificabile, invio di prova disponibile
`SCHEDULED`	Programmata per data futura
`SENDING`	Fan-out in corso
`SENT`	Invio completato
`PAUSED`	In pausa (se supportato dal flusso)
`CANCELLED`	Annullata prima o durante l'invio

Endpoint principali

Azione	Endpoint	Scope
Creare	`POST /campaigns`	`campaigns:write`
Elencare	`GET /campaigns`	`campaigns:read`
Dettaglio + stats	`GET /campaigns/:id`	`campaigns:read`
Modificare	`PATCH /campaigns/:id`	`campaigns:write` (solo `DRAFT`)
Invio di prova	`POST /campaigns/:id/test`	`campaigns:write`
Programmare	`POST /campaigns/:id/schedule`	`campaigns:write`
Inviare ora	`POST /campaigns/:id/send`	`campaigns:write`
Annullare	`POST /campaigns/:id/cancel`	`campaigns:write`
Copertura lingua	`GET /campaigns/:id/locale-coverage`	`campaigns:read`

Creare una campagna

{
  "name": "Newsletter giugno",
  "templateVersionId": "clx...",
  "subject": "Override opzionale",
  "projectId": "clx...",
  "timezone": "Europe/Rome",
  "audienceFilter": {
    "locale": "it",
    "optIn": true,
    "projectId": "clx..."
  }
}

audienceFilter usa gli stessi criteri di GET /contacts — vedi Contatti e audience.

Fan-out asincrono

L'invio accoda job BullMQ (mc:campaign-dispatch → chunk di CAMPAIGN_CHUNK_SIZE, default 100). La quota mensile viene verificata al dispatch, non alla creazione.

Idempotenza per destinatario: idempotencyKey = campaignId:contactId.

Statistiche

GET /campaigns/:id include stats:

{
  "queued": 0,
  "sent": 1200,
  "delivered": 1180,
  "bounced": 5,
  "opened": 450,
  "clicked": 120,
  "unsub": 3,
  "rejected": 15
}

I rejected includono contatti soppressi o senza consenso.

Prossimi passi

Creare e inviare campagna — test → schedule → send
Copertura per lingua — verificare varianti prima dell'invio