# Événements

> Parcourez les événements qu’Emailit enregistre pour votre espace de travail dans le tableau de bord ou avec l’API des événements, et utilisez-les pour rattraper ou rapprocher les webhooks.

Un événement est un enregistrement indiquant que quelque chose s’est produit dans votre espace de travail : un e-mail a été livré, un lien a été cliqué, un message est arrivé sur votre sous-domaine de réception, un contact a été créé. Emailit enregistre chaque événement, les affiche dans le tableau de bord et construit chaque requête de [webhook](/fr/docs/webhooks/) à partir d’eux. Cette page explique comment parcourir les événements et les lire avec l’API.

## Contenu d’un événement

| Champ | Description |
| --- | --- |
| `id` | L’ID de l’événement, qui commence par `evt_`. Dans les requêtes de webhook, il s’appelle `event_id`. |
| `type` | Ce qui s’est passé, par exemple `email.delivered` ou `contact.created`. Voir [Types d’événements](/fr/docs/webhooks/event-types/). |
| `data.object` | La ressource concernée par l’événement, comme l’e-mail, le clic, le domaine ou le contact, telle qu’elle était au moment de l’événement. |
| `created_at` | Date d’enregistrement de l’événement. |

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

## Événements et webhooks

Les événements sont la source des requêtes de webhook. Quand Emailit enregistre un événement, il met en file d’attente une requête pour chaque webhook activé qui est abonné à ce type d’événement et dont le [filtre de contenu](/fr/docs/webhooks/set-up/#filter-events-by-payload) correspond. L’événement est enregistré, qu’un webhook le reçoive ou non.

Cela a deux conséquences :

- Un webhook ne reçoit que les événements qui se produisent pendant qu’il existe et qu’il est activé. Les événements enregistrés pendant qu’un webhook était désactivé, ou avant sa création, ne lui sont pas envoyés après coup.
- Vous pouvez utiliser la liste des événements pour combler les manques. Après une panne ou une période de désactivation, lisez les événements de cette période avec l’API et traitez ceux que votre webhook a manqués. Dédoublonnez par ID d’événement : c’est le même ID `evt_` que les webhooks utilisent comme `event_id`.

## Parcourir les événements dans le tableau de bord

Accédez à **Email API → Events**. Le tableau affiche l’**Event type**, l’**ID** et l’heure **Created** de chaque événement, du plus récent au plus ancien.

- Par défaut, la page affiche les 2 derniers jours. Ajoutez un filtre **Created** pour remonter plus loin, dans la limite de votre durée de conservation.
- Filtrez par **Type** pour voir un seul type d’événement, par exemple uniquement `email.bounced`.
- Sélectionnez un événement pour voir son heure **Created**, son **Type** et son **Payload** complet en JSON, avec un bouton de copie.

## Lire les événements avec l’API

Les deux endpoints nécessitent une clé API **Full Access**.

### Lister les événements

[Lister les événements](/fr/docs/api-reference/events/list/) renvoie les événements du plus récent au plus ancien.

| Paramètre de requête | Description |
| --- | --- |
| `type` | Un type, ou plusieurs séparés par des virgules, par exemple `email.bounced,email.complained`. |
| `include_data` | `true` pour inclure `data` pour chaque événement. Par défaut : `false`, qui ne renvoie que `id`, `type` et `created_at`. |
| `page`, `limit` | Numéro et taille de page. `limit` va de 1 à 100 et vaut 100 par défaut. |
| `created_at.after`, `created_at.before` | Filtres de date. Voir [Filtrage et tri](/fr/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
}
```

Deux limites maintiennent la rapidité de cet endpoint :

- **Fenêtre par défaut.** Sans filtre `created_at`, la liste couvre les 2 derniers jours. Ajoutez `created_at.after` pour lire des événements plus anciens.
- **Profondeur de pagination.** Le décalage, `(page - 1) × limit`, ne peut pas dépasser 2 500. Les pages plus profondes renvoient `422` avec le code `events_offset_too_large`. Restreignez plutôt la requête avec `type` ou une plage `created_at` au lieu de paginer plus loin.

### Récupérer un événement

[Récupérer un événement](/fr/docs/api-reference/events/get/) renvoie un événement d’après son ID `evt_`, toujours avec `data`.

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

## Rapprocher les événements de webhook manqués

1. **Choisissez la période.** Notez quand votre endpoint a commencé à échouer ou quand le webhook a été désactivé, et quand le problème a été corrigé.

2. **Listez les événements.** Appelez `GET /v2/events` avec `created_at.after` et `created_at.before` réglés sur cette période, les valeurs `type` que gère votre webhook et `include_data=true`. Suivez `next_page_url` jusqu’à ce qu’il vaille `null`. Si vous rencontrez `events_offset_too_large`, découpez la période en plages plus courtes.

3. **Traitez ce que vous n’avez pas vu.** Ignorez les événements dont vous avez déjà enregistré l’ID comme traité, et traitez les autres avec le même code que votre webhook.

Pour les requêtes mises en file d’attente mais en échec, [Retry failed](/fr/docs/webhooks/retries-and-failures/#retry-failed-requests) sur le webhook est plus simple, tant que les échecs datent de moins de 7 jours.

## Conservation

Les événements suivent la durée de conservation des **Logs**, comme les logs de requêtes et les requêtes de webhook :

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Conservation des logs de requêtes | 7 jours | 30 jours | 30 jours | Flexible |

## Voir aussi

  - [Types d’événements](/fr/docs/webhooks/event-types/)
  - [API des événements](/fr/docs/api-reference/events/)

---
Source: https://emailit.com/fr/docs/logs/events/