Eventi

Un evento è il record di qualcosa che è accaduto nel tuo workspace: un’email è stata consegnata, un link è stato cliccato, un messaggio è arrivato sul tuo sottodominio di ricezione, un contatto è stato creato. Emailit salva ogni evento, li mostra nel pannello e costruisce ogni richiesta webhook a partire da essi. Questa pagina spiega come consultare gli eventi e leggerli con l’API.

Cosa contiene un evento

{
  "object": "event",
  "id": "evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
      "object": "email",
      "from": "billing@acme.com",
      "to": "ada@example.com",
      "subject": "Your receipt #1042",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T09:14:03.512000+00:00",
      "created_at": "2026-10-01T09:14:01.207000+00:00"
    }
  },
  "created_at": "2026-10-01T09:14:03.540000+00:00"
}

Eventi e webhook

Gli eventi sono l’origine delle richieste webhook. Quando Emailit registra un evento, mette in coda una richiesta per ogni webhook attivo che sottoscrive quel tipo di evento e il cui filtro sul payload corrisponde. L’evento viene salvato indipendentemente dal fatto che un webhook lo riceva.

Questo ha due conseguenze:

• Un webhook riceve solo gli eventi che avvengono mentre esiste ed è attivo. Gli eventi registrati mentre un webhook era disattivato, o prima che fosse creato, non gli vengono inviati in seguito.
• Puoi usare l’elenco degli eventi per colmare le lacune. Dopo un’interruzione o un periodo di disattivazione, leggi con l’API gli eventi di quella finestra temporale ed elabora quelli che il webhook ha perso. Elimina i duplicati in base all’ID dell’evento, che è lo stesso ID evt_ che i webhook usano come event_id.

Consulta gli eventi nel pannello

Vai a Email API›Events. La tabella mostra per ogni evento Event type, ID e l’orario Created, a partire dal più recente.

• Per impostazione predefinita la pagina mostra gli ultimi 2 giorni. Aggiungi un filtro Created per andare più indietro, entro il periodo di conservazione.
• Filtra per Type per vedere un solo tipo di evento, ad esempio solo email.bounced.
• Seleziona un evento per vedere l’orario Created, il Type e il Payload completo in JSON, con un pulsante per copiarlo.

Leggi gli eventi con l’API

Entrambi gli endpoint richiedono una chiave API con Full Access.

Elenca gli eventi

Elenca gli eventi restituisce gli eventi a partire dal più recente.

curl -G https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "type=email.bounced,email.complained" \
  --data-urlencode "created_at.after=2026-09-28T00:00:00Z" \
  --data-urlencode "include_data=true"

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xGkB3n8WqZ5cT1vRmK7pLsD4hY",
      "type": "email.bounced",
      "data": { "object": { "id": "em_2xGkA9m1PdX6bR3sQnJ8tKfW2eV", "object": "email", "status": "bounced" } },
      "created_at": "2026-09-30T17:02:41.118000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.bounced%2Cemail.complained&include_data=true",
  "previous_page_url": null
}

Due limiti mantengono veloce questo endpoint:

• Finestra predefinita. Senza un filtro created_at, l’elenco copre gli ultimi 2 giorni. Aggiungi created_at.after per leggere gli eventi più vecchi.
• Profondità delle pagine. L’offset, (page - 1) × limit, non può superare 2500. Le pagine più profonde restituiscono 422 con il codice events_offset_too_large. Restringi la richiesta con type o con un intervallo created_at invece di andare avanti con le pagine.

Recupera un evento

Recupera un evento restituisce un evento in base al suo ID evt_, sempre con data.

curl https://api.emailit.com/v2/events/evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

Riconcilia gli eventi webhook persi

1. Scegli la finestra. Annota quando il tuo endpoint ha iniziato a non rispondere o quando il webhook è stato disattivato, e quando il problema è stato risolto.

2. Elenca gli eventi. Chiama GET /v2/events con created_at.after e created_at.before impostati su quella finestra, i valori type gestiti dal tuo webhook e include_data=true. Segui next_page_url finché non è null. Se ricevi events_offset_too_large, dividi la finestra in intervalli più brevi.

3. Elabora quello che non hai ancora visto. Salta gli eventi il cui ID hai già salvato come elaborato, e gestisci gli altri con lo stesso codice che usa il tuo webhook.

Per le richieste che erano in coda ma non sono riuscite, Retry failed sul webhook è più semplice, purché gli errori risalgano a meno di 7 giorni prima.

Conservazione

Gli eventi seguono il periodo di conservazione Logs, come i log delle richieste e le richieste webhook:

Vedi anche