# Eventi

> Consulta gli eventi che Emailit registra per il tuo workspace nel pannello o con l’API degli eventi, e usali per recuperare o riconciliare i webhook.

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](/it/docs/webhooks/) a partire da essi. Questa pagina spiega come consultare gli eventi e leggerli con l’API.

## Cosa contiene un evento

| Campo | Descrizione |
| --- | --- |
| `id` | L’ID dell’evento, che inizia con `evt_`. Nelle richieste webhook si chiama `event_id`. |
| `type` | Cosa è successo, ad esempio `email.delivered` o `contact.created`. Vedi [Tipi di evento](/it/docs/webhooks/event-types/). |
| `data.object` | La risorsa a cui si riferisce l’evento, come l’email, il clic, il dominio o il contatto, così com’era quando l’evento è avvenuto. |
| `created_at` | Quando è stato registrato l’evento. |

```json
{
  "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](/it/docs/webhooks/set-up/#filter-events-by-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](/it/docs/api-reference/events/list/) restituisce gli eventi a partire dal più recente.

| Parametro di query | Descrizione |
| --- | --- |
| `type` | Un tipo, o più tipi separati da virgole, ad esempio `email.bounced,email.complained`. |
| `include_data` | `true` per includere `data` per ogni evento. Il valore predefinito è `false`, che restituisce solo `id`, `type` e `created_at`. |
| `page`, `limit` | Numero e dimensione della pagina. `limit` va da 1 a 100 e il valore predefinito è 100. |
| `created_at.after`, `created_at.before` | Filtri sulla data. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/). |

```bash
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"
```

```json
{
  "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](/it/docs/api-reference/events/get/) restituisce un evento in base al suo ID `evt_`, sempre con `data`.

```bash
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](/it/docs/webhooks/retries-and-failures/#retry-failed-requests) 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:

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Log delle richieste conservati | 7 giorni | 30 giorni | 30 giorni | Flessibile |

## Vedi anche

  - [Tipi di evento](/it/docs/webhooks/event-types/)
  - [API degli eventi](/it/docs/api-reference/events/)

---
Fonte: https://emailit.com/it/docs/logs/events/