Endpoint Eventi email

GET /api/v1/sends — eventi delivery, open, click, bounce con cursor `since` per polling incrementale.

L'endpoint sends ti dà accesso agli eventi email del tuo tenant: ogni record corrisponde a un'email inviata + tutti gli stati attraversati (sent, delivered, opened, clicked, bounced, complained, suppressed, failed).

È pensato per polling incrementale: il consumer salva l'ultimo next ricevuto e lo passa come since alla prossima chiamata, ricevendo solo gli eventi nuovi.

GET /api/v1/sends

Scope richiesto: sends:read

Query params

Param	Tipo	Default	Descrizione
limit	int	100	1–500
since	ISO timestamp	—	Restituisce sends con created_at > questo valore
campaignId	UUID	—	Filtra per una specifica campagna
status	enum	—	queued | sent | delivered | opened | clicked | bounced | complained | suppressed | failed | delayed

I sends sono ordinati per created_at ascendente: puoi consumarli in ordine cronologico senza saltare eventi.

Esempio cURL

curl -s -H "Authorization: Bearer $SMARTCQ_KEY" \
  "https://app.smartcq.it/api/v1/sends?since=2026-05-09T00:00:00Z&limit=200"

Risposta 200

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000a01",
      "campaignId": "00000000-0000-0000-0000-000000000c01",
      "contactId": "00000000-0000-0000-0000-000000000001",
      "status": "delivered",
      "sentAt": "2026-05-10T08:00:00.000Z",
      "deliveredAt": "2026-05-10T08:00:03.000Z",
      "openedAt": null,
      "clickedAt": null,
      "error": null,
      "createdAt": "2026-05-10T08:00:00.000Z"
    }
  ],
  "next": "2026-05-10T08:00:00.000Z"
}

Pattern polling incrementale

let since = loadCheckpoint() ?? "1970-01-01T00:00:00.000Z";

while (true) {
  const url = new URL("https://app.smartcq.it/api/v1/sends");
  url.searchParams.set("since", since);
  url.searchParams.set("limit", "500");
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SMARTCQ_KEY}` },
  });
  const j = await res.json();

  for (const send of j.data) {
    await processEvent(send);
  }

  if (j.next === null) {
    saveCheckpoint(since);
    break;
  }
  since = j.next;
}

Nota — Per reazione real-time agli eventi (bounce, unsubscribe) usa i webhook invece del polling. Le API sends sono utili per backfill iniziale o riconciliazione periodica.