# Événements API

> Consultez le flux d’événements derrière les webhooks : livraisons, rebonds, ouvertures et plus encore.

URL de base : `https://api.emailit.com/v2`. Authentifiez-vous avec `Authorization: Bearer <API key>`.

## Lister les événements — GET /events

> Listez les événements de votre espace de travail, du plus récent au plus ancien, par type et par date. Les événements sont les mêmes enregistrements que ceux que livrent les webhooks.

# Lister les événements

Renvoie les événements de votre espace de travail, du plus récent au plus ancien. Chaque livraison de webhook est construite à partir de l’un de ces événements : vous pouvez donc utiliser cet endpoint pour récupérer après coup les événements que votre endpoint a manqués. Nécessite une clé API de portée `full`.

`GET /events`

## Paramètres de requête

- `page` (integer): Numéro de page, à partir de `1`. Par défaut : `1`. Les pages situées au-delà de 2 500 événements (`(page - 1) × limit > 2500`) renvoient `422`.

- `limit` (integer): Nombre d’événements par page, de `1` à `100`. Par défaut : `100`.

- `type` (string): Type d’événement, ou liste de types séparés par des virgules, par exemple `email.delivered,email.bounced`. Consultez [Types d’événements](/fr/docs/webhooks/event-types/).

- `include_data` (boolean): Définissez `true` pour inclure le payload `data` de chaque événement. Par défaut : `false`, qui ne renvoie que `object`, `id`, `type` et `created_at`.

- `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

## Filtres et tri

Clés de filtre et de tri : voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/).

Sans filtre `created_at`, la liste ne couvre que les 2 derniers jours. Pour remonter plus loin, ajoutez-en un, par exemple `created_at.after=2026-09-01T00:00:00Z`. Les événements plus anciens restent disponibles tant que la [conservation des données](/fr/docs/data-retention/) de votre forfait les garde.

## Réponse

Renvoie `200 OK` avec les événements dans `data`, ainsi que `next_page_url` et `previous_page_url` (`null` aux deux extrémités). Les URL de page conservent `type`, `limit` et `include_data`.

Renvoie `422` avec `code: "events_offset_too_large"` lorsque la page est trop profonde. Réduisez la plage de dates ou les types plutôt que de paginer plus loin.

**Requête** `GET /events`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const events = await emailit.events.list({ type: 'email.delivered' });
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

events = client.events.list({"type": "email.delivered"})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$events = $emailit->events()->list(['type' => 'email.delivered']);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

events = client.events.list(type: "email.delivered")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

events, err := client.Events.List(&emailit.ListEventsRequest{Type: "email.delivered"})
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let events = emailit.events.list(Some(emailit::types::ListEventsParams { r#type: Some("email.delivered".into()), ..Default::default() })).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject events = emailit.events().list();
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var events = emailit.Events.List(new EventListOptions { Type = "email.delivered" });
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$events = Emailit::events()->list(['type' => 'email.delivered']);
```

**cURL**

```bash
curl -X GET "https://api.emailit.com/v2/events?type=email.delivered" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"
```

**200**

```json
{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered",
  "previous_page_url": null
}
```

**200 avec data**

```json
{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "data": {
        "object": {
          "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
          "object": "email",
          "from": "hello@acme.com",
          "to": "ada@example.com",
          "subject": "Your order has shipped",
          "status": "delivered",
          "meta": { "order_id": "1042" },
          "updated_at": "2026-10-01T10:02:14.307000+00:00",
          "created_at": "2026-10-01T10:02:11.583000+00:00"
        }
      },
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered&include_data=true",
  "previous_page_url": null
}
```

**422**

```json
{
  "error": "Page is too deep. Narrow the type or date filter, or open an earlier page.",
  "code": "events_offset_too_large"
}
```

---
Source: https://emailit.com/fr/docs/api-reference/events/list/

## Récupérer un événement — GET /events/{id}

> Récupérez un événement par son ID, avec le payload data complet qu’Emailit a envoyé, ou enverrait, à vos webhooks.

# Récupérer un événement

Renvoie un événement avec son payload `data` complet. L’`id` est la même valeur que celle que les webhooks envoient dans `event_id` : vous pouvez donc retrouver n’importe quel événement reçu. Nécessite une clé API de portée `full`.

`GET /events/:id`

## Paramètres de chemin

- `id` (string, obligatoire): ID de l’événement, par exemple `evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a`.

## Réponse

Renvoie `200 OK` avec l’événement : `object` (`event`), `id`, `type`, `data` et `created_at`. `data.object` a la même forme que dans le payload de webhook de ce type ; consultez la [référence des événements webhook](/fr/docs/webhooks/event-types/).

Renvoie `404` avec `error: "Event not found"` si l’ID n’existe pas dans votre espace de travail.

**Requête** `GET /events/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const event = await emailit.events.get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$event = $emailit->events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

event, err := client.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let event = emailit.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a").await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject event = emailit.events().get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var ev = emailit.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$event = Emailit::events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');
```

**cURL**

```bash
curl https://api.emailit.com/v2/events/evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "event",
  "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
      "object": "email",
      "from": "hello@acme.com",
      "to": "ada@example.com",
      "subject": "Your order has shipped",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T10:02:14.307000+00:00",
      "created_at": "2026-10-01T10:02:11.583000+00:00"
    }
  },
  "created_at": "2026-10-01T10:02:15.912000+00:00"
}
```

**404**

```json
{
  "error": "Event not found"
}
```

---
Source: https://emailit.com/fr/docs/api-reference/events/get/