# API Sendeo (version 1.0)

L'API Sendeo vous permet d'envoyer des emails transactionnels depuis votre site ou votre application,
et de gérer vos contacts, listes, templates, campagnes et webhooks.

C'est une API REST : des URL prévisibles, des corps de requête et de réponse en JSON (UTF-8) et les
codes HTTP standard.

| | |
|---|---|
| **URL de base** | `https://api.sendeo.io/v1` |
| **Authentification** | Clé API dans l'en-tête `Authorization: Bearer sk_…` |
| **Format** | JSON, dates ISO 8601 en UTC |

## Démarrage rapide

Trois étapes suffisent pour envoyer votre premier email.

1. **Vérifiez votre domaine d'envoi** dans *Paramètres › Domaines*, puis déclarez l'adresse
   d'expédition (par exemple `commandes@boutique.fr`).
2. **Créez une clé API** dans *Développeurs › Clés API* et gardez-la dans une variable
   d'environnement :

   ```bash
   export SENDEO_API_KEY="sk_…"
   ```

3. **Envoyez un email** :

   ```bash
   curl https://api.sendeo.io/v1/send \
     -H "Authorization: Bearer $SENDEO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "from": "Boutique <commandes@boutique.fr>",
       "to": ["client@example.com"],
       "subject": "Bienvenue !",
       "html": "<p>Merci pour votre inscription.</p>"
     }'
   ```

La réponse `202 Accepted` arrive immédiatement avec l'identifiant de chaque message ; l'envoi se fait
dans les secondes qui suivent. Suivez-le avec [`GET /v1/messages/{message_id}`](#tag/emails-transactionnels)
ou recevez ses événements grâce aux [webhooks](#description/webhooks).

## Authentification

Chaque requête porte une clé API de votre organisation :

```http
Authorization: Bearer sk_7Hk2Lp9vQ3xR7tY1uZ8wA5bC0dE4fG6h
```

- Les clés se créent et se révoquent dans *Développeurs › Clés API*. Une clé n'est affichée qu'une
  fois, à sa création.
- Une clé donne accès à toutes les données de son organisation : gardez-la côté serveur, jamais
  dans le code d'une page web ou d'une application mobile, ni dans un dépôt de code.
- Une clé absente, invalide ou révoquée renvoie `401 Unauthorized`.
- Une clé est créée en lecture seule ou en lecture et écriture. Une clé en lecture seule n'accepte
  que les requêtes `GET` (sinon `403 Forbidden`) et ne fonctionne pas sur le relais SMTP.

## Serveur MCP

Les offres Premium et Business peuvent connecter un assistant IA à Sendeo avec le protocole MCP, à
l'adresse `https://api.sendeo.io/mcp` et avec une clé API dans l'en-tête `Authorization`. L'assistant
consulte vos données, prépare des brouillons de campagne et envoie des emails unitaires, selon la
permission de la clé. Une campagne se lance toujours depuis l'application.

Avec Claude Code :

```bash
claude mcp add --transport http sendeo https://api.sendeo.io/mcp \
  --header "Authorization: Bearer $SENDEO_API_KEY"
```

Avec Cursor, dans `.cursor/mcp.json` :

```json
{
  "mcpServers": {
    "sendeo": {
      "url": "https://api.sendeo.io/mcp",
      "headers": { "Authorization": "Bearer sk_…" }
    }
  }
}
```

Une clé en lecture seule ne voit que les outils de lecture. Chaque appel d'outil compte dans la limite
de débit de la clé. Les descriptions des outils sont rédigées en anglais, la langue que les assistants
suivent le plus sûrement ; ils répondent à l'utilisateur dans sa langue.

| Domaine | Lecture | Écriture |
|---|---|---|
| Contacts | `list_contacts`, `get_contact` | `create_contact`, `update_contact`, `delete_contact` |
| Listes | `list_contact_lists` | `create_contact_list`, `update_contact_list`, `delete_contact_list` |
| Templates | `list_templates`, `get_template` | `create_template`, `update_template` |
| Campagnes | `list_campaigns`, `get_campaign` | `create_campaign_draft`, `update_campaign_draft` |
| Statistiques | `get_statistics` | |
| Emails | | `send_email` |

Les suppressions sont définitives et `send_email` envoie immédiatement : ces outils sont signalés
comme destructifs à l'assistant, pour qu'il demande confirmation selon les réglages de son client.
Un template créé par un assistant s'ouvre dans l'éditeur de code de Sendeo ; le HTML d'un template
de l'éditeur visuel ne se modifie que dans Sendeo. Un brouillon modifié n'est pas envoyé : le lancement
reste à faire depuis l'application.

## Skill pour agents IA

Le skill Sendeo indique à un agent IA comment utiliser Sendeo correctement : quel accès choisir, quelles
actions faire confirmer, comment lire le résultat d'un envoi. C'est un fichier
[`SKILL.md`](https://api.sendeo.io/v1/skill.md) au format Agent Skills. Il complète le serveur MCP et
fonctionne aussi sans lui, avec l'API REST. Il ne contient aucune clé : l'agent utilise celle du serveur
MCP ou la variable `SENDEO_API_KEY`.

Avec Claude Code :

```bash
mkdir -p ~/.claude/skills/sendeo
curl -fsS https://api.sendeo.io/v1/skill.md -o ~/.claude/skills/sendeo/SKILL.md
```

Pour un autre agent compatible, placez ce fichier dans un dossier `sendeo` de son répertoire de skills.

## Erreurs

Les erreurs utilisent les codes HTTP standard et un corps unique, dont le message lisible peut
être affiché tel quel :

```json
{ "detail": "L'adresse news@inconnu.fr n'est pas une adresse d'expédition validée." }
```

| Code | Signification |
|---|---|
| `400` | Requête mal formée (curseur de pagination invalide…) |
| `401` | Clé API absente, invalide ou révoquée |
| `403` | Action refusée : expéditeur non validé, organisation suspendue |
| `404` | Ressource introuvable (ou appartenant à une autre organisation) |
| `409` | Conflit : contact déjà existant, clé d'idempotence réutilisée avec un autre corps |
| `422` | Données invalides ; pour une erreur de format, `detail` est la liste des champs en cause |
| `429` | Trop de requêtes : voir [Limites de débit](#description/limites-de-débit) |
| `5xx` | Erreur de notre côté : réessayez plus tard, avec la même clé d'idempotence |

## Limites de débit

Chaque clé peut faire un nombre de requêtes par minute qui dépend de votre offre :

| Offre | Requêtes par minute et par clé |
|---|---|
| Gratuit | 60 |
| Starter | 300 |
| Essentiel | 600 |
| Premium | 1 200 |
| Business | 3 000 |

Chaque réponse indique où vous en êtes :

| En-tête | Description |
|---|---|
| `RateLimit-Limit` | Requêtes autorisées par minute |
| `RateLimit-Remaining` | Requêtes restantes dans la minute en cours |
| `RateLimit-Reset` | Secondes avant la remise à zéro du compteur |

Au-delà, l'API répond `429 Too Many Requests` avec l'en-tête `Retry-After` (en secondes). Pour envoyer
le même email à beaucoup de destinataires, regroupez-les : `POST /v1/send` en accepte 50 par requête.

## Idempotence

Un réseau peut couper après l'envoi d'une requête mais avant la réception de la réponse. Pour pouvoir
réessayer sans risque d'envoyer deux fois le même email ou de créer deux fois la même ressource,
ajoutez l'en-tête `Idempotency-Key` à `POST /v1/send` ou à toute création (`POST /v1/contacts`,
`/v1/lists`, `/v1/templates`, `/v1/campaigns`, `/v1/webhooks`, `/v1/events`, `/v1/validate`), avec
une valeur propre à l'opération (par exemple le numéro de la commande) :

```http
Idempotency-Key: commande-4521
```

- Rejouée avec la même clé pendant **24 heures**, la requête renvoie la réponse de la première, avec
  l'en-tête `Idempotent-Replayed: true`, sans rien envoyer de plus.
- Réutilisée avec un corps différent, ou sur une autre route, elle est refusée (`409 Conflict`).
- Si la première requête a échoué (`4xx`), la clé redevient libre : corrigez et renvoyez.

## Pagination

Les listes sont paginées par curseur. La réponse contient les éléments de la page, le nombre total
de résultats et le curseur de la page suivante (`null` sur la dernière page) :

```json
{ "items": [ … ], "total": 1284, "next_cursor": "MjU=" }
```

Passez ce curseur en paramètre `cursor` pour obtenir la page suivante ; `limit` fixe la taille de
page (100 au plus).

## Personnalisation

Le sujet et le contenu d'un email (ou d'un template) acceptent des variables :

| Variable | Valeur |
|---|---|
| `{{ var.numero }}` | Valeur `numero` de `variables`, dans la requête ou propre au destinataire |
| `{{ contact.first_name }}`, `{{ contact.last_name }}`, `{{ contact.email }}` | Champs du contact, si le destinataire en est un ; sinon `first_name` reprend le `name` donné |
| `{{ contact.attributes.ville }}` | Champ personnalisé du contact |
| `{{ org.name }}` | Nom de votre organisation |

Une valeur par défaut évite un trou quand la donnée manque :
`Bonjour {{ contact.first_name | default('à vous') }}`.

## Webhooks

Les webhooks préviennent votre application en temps réel de ce qui arrive à vos emails. Créez-les
dans *Développeurs › Webhooks* ou avec [`POST /v1/webhooks`](#tag/webhooks).

### Événements

| Événement | Envoyé quand |
|---|---|
| `message.sent` | L'email a quitté nos serveurs |
| `message.delivered` | La messagerie du destinataire l'a accepté |
| `message.opened` | Le destinataire l'a ouvert (estimation : certaines messageries ouvrent automatiquement) |
| `message.clicked` | Un lien suivi a été cliqué |
| `message.bounced` | L'adresse a refusé l'email (`bounceType` : `Permanent` ou `Transient`) |
| `message.complained` | Le destinataire l'a signalé comme spam |
| `message.failed` | L'email n'est pas parti (adresse bloquée, refus définitif) |
| `contact.unsubscribed` | Le destinataire s'est désinscrit |

Les ouvertures et clics des passerelles de sécurité (scanners de liens) ne sont pas transmis.

### Requête envoyée

Sendeo envoie un `POST` en JSON à votre URL :

```json
{
  "id": "2f9d8c7b-6a5e-4d3c-9b2a-1f0e9d8c7b6a",
  "type": "message.delivered",
  "created_at": "2026-10-08T14:32:08Z",
  "data": {
    "message_id": "6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70",
    "campaign_id": null,
    "email": "client@example.com",
    "subject": "Votre commande n° 4521",
    "tags": ["commande"]
  }
}
```

Répondez par un code `2xx` en moins de 10 secondes, puis traitez l'événement de façon asynchrone.
Sans réponse `2xx`, l'événement est renvoyé 7 fois en environ 3 jours (après 1 min, 10 min, 1 h, 4 h,
12 h, 24 h et 30 h) ; après 3 jours d'échecs consécutifs, le webhook est désactivé. Un même
événement peut arriver deux fois : utilisez `id` pour ignorer les doublons.

### Vérifier la signature

Chaque requête porte l'en-tête `Sendeo-Signature` :

```http
Sendeo-Signature: t=1791470000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

`v1` est le HMAC-SHA256, en hexadécimal, de la chaîne `{t}.{corps brut de la requête}` avec le secret
du webhook (`whsec_…`, affiché à sa création). Vérifiez-la sur le corps **brut**, avant de le décoder,
et refusez les requêtes de plus de 5 minutes.

**Python**

```python
import hashlib
import hmac
import time


def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    recent = abs(time.time() - int(parts["t"])) < 300
    return recent and hmac.compare_digest(expected, parts["v1"])
```

**Node.js**

```javascript
import crypto from 'node:crypto'

export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(',').map((item) => item.split('=')))
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  const recent = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  const valid = parts.v1?.length === expected.length
  return recent && valid && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}
```

**PHP**

```php
function verify(string $secret, string $header, string $body): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $body, $secret);
    $recent = abs(time() - (int) $parts['t']) < 300;
    return $recent && hash_equals($expected, $parts['v1']);
}
```

## Emails transactionnels

Envoyez un email à un ou plusieurs destinataires (un message chacun), puis suivez son statut et ses événements. Le journal est conservé 30 jours.

### Envoyer un email transactionnel

`POST /v1/send`

Un message par destinataire (1 à 50), envoyé en arrière-plan : la réponse arrive avant
l'envoi. Contenu : `template_id`, ou `html` / `text` avec `subject`. Les variables
s'écrivent `{{ var.nom }}` ; si le destinataire est un contact, `{{ contact.first_name }}`
et ses champs sont aussi disponibles. Une adresse en bounce définitif ou en plainte n'est
pas écrite : son message est renvoyé en `failed`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [SendRequest](#sendrequest)

```json
{
  "from": "Boutique <commandes@boutique.fr>",
  "to": [
    {
      "email": "client@example.com",
      "name": "Jeanne"
    }
  ],
  "subject": "Votre commande n° {{ var.numero }}",
  "html": "<p>Bonjour {{ contact.first_name }}, commande de {{ var.total }} validée.</p>",
  "variables": {
    "numero": "4521",
    "total": "59,90 €"
  },
  "tags": [
    "commande"
  ]
}
```

**Réponse `202`** ([SendResponse](#sendresponse)) — Demande acceptée, traitée en arrière-plan.

```json
{
  "messages": [
    {
      "id": "6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70",
      "email": "client@example.com",
      "status": "queued",
      "error": null
    }
  ]
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/send" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Idempotency-Key: commande-4521" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Boutique <commandes@boutique.fr>",
    "to": [
      {
        "email": "client@example.com",
        "name": "Jeanne"
      }
    ],
    "subject": "Votre commande n° {{ var.numero }}",
    "html": "<p>Bonjour {{ contact.first_name }}, commande de {{ var.total }} validée.</p>",
    "variables": {
      "numero": "4521",
      "total": "59,90 €"
    },
    "tags": [
      "commande"
    ]
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
        "Idempotency-Key": "commande-4521",
    },
    json={
        "from": "Boutique <commandes@boutique.fr>",
        "to": [
            {
                "email": "client@example.com",
                "name": "Jeanne",
            },
        ],
        "subject": "Votre commande n° {{ var.numero }}",
        "html": "<p>Bonjour {{ contact.first_name }}, commande de {{ var.total }} validée.</p>",
        "variables": {
            "numero": "4521",
            "total": "59,90 €",
        },
        "tags": [
            "commande",
        ],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/send');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: commande-4521',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "from": "Boutique <commandes@boutique.fr>",
    "to": [
        {
            "email": "client@example.com",
            "name": "Jeanne"
        }
    ],
    "subject": "Votre commande n° {{ var.numero }}",
    "html": "<p>Bonjour {{ contact.first_name }}, commande de {{ var.total }} validée.</p>",
    "variables": {
        "numero": "4521",
        "total": "59,90 €"
    },
    "tags": [
        "commande"
    ]
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Idempotency-Key': 'commande-4521',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "from": "Boutique <commandes@boutique.fr>",
    "to": [
      {
        "email": "client@example.com",
        "name": "Jeanne"
      }
    ],
    "subject": "Votre commande n° {{ var.numero }}",
    "html": "<p>Bonjour {{ contact.first_name }}, commande de {{ var.total }} validée.</p>",
    "variables": {
      "numero": "4521",
      "total": "59,90 €"
    },
    "tags": [
      "commande"
    ]
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Journal des emails transactionnels (30 jours)

`GET /v1/messages`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `search` | requête | string ou null | non |  |
| `status` | requête | [RecipientStatus](#recipientstatus) ou null | non |  |
| `cursor` | requête | string ou null | non |  |
| `limit` | requête | integer | non | Par défaut : `25`. |

**Réponse `200`** ([MessagePage](#messagepage)) — Succès.

```json
{
  "items": [
    {
      "id": "6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70",
      "to": "client@example.com",
      "from_email": "commandes@boutique.fr",
      "from_name": "Boutique",
      "subject": "Votre commande n° 4521",
      "status": "delivered",
      "tags": [
        "commande"
      ],
      "campaign_id": null,
      "error": null,
      "created_at": "2026-10-08T14:32:05Z",
      "sent_at": "2026-10-08T14:32:06Z"
    }
  ],
  "next_cursor": "MjU=",
  "total": 42
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/messages?status=bounced" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/messages?status=bounced",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/messages?status=bounced');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/messages?status=bounced', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Statut et événements d'un message

`GET /v1/messages/{message_id}`

Tout message de l'organisation, transactionnel ou de campagne (identifiant reçu dans
la réponse de `/v1/send` ou dans un webhook).

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `message_id` | chemin | string (uuid) | oui |  |

**Réponse `200`** ([MessageDetailOut](#messagedetailout)) — Succès.

```json
{
  "id": "6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70",
  "to": "client@example.com",
  "from_email": "commandes@boutique.fr",
  "from_name": "Boutique",
  "subject": "Votre commande n° 4521",
  "status": "delivered",
  "tags": [
    "commande"
  ],
  "campaign_id": null,
  "error": null,
  "created_at": "2026-10-08T14:32:05Z",
  "sent_at": "2026-10-08T14:32:06Z",
  "events": [
    {
      "type": "queued",
      "occurred_at": "2026-10-08T14:32:05Z",
      "detail": null
    },
    {
      "type": "sent",
      "occurred_at": "2026-10-08T14:32:06Z",
      "detail": null
    },
    {
      "type": "delivered",
      "occurred_at": "2026-10-08T14:32:08Z",
      "detail": null
    }
  ]
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/messages/6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/messages/6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/messages/6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/messages/6f1c2e4a-3b7d-4c8e-9a10-2b3c4d5e6f70', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Contacts

Votre base de contacts, identifiés par leur adresse email. Une adresse de la liste de suppression (désinscription, bounce, plainte) ne peut pas être ajoutée.

### Lister les contacts

`GET /v1/contacts`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `search` | requête | string ou null | non |  |
| `status` | requête | [ContactStatus](#contactstatus) ou null | non |  |
| `list_id` | requête | string (uuid) ou null | non |  |
| `cursor` | requête | string ou null | non |  |
| `limit` | requête | integer | non | Par défaut : `25`. |

**Réponse `200`** ([ContactPage](#contactpage)) — Succès.

```json
{
  "items": [
    {
      "id": "0d9b6c1e-52a4-4f0b-8e3a-7c1d2e3f4a5b",
      "email": "jeanne.martin@example.com",
      "first_name": "Jeanne",
      "last_name": "Martin",
      "status": "subscribed",
      "lists": [
        {
          "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
          "name": "Clients"
        }
      ],
      "attributes": {
        "ville": "Lyon"
      },
      "created_at": "2026-10-08T14:32:05Z",
      "updated_at": "2026-10-08T14:32:05Z",
      "last_activity_at": null
    }
  ],
  "next_cursor": "MjU=",
  "total": 1284
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/contacts?limit=100" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/contacts?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts?limit=100');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts?limit=100', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Créer un contact

`POST /v1/contacts`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [ContactCreate](#contactcreate)

```json
{
  "email": "jeanne.martin@example.com",
  "first_name": "Jeanne",
  "last_name": "Martin",
  "list_ids": [
    "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
  ],
  "attributes": {
    "ville": "Lyon"
  }
}
```

**Réponse `201`** ([ContactOut](#contactout)) — Ressource créée.

```json
{
  "id": "0d9b6c1e-52a4-4f0b-8e3a-7c1d2e3f4a5b",
  "email": "jeanne.martin@example.com",
  "first_name": "Jeanne",
  "last_name": "Martin",
  "status": "subscribed",
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "attributes": {
    "ville": "Lyon"
  },
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "last_activity_at": null
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/contacts" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jeanne.martin@example.com",
    "first_name": "Jeanne",
    "last_name": "Martin",
    "list_ids": [
      "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ],
    "attributes": {
      "ville": "Lyon"
    }
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "email": "jeanne.martin@example.com",
        "first_name": "Jeanne",
        "last_name": "Martin",
        "list_ids": [
            "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
        ],
        "attributes": {
            "ville": "Lyon",
        },
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "email": "jeanne.martin@example.com",
    "first_name": "Jeanne",
    "last_name": "Martin",
    "list_ids": [
        "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ],
    "attributes": {
        "ville": "Lyon"
    }
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "jeanne.martin@example.com",
    "first_name": "Jeanne",
    "last_name": "Martin",
    "list_ids": [
      "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ],
    "attributes": {
      "ville": "Lyon"
    }
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Importer un fichier CSV (asynchrone)

`POST /v1/contacts/import`

Fichier CSV (50 Mo au plus) dont les colonnes sont reconnues par leur en-tête : `email`
(obligatoire), `prenom`, `nom`, ou la clé d'un champ personnalisé. Suivez l'avancement avec
`GET /v1/contacts/imports/{import_id}`.

**Corps de la requête** (`multipart/form-data`) : [Body_import_contacts](#body_import_contacts)

**Réponse `202`** ([ImportJobOut](#importjobout)) — Demande acceptée, traitée en arrière-plan.

```json
{
  "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
  "file_name": "clients.csv",
  "status": "processing",
  "columns": [
    "email",
    "prenom",
    "nom"
  ],
  "sample_rows": [
    [
      "jeanne.martin@example.com",
      "Jeanne",
      "Martin"
    ]
  ],
  "suggested_mapping": {
    "email": "email",
    "prenom": "first_name",
    "nom": "last_name"
  },
  "list_id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
  "update_existing": true,
  "total_rows": 1284,
  "processed_rows": 0,
  "created": 0,
  "updated": 0,
  "skipped": 0,
  "risky": 0,
  "errors": [],
  "created_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/contacts/import" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/contacts/import",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts/import');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts/import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Suivre un import

`GET /v1/contacts/imports/{import_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `import_id` | chemin | string (uuid) | oui |  |

**Réponse `200`** ([ImportJobOut](#importjobout)) — Succès.

```json
{
  "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
  "file_name": "clients.csv",
  "status": "completed",
  "columns": [
    "email",
    "prenom",
    "nom"
  ],
  "sample_rows": [
    [
      "jeanne.martin@example.com",
      "Jeanne",
      "Martin"
    ]
  ],
  "suggested_mapping": {
    "email": "email",
    "prenom": "first_name",
    "nom": "last_name"
  },
  "list_id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
  "update_existing": true,
  "total_rows": 1284,
  "processed_rows": 1284,
  "created": 1270,
  "updated": 0,
  "skipped": 0,
  "risky": 0,
  "errors": [],
  "created_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/contacts/imports/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/contacts/imports/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts/imports/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts/imports/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Lire un contact

`GET /v1/contacts/{email}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `email` | chemin | string | oui |  |

**Réponse `200`** ([ContactOut](#contactout)) — Succès.

```json
{
  "id": "0d9b6c1e-52a4-4f0b-8e3a-7c1d2e3f4a5b",
  "email": "jeanne.martin@example.com",
  "first_name": "Jeanne",
  "last_name": "Martin",
  "status": "subscribed",
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "attributes": {
    "ville": "Lyon"
  },
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "last_activity_at": null
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Modifier un contact

`PATCH /v1/contacts/{email}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `email` | chemin | string | oui |  |

**Corps de la requête** (`application/json`) : [ContactUpdate](#contactupdate)

```json
{
  "attributes": {
    "ville": "Paris"
  }
}
```

**Réponse `200`** ([ContactOut](#contactout)) — Succès.

```json
{
  "id": "0d9b6c1e-52a4-4f0b-8e3a-7c1d2e3f4a5b",
  "email": "jeanne.martin@example.com",
  "first_name": "Jeanne",
  "last_name": "Martin",
  "status": "subscribed",
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "attributes": {
    "ville": "Paris"
  },
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "last_activity_at": null
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X PATCH "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "ville": "Paris"
    }
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.patch(
    "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "attributes": {
            "ville": "Paris",
        },
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "attributes": {
        "ville": "Paris"
    }
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "attributes": {
      "ville": "Paris"
    }
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Supprimer un contact

`DELETE /v1/contacts/{email}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `email` | chemin | string | oui |  |

**Réponse `204`** — Ressource supprimée (pas de contenu).

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X DELETE "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.delete(
    "https://api.sendeo.io/v1/contacts/jeanne.martin@example.com",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/contacts/jeanne.martin@example.com', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
```

## Listes

Les listes regroupent des contacts destinataires de campagnes.

### Lister les listes de contacts

`GET /v1/lists`

**Réponse `200`** (liste de [ContactListOut](#contactlistout)) — Succès.

```json
[
  {
    "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
    "name": "Clients",
    "description": "Clients ayant passé au moins une commande",
    "contact_count": 1284,
    "created_at": "2026-10-08T14:32:05Z"
  }
]
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/lists" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/lists",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/lists');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/lists', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Créer une liste

`POST /v1/lists`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [ContactListCreate](#contactlistcreate)

```json
{
  "name": "Clients",
  "description": "Clients ayant passé au moins une commande"
}
```

**Réponse `201`** ([ContactListOut](#contactlistout)) — Ressource créée.

```json
{
  "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
  "name": "Clients",
  "description": "Clients ayant passé au moins une commande",
  "contact_count": 1284,
  "created_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/lists" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clients",
    "description": "Clients ayant passé au moins une commande"
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/lists",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "name": "Clients",
        "description": "Clients ayant passé au moins une commande",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/lists');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "name": "Clients",
    "description": "Clients ayant passé au moins une commande"
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/lists', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Clients",
    "description": "Clients ayant passé au moins une commande"
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Renommer une liste

`PATCH /v1/lists/{list_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `list_id` | chemin | string (uuid) | oui |  |

**Corps de la requête** (`application/json`) : [ContactListUpdate](#contactlistupdate)

```json
{
  "name": "Clients fidèles"
}
```

**Réponse `200`** ([ContactListOut](#contactlistout)) — Succès.

```json
{
  "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
  "name": "Clients fidèles",
  "description": "Clients ayant passé au moins une commande",
  "contact_count": 1284,
  "created_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X PATCH "https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clients fidèles"
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.patch(
    "https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "name": "Clients fidèles",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "name": "Clients fidèles"
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Clients fidèles"
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Supprimer une liste

`DELETE /v1/lists/{list_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `list_id` | chemin | string (uuid) | oui |  |

**Réponse `204`** — Ressource supprimée (pas de contenu).

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X DELETE "https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.delete(
    "https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/lists/5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
```

## Validation d'adresses

Vérifiez des adresses avant de les importer ou de leur écrire : moins de bounces, une meilleure réputation. Crédits mensuels selon votre offre.

### Valider des adresses

`POST /v1/validate`

De 1 à 100 adresses, chacune avec un verdict : `valid`, `risky` (jetable, boîte de rôle
comme `contact@`, domaine qui accepte tout) ou `invalid` (syntaxe, domaine sans serveur de
messagerie, boîte inexistante). Une adresse consomme un crédit de validation du mois.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [ValidateRequest](#validaterequest)

```json
{
  "emails": [
    "jeanne.martin@example.com",
    "contact@boutique.fr",
    "paul@boutque.fr"
  ]
}
```

**Réponse `200`** ([ValidateResponse](#validateresponse)) — Succès.

```json
{
  "results": [
    {
      "email": "jeanne.martin@example.com",
      "verdict": "valid",
      "reason": "ok"
    },
    {
      "email": "contact@boutique.fr",
      "verdict": "risky",
      "reason": "role"
    },
    {
      "email": "paul@boutque.fr",
      "verdict": "invalid",
      "reason": "no_mx"
    }
  ],
  "credits_remaining": 1997
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/validate" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "jeanne.martin@example.com",
      "contact@boutique.fr",
      "paul@boutque.fr"
    ]
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/validate",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "emails": [
            "jeanne.martin@example.com",
            "contact@boutique.fr",
            "paul@boutque.fr",
        ],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/validate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "emails": [
        "jeanne.martin@example.com",
        "contact@boutique.fr",
        "paul@boutque.fr"
    ]
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/validate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "emails": [
      "jeanne.martin@example.com",
      "contact@boutique.fr",
      "paul@boutque.fr"
    ]
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Templates

Contenus réutilisables : utilisez leur identifiant comme `template_id` dans `POST /v1/send` ou dans une campagne.

### Lister les templates

`GET /v1/templates`

**Réponse `200`** (liste de [TemplateOut](#templateout)) — Succès.

```json
[
  {
    "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "name": "Confirmation de commande",
    "category_id": null,
    "editor": "code",
    "subject": "Commande n° {{ var.numero }} confirmée",
    "preheader": "",
    "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>",
    "created_at": "2026-10-08T14:32:05Z",
    "updated_at": "2026-10-08T14:32:05Z"
  }
]
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/templates" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/templates",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/templates');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/templates', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Créer un template

`POST /v1/templates`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [ApiTemplateCreate](#apitemplatecreate)

```json
{
  "name": "Confirmation de commande",
  "subject": "Commande n° {{ var.numero }} confirmée",
  "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>"
}
```

**Réponse `201`** ([TemplateSaved](#templatesaved)) — Ressource créée.

```json
{
  "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
  "name": "Confirmation de commande",
  "category_id": null,
  "editor": "code",
  "subject": "Commande n° {{ var.numero }} confirmée",
  "preheader": "",
  "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>",
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "unknown_variables": []
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/templates" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Confirmation de commande",
    "subject": "Commande n° {{ var.numero }} confirmée",
    "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>"
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/templates",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "name": "Confirmation de commande",
        "subject": "Commande n° {{ var.numero }} confirmée",
        "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/templates');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "name": "Confirmation de commande",
    "subject": "Commande n° {{ var.numero }} confirmée",
    "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>"
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/templates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Confirmation de commande",
    "subject": "Commande n° {{ var.numero }} confirmée",
    "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>"
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Lire un template

`GET /v1/templates/{template_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `template_id` | chemin | string (uuid) | oui |  |

**Réponse `200`** ([TemplateOut](#templateout)) — Succès.

```json
{
  "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
  "name": "Confirmation de commande",
  "category_id": null,
  "editor": "code",
  "subject": "Commande n° {{ var.numero }} confirmée",
  "preheader": "",
  "html": "<html><body><p>Bonjour {{ contact.first_name | default('') }},</p></body></html>",
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Modifier un template

`PATCH /v1/templates/{template_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `template_id` | chemin | string (uuid) | oui |  |

**Corps de la requête** (`application/json`) : [ApiTemplateUpdate](#apitemplateupdate)

**Réponse `200`** ([TemplateSaved](#templatesaved)) — Succès.

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X PATCH "https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.patch(
    "https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/templates/0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Campagnes

Emails marketing envoyés à une ou plusieurs listes : créez un brouillon, puis lancez-le tout de suite ou planifiez-le.

### Lister les campagnes

`GET /v1/campaigns`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `search` | requête | string ou null | non |  |
| `status` | requête | [CampaignStatus](#campaignstatus) ou null | non |  |
| `cursor` | requête | string ou null | non |  |
| `limit` | requête | integer | non | Par défaut : `20`. |

**Réponse `200`** ([CampaignPage](#campaignpage)) — Succès.

```json
{
  "items": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "name": "Soldes d'hiver",
      "subject": "Jusqu'à -50 % ce week-end",
      "preheader": "",
      "from_name": "Boutique",
      "from_email": "news@boutique.fr",
      "reply_to": null,
      "template": {
        "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
        "name": "Soldes"
      },
      "lists": [
        {
          "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
          "name": "Clients"
        }
      ],
      "segments": [],
      "recipient_count": 1284,
      "status": "scheduled",
      "tracking_enabled": true,
      "ab_test": null,
      "scheduled_at": "2026-12-01T08:00:00Z",
      "sent_at": null,
      "finished_at": null,
      "error": null,
      "created_at": "2026-10-08T14:32:05Z",
      "updated_at": "2026-10-08T14:32:05Z",
      "stats": {
        "recipients": 1284,
        "sent": 1280,
        "delivered": 1262,
        "opened": 611,
        "clicked": 148,
        "bounced": 18,
        "complained": 1,
        "unsubscribed": 6,
        "failed": 4,
        "queued": 0
      }
    }
  ],
  "next_cursor": "MjU=",
  "total": 37
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/campaigns?status=sent" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/campaigns?status=sent",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/campaigns?status=sent');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/campaigns?status=sent', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Créer une campagne (brouillon)

`POST /v1/campaigns`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [CampaignCreate](#campaigncreate)

```json
{
  "name": "Soldes d'hiver",
  "subject": "Jusqu'à -50 % ce week-end",
  "from_name": "Boutique",
  "from_email": "news@boutique.fr",
  "template_id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
  "list_ids": [
    "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
  ]
}
```

**Réponse `201`** ([CampaignOut](#campaignout)) — Ressource créée.

```json
{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Soldes d'hiver",
  "subject": "Jusqu'à -50 % ce week-end",
  "preheader": "",
  "from_name": "Boutique",
  "from_email": "news@boutique.fr",
  "reply_to": null,
  "template": {
    "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "name": "Soldes"
  },
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "segments": [],
  "recipient_count": 1284,
  "status": "draft",
  "tracking_enabled": true,
  "ab_test": null,
  "scheduled_at": null,
  "sent_at": null,
  "finished_at": null,
  "error": null,
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "stats": {
    "recipients": 1284,
    "sent": 1280,
    "delivered": 1262,
    "opened": 611,
    "clicked": 148,
    "bounced": 18,
    "complained": 1,
    "unsubscribed": 6,
    "failed": 4,
    "queued": 0
  }
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/campaigns" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soldes d'hiver",
    "subject": "Jusqu'à -50 % ce week-end",
    "from_name": "Boutique",
    "from_email": "news@boutique.fr",
    "template_id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "list_ids": [
      "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ]
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/campaigns",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "name": "Soldes d'hiver",
        "subject": "Jusqu'à -50 % ce week-end",
        "from_name": "Boutique",
        "from_email": "news@boutique.fr",
        "template_id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
        "list_ids": [
            "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
        ],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/campaigns');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "name": "Soldes d'hiver",
    "subject": "Jusqu'à -50 % ce week-end",
    "from_name": "Boutique",
    "from_email": "news@boutique.fr",
    "template_id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "list_ids": [
        "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ]
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Soldes d'hiver",
    "subject": "Jusqu'à -50 % ce week-end",
    "from_name": "Boutique",
    "from_email": "news@boutique.fr",
    "template_id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "list_ids": [
      "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13"
    ]
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Lire une campagne

`GET /v1/campaigns/{campaign_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `campaign_id` | chemin | string (uuid) | oui |  |

**Réponse `200`** ([CampaignOut](#campaignout)) — Succès.

```json
{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Soldes d'hiver",
  "subject": "Jusqu'à -50 % ce week-end",
  "preheader": "",
  "from_name": "Boutique",
  "from_email": "news@boutique.fr",
  "reply_to": null,
  "template": {
    "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "name": "Soldes"
  },
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "segments": [],
  "recipient_count": 1284,
  "status": "scheduled",
  "tracking_enabled": true,
  "ab_test": null,
  "scheduled_at": "2026-12-01T08:00:00Z",
  "sent_at": null,
  "finished_at": null,
  "error": null,
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "stats": {
    "recipients": 1284,
    "sent": 1280,
    "delivered": 1262,
    "opened": 611,
    "clicked": 148,
    "bounced": 18,
    "complained": 1,
    "unsubscribed": 6,
    "failed": 4,
    "queued": 0
  }
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Modifier une campagne (brouillon ou planifiée)

`PATCH /v1/campaigns/{campaign_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `campaign_id` | chemin | string (uuid) | oui |  |

**Corps de la requête** (`application/json`) : [CampaignUpdate](#campaignupdate)

**Réponse `200`** ([CampaignOut](#campaignout)) — Succès.

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X PATCH "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.patch(
    "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Lancer ou planifier une campagne

`POST /v1/campaigns/{campaign_id}/send`

Sans `scheduled_at` (ou avec une date passée) : envoi immédiat. Avec
`send_time_optimization`, chaque destinataire reçoit l'email dans les 24 h, à l'heure où il
clique le plus d'après son historique (sinon celle de vos contacts, sinon au lancement).
Les contrôles avant envoi (expéditeur vérifié, objet, contenu, destinataires) s'appliquent
comme dans l'application.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `campaign_id` | chemin | string (uuid) | oui |  |

**Corps de la requête** (`application/json`) : [CampaignSchedule](#campaignschedule) ou null

```json
{
  "scheduled_at": "2026-12-01T09:00:00+01:00"
}
```

**Réponse `200`** ([CampaignOut](#campaignout)) — Succès.

```json
{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Soldes d'hiver",
  "subject": "Jusqu'à -50 % ce week-end",
  "preheader": "",
  "from_name": "Boutique",
  "from_email": "news@boutique.fr",
  "reply_to": null,
  "template": {
    "id": "0b0e7d3c-6c43-4bd4-9a35-2f8a5f3e1c11",
    "name": "Soldes"
  },
  "lists": [
    {
      "id": "5f0c2b1e-8f7a-4d3e-9c1b-2a6d4e8f0a13",
      "name": "Clients"
    }
  ],
  "segments": [],
  "recipient_count": 1284,
  "status": "scheduled",
  "tracking_enabled": true,
  "ab_test": null,
  "scheduled_at": "2026-12-01T08:00:00Z",
  "sent_at": null,
  "finished_at": null,
  "error": null,
  "created_at": "2026-10-08T14:32:05Z",
  "updated_at": "2026-10-08T14:32:05Z",
  "stats": {
    "recipients": 1284,
    "sent": 1280,
    "delivered": 1262,
    "opened": 611,
    "clicked": 148,
    "bounced": 18,
    "complained": 1,
    "unsubscribed": 6,
    "failed": 4,
    "queued": 0
  }
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/send" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-12-01T09:00:00+01:00"
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/send",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "scheduled_at": "2026-12-01T09:00:00+01:00",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/send');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "scheduled_at": "2026-12-01T09:00:00+01:00"
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/campaigns/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "scheduled_at": "2026-12-01T09:00:00+01:00"
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Statistiques

Chiffres d'envoi agrégés de votre organisation sur une période.

### Lire les statistiques d'envoi

`GET /v1/stats`

Totaux, courbe quotidienne et meilleures campagnes sur 7, 30 ou 90 jours. `kind` limite
le calcul aux emails marketing ou transactionnels.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `period` | requête | `7d` / `30d` / `90d` | non | Par défaut : `"30d"`. |
| `kind` | requête | [MessageKind](#messagekind) ou null | non |  |

**Réponse `200`** ([StatsOut](#statsout)) — Succès.

```json
{
  "period": "30d",
  "totals": {
    "recipients": 1284,
    "sent": 1280,
    "delivered": 1262,
    "opened": 611,
    "clicked": 148,
    "bounced": 18,
    "complained": 1,
    "unsubscribed": 6,
    "failed": 4,
    "queued": 0
  },
  "series": [
    {
      "date": "2026-10-08",
      "sent": 4210,
      "delivered": 4180,
      "opened": 1605,
      "clicked": 312,
      "bounced": 30
    }
  ],
  "top_campaigns": [],
  "breakdown": null
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/stats?period=30d" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/stats?period=30d",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/stats?period=30d');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/stats?period=30d', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Événements

Signalez ce que font vos contacts sur votre site (commande, panier abandonné…) : un événement fait entrer le contact dans les scénarios qui l'attendent, ou le fait sortir de ceux dont c'est l'objectif.

### Signaler un événement (déclencheur de scénario)

`POST /v1/events`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [EventIn](#eventin)

```json
{
  "email": "jeanne.martin@example.com",
  "event": "panier_abandonne",
  "data": {
    "panier_url": "https://boutique.fr/panier/4521",
    "total": "59,90 €"
  }
}
```

**Réponse `202`** ([EventOut](#eventout)) — Demande acceptée, traitée en arrière-plan.

```json
{
  "accepted": true,
  "automations_entered": 1
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/events" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jeanne.martin@example.com",
    "event": "panier_abandonne",
    "data": {
      "panier_url": "https://boutique.fr/panier/4521",
      "total": "59,90 €"
    }
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/events",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "email": "jeanne.martin@example.com",
        "event": "panier_abandonne",
        "data": {
            "panier_url": "https://boutique.fr/panier/4521",
            "total": "59,90 €",
        },
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/events');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "email": "jeanne.martin@example.com",
    "event": "panier_abandonne",
    "data": {
        "panier_url": "https://boutique.fr/panier/4521",
        "total": "59,90 €"
    }
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "jeanne.martin@example.com",
    "event": "panier_abandonne",
    "data": {
      "panier_url": "https://boutique.fr/panier/4521",
      "total": "59,90 €"
    }
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

## Webhooks

Abonnez une URL de votre application aux événements de vos emails (voir [Webhooks](#description/webhooks) pour le format et la signature).

### Lister les webhooks

`GET /v1/webhooks`

**Réponse `200`** (liste de [WebhookOut](#webhookout)) — Succès.

```json
[
  {
    "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "url": "https://boutique.fr/webhooks/sendeo",
    "events": [
      "message.delivered",
      "message.bounced",
      "message.complained"
    ],
    "enabled": true,
    "disabled_reason": null,
    "secret_prefix": "whsec_Hk2Lp",
    "last_delivery_status": "success",
    "created_at": "2026-10-08T14:32:05Z"
  }
]
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl "https://api.sendeo.io/v1/webhooks" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.get(
    "https://api.sendeo.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/webhooks');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/webhooks', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### S'abonner à des événements

`POST /v1/webhooks`

Le `secret` n'est renvoyé qu'ici : il sert à vérifier l'en-tête `Sendeo-Signature`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `Idempotency-Key` | en-tête | string ou null | non | Identifiant unique de l'opération (ex. numéro de commande). Rejouée avec la même clé pendant 24 h, la requête renvoie la première réponse sans rien renvoyer ; avec un corps différent, elle est refusée (409). |

**Corps de la requête** (`application/json`) : [WebhookCreate](#webhookcreate)

```json
{
  "url": "https://boutique.fr/webhooks/sendeo",
  "events": [
    "message.delivered",
    "message.bounced",
    "message.complained"
  ]
}
```

**Réponse `201`** ([WebhookCreated](#webhookcreated)) — Ressource créée.

```json
{
  "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "url": "https://boutique.fr/webhooks/sendeo",
  "events": [
    "message.delivered",
    "message.bounced",
    "message.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "secret_prefix": "whsec_Hk2Lp",
  "last_delivery_status": "success",
  "created_at": "2026-10-08T14:32:05Z",
  "secret": "whsec_Hk2Lp9vQ3xR7tY1uZ8wA5bC0dE4fG6h"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X POST "https://api.sendeo.io/v1/webhooks" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://boutique.fr/webhooks/sendeo",
    "events": [
      "message.delivered",
      "message.bounced",
      "message.complained"
    ]
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.post(
    "https://api.sendeo.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "url": "https://boutique.fr/webhooks/sendeo",
        "events": [
            "message.delivered",
            "message.bounced",
            "message.complained",
        ],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/webhooks');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "url": "https://boutique.fr/webhooks/sendeo",
    "events": [
        "message.delivered",
        "message.bounced",
        "message.complained"
    ]
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://boutique.fr/webhooks/sendeo",
    "events": [
      "message.delivered",
      "message.bounced",
      "message.complained"
    ]
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Modifier un webhook

`PATCH /v1/webhooks/{webhook_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `webhook_id` | chemin | string (uuid) | oui |  |

**Corps de la requête** (`application/json`) : [WebhookUpdate](#webhookupdate)

```json
{
  "enabled": false
}
```

**Réponse `200`** ([WebhookOut](#webhookout)) — Succès.

```json
{
  "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "url": "https://boutique.fr/webhooks/sendeo",
  "events": [
    "message.delivered",
    "message.bounced",
    "message.complained"
  ],
  "enabled": false,
  "disabled_reason": null,
  "secret_prefix": "whsec_Hk2Lp",
  "last_delivery_status": "success",
  "created_at": "2026-10-08T14:32:05Z"
}
```

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X PATCH "https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SENDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

**Exemple — Python**

```python
import os

import requests

response = requests.patch(
    "https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    json={
        "enabled": False,
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
    "enabled": false
}
JSON,
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": false
  }),
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
console.log(await response.json())
```

### Supprimer un webhook

`DELETE /v1/webhooks/{webhook_id}`

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
| `webhook_id` | chemin | string (uuid) | oui |  |

**Réponse `204`** — Ressource supprimée (pas de contenu).

**Erreurs**

- `401` : Clé API absente, invalide ou révoquée.
- `404` : Ressource introuvable dans votre organisation.
- `422` : Données invalides : `detail` indique le champ en cause.
- `429` : Limite de débit atteinte.

**Exemple — cURL**

```bash
curl -X DELETE "https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $SENDEO_API_KEY"
```

**Exemple — Python**

```python
import os

import requests

response = requests.delete(
    "https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    headers={
        "Authorization": f"Bearer {os.environ['SENDEO_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
```

**Exemple — PHP**

```php
<?php
$ch = curl_init('https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SENDEO_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
```

**Exemple — Node.js**

```javascript
const response = await fetch('https://api.sendeo.io/v1/webhooks/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SENDEO_API_KEY}`,
  },
})
if (!response.ok) throw new Error(`Erreur ${response.status}`)
```

## Objets

### AbMetric

Valeurs : `opens`, `clicks`

### AbTestIn

Test A/B (CMP-08) : l'échantillon reçoit les variantes, le reste reçoit la gagnante.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `sample_percent` | integer | oui |  |
| `metric` | [AbMetric](#abmetric) | non | Par défaut : `"opens"`. |
| `wait_hours` | integer | non | Par défaut : `4`. |
| `variants` | liste de [VariantIn](#variantin) | oui |  |

### AbTestOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `sample_percent` | integer | oui |  |
| `metric` | [AbMetric](#abmetric) | oui |  |
| `wait_hours` | integer | oui |  |
| `decide_at` | string (date-time) ou null | oui |  |
| `winner_id` | string (uuid) ou null | oui |  |
| `variants` | liste de [VariantOut](#variantout) | oui |  |

### AddressResultOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | string | oui |  |
| `verdict` | [ValidationVerdict](#validationverdict) | oui |  |
| `reason` | [ValidationReason](#validationreason) | oui |  |

### ApiTemplateCreate

Template créé par l'API publique : HTML écrit à la main, éditeur de code par défaut.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui |  |
| `category_id` | string (uuid) ou null | non |  |
| `editor` | [TemplateEditor](#templateeditor) | non | Par défaut : `"code"`. |
| `subject` | string | non |  |
| `preheader` | string | non |  |
| `html` | string | non |  |

### ApiTemplateUpdate

Modification par l'API publique ; champ absent : inchangé.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string ou null | non |  |
| `subject` | string ou null | non |  |
| `preheader` | string ou null | non |  |
| `html` | string ou null | non | Templates de l'éditeur de code seulement (409 pour l'éditeur visuel). |
| `base_revision` | integer ou null | non | `revision` lue avant de modifier : 409 si le template a changé depuis. |

### AttachmentIn

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `filename` | string | oui | Nom du fichier vu par le destinataire. |
| `content_type` | string | non | Type MIME, par exemple `application/pdf`. Par défaut : `"application/octet-stream"`. |
| `content` | string | oui | Contenu du fichier encodé en base64. |

### Body_import_contacts

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `file` | fichier | oui |  |
| `list_id` | string (uuid) ou null | non |  |
| `update_existing` | boolean | non | Par défaut : `true`. |

### BreakdownOut

Répartition des ouvertures et clics (TRK-07), scanners exclus.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `clients` | liste de [ShareOut](#shareout) | oui |  |
| `devices` | liste de [ShareOut](#shareout) | oui |  |
| `countries` | liste de [ShareOut](#shareout) | oui |  |

### CampaignCreate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui |  |
| `subject` | string | non |  |
| `preheader` | string | non |  |
| `from_name` | string | non |  |
| `from_email` | string | non |  |
| `reply_to` | string (email) ou null | non |  |
| `template_id` | string (uuid) ou null | non |  |
| `list_ids` | liste de string (uuid) | non |  |
| `segment_ids` | liste de string (uuid) | non |  |
| `tracking_enabled` | boolean | non | Par défaut : `true`. |
| `ab_test` | [AbTestIn](#abtestin) ou null | non |  |

### CampaignOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |
| `subject` | string | oui |  |
| `preheader` | string | oui |  |
| `from_name` | string | oui |  |
| `from_email` | string | oui |  |
| `reply_to` | string ou null | oui |  |
| `template` | [RefOut](#refout) ou null | oui |  |
| `lists` | liste de [RefOut](#refout) | oui |  |
| `segments` | liste de [RefOut](#refout) | oui |  |
| `recipient_count` | integer | oui |  |
| `status` | [CampaignStatus](#campaignstatus) | oui |  |
| `tracking_enabled` | boolean | oui |  |
| `send_time_optimization` | boolean | oui |  |
| `ab_test` | [AbTestOut](#abtestout) ou null | oui |  |
| `scheduled_at` | string (date-time) ou null | oui |  |
| `sent_at` | string (date-time) ou null | oui |  |
| `finished_at` | string (date-time) ou null | oui |  |
| `error` | string ou null | oui |  |
| `created_at` | string (date-time) | oui |  |
| `updated_at` | string (date-time) | oui |  |
| `stats` | [DeliveryStatsOut](#deliverystatsout) | oui |  |

### CampaignPage

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `items` | liste de [CampaignOut](#campaignout) | oui |  |
| `next_cursor` | string ou null | oui |  |
| `total` | integer | oui |  |

### CampaignSchedule

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `scheduled_at` | string (date-time) ou null | non |  |
| `send_time_optimization` | boolean | non | Par défaut : `false`. |

### CampaignStatus

Valeurs : `draft`, `scheduled`, `sending`, `paused`, `sent`, `cancelled`, `failed`

### CampaignUpdate

Champs absents : inchangés ; `null` explicite : effacé (template, réponse).

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string ou null | non |  |
| `subject` | string ou null | non |  |
| `preheader` | string ou null | non |  |
| `from_name` | string ou null | non |  |
| `from_email` | string ou null | non |  |
| `reply_to` | string (email) ou null | non |  |
| `template_id` | string (uuid) ou null | non |  |
| `list_ids` | liste de string (uuid) ou null | non |  |
| `segment_ids` | liste de string (uuid) ou null | non |  |
| `tracking_enabled` | boolean ou null | non |  |
| `ab_test` | [AbTestIn](#abtestin) ou null | non |  |

### ContactCreate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | string | oui |  |
| `first_name` | string | non |  |
| `last_name` | string | non |  |
| `list_ids` | liste de string (uuid) | non |  |
| `attributes` | object | non |  |
| `open_tracking_consent` | [OpenTrackingConsent](#opentrackingconsent) | non | Par défaut : `"unknown"`. |

### ContactListCreate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui |  |
| `description` | string | non |  |

### ContactListOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |
| `description` | string | oui |  |
| `contact_count` | integer | oui |  |
| `created_at` | string (date-time) | oui |  |

### ContactListUpdate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string ou null | non |  |
| `description` | string ou null | non |  |

### ContactOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `email` | string | oui |  |
| `first_name` | string | oui |  |
| `last_name` | string | oui |  |
| `status` | [ContactStatus](#contactstatus) | oui |  |
| `lists` | liste de [ListRef](#listref) | oui |  |
| `attributes` | object | oui |  |
| `created_at` | string (date-time) | oui |  |
| `updated_at` | string (date-time) | oui |  |
| `last_activity_at` | string (date-time) ou null | oui |  |
| `engagement_score` | integer | oui |  |
| `open_tracking_consent` | [OpenTrackingConsent](#opentrackingconsent) | oui |  |
| `open_tracking_consent_source` | string | oui |  |
| `open_tracking_consent_at` | string (date-time) ou null | oui |  |

### ContactPage

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `items` | liste de [ContactOut](#contactout) | oui |  |
| `next_cursor` | string ou null | oui |  |
| `total` | integer | oui |  |

### ContactStatus

Valeurs : `subscribed`, `unsubscribed`, `bounced`, `complained`

### ContactUpdate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | string ou null | non |  |
| `first_name` | string ou null | non |  |
| `last_name` | string ou null | non |  |
| `list_ids` | liste de string (uuid) ou null | non |  |
| `attributes` | object ou null | non |  |
| `open_tracking_consent` | [OpenTrackingConsent](#opentrackingconsent) ou null | non |  |

### DailyPointOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `date` | string (date) | oui |  |
| `sent` | integer | oui |  |
| `delivered` | integer | oui |  |
| `measured` | integer | oui |  |
| `opened` | integer | oui |  |
| `clicked` | integer | oui |  |
| `bounced` | integer | oui |  |

### DeliveryStatsOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `recipients` | integer | oui |  |
| `sent` | integer | oui |  |
| `delivered` | integer | oui |  |
| `measured` | integer | oui |  |
| `opened` | integer | oui |  |
| `anonymous_opened` | integer | non | Par défaut : `0`. |
| `clicked` | integer | oui |  |
| `bounced` | integer | oui |  |
| `complained` | integer | oui |  |
| `unsubscribed` | integer | oui |  |
| `failed` | integer | oui |  |
| `queued` | integer | oui |  |

### DeliveryStatus

Valeurs : `pending`, `success`, `failed`

### EventIn

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | string (email) | oui | Adresse du contact ; inconnue, réponse 404 sauf avec `create_contact`. |
| `event` | string | oui | Nom de l'événement, en minuscules (ex. `panier_abandonne`, `achat`). |
| `data` | object | non | Données libres, lues dans les emails du scénario par `{{ var.nom }}`. |
| `create_contact` | boolean | non | Crée le contact s'il n'existe pas (abonné, dans aucune liste : il reçoit les emails du scénario, et une campagne seulement si un segment l'inclut). 409 si l'adresse est dans la liste de suppression. Par défaut : `false`. |

### EventOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `accepted` | boolean | non | Par défaut : `true`. |
| `automations_entered` | integer | oui | Scénarios dans lesquels le contact est entré. |

### ImportJobOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `file_name` | string | oui |  |
| `status` | [ImportStatus](#importstatus) | oui |  |
| `columns` | liste de string | oui |  |
| `sample_rows` | liste de liste de string | oui |  |
| `suggested_mapping` | object | oui |  |
| `list_id` | string (uuid) ou null | oui |  |
| `update_existing` | boolean | oui |  |
| `total_rows` | integer | oui |  |
| `processed_rows` | integer | oui |  |
| `created` | integer | oui |  |
| `updated` | integer | oui |  |
| `skipped` | integer | oui |  |
| `risky` | integer | oui |  |
| `errors` | liste de [ImportRowError](#importrowerror) | oui |  |
| `created_at` | string (date-time) | oui |  |

### ImportRowError

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `row` | integer | oui |  |
| `email` | string | oui |  |
| `reason` | string | oui |  |

### ImportStatus

Valeurs : `mapping`, `processing`, `completed`, `failed`

### JsonValue

Toute valeur JSON (texte, nombre, booléen, liste ou objet).

### ListRef

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |

### MessageDetailOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `to` | string | oui | Adresse du destinataire. |
| `from_email` | string | oui |  |
| `from_name` | string | oui |  |
| `subject` | string | oui | Objet, variables remplacées une fois l'email envoyé. |
| `status` | [RecipientStatus](#recipientstatus) | oui | Dernier état connu : `queued`, `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained` ou `failed`. |
| `tags` | liste de string | oui |  |
| `campaign_id` | string (uuid) ou null | oui | Campagne d'origine ; nul : transactionnel. |
| `error` | string ou null | oui | Raison de l'échec, si le message n'est pas parti. |
| `created_at` | string (date-time) | oui | Réception de la demande d'envoi. |
| `sent_at` | string (date-time) ou null | oui | Remise au serveur d'envoi. |
| `events` | liste de [MessageEventOut](#messageeventout) | oui | Chronologie, du plus ancien au plus récent. |

### MessageEventOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `type` | [MessageEventType](#messageeventtype) | oui |  |
| `occurred_at` | string (date-time) | oui |  |
| `detail` | string ou null | oui | Précision : lien cliqué, réponse du serveur destinataire, raison d'un échec. |

### MessageEventType

Valeurs : `queued`, `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `unsubscribed`, `failed`

### MessageKind

Valeurs : `campaign`, `transactional`, `automation`

### MessageOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `to` | string | oui | Adresse du destinataire. |
| `from_email` | string | oui |  |
| `from_name` | string | oui |  |
| `subject` | string | oui | Objet, variables remplacées une fois l'email envoyé. |
| `status` | [RecipientStatus](#recipientstatus) | oui | Dernier état connu : `queued`, `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained` ou `failed`. |
| `tags` | liste de string | oui |  |
| `campaign_id` | string (uuid) ou null | oui | Campagne d'origine ; nul : transactionnel. |
| `error` | string ou null | oui | Raison de l'échec, si le message n'est pas parti. |
| `created_at` | string (date-time) | oui | Réception de la demande d'envoi. |
| `sent_at` | string (date-time) ou null | oui | Remise au serveur d'envoi. |

### MessagePage

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `items` | liste de [MessageOut](#messageout) | oui |  |
| `next_cursor` | string ou null | oui | Curseur de la page suivante ; nul : dernière page. |
| `total` | integer | oui | Nombre total de résultats. |

### MessageStatus

Valeurs : `queued`, `sent`, `delivered`, `bounced`, `complained`, `failed`

### OpenTrackingConsent

Accord du contact à la mesure de ses ouvertures (TRK-10) ; sans réponse : `unknown`.

Valeurs : `unknown`, `granted`, `denied`

### RecipientIn

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | string (email) | oui | Adresse du destinataire. |
| `name` | string | non | Nom affiché ; sert de `contact.first_name` si l'adresse n'est pas un contact. |
| `variables` | object | non | Variables propres à ce destinataire, prioritaires sur les variables communes. |

### RecipientStatus

Statut affiché d'un destinataire : celui du message, enrichi de l'ouverture et du clic.

Valeurs : `queued`, `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `failed`

### RefOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |

### SendRequest

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `from` | string | oui | Expéditeur : `commandes@boutique.fr` ou `Boutique <commandes@boutique.fr>`. L'adresse doit être une adresse d'expédition validée, sur un domaine vérifié. |
| `to` | liste de string (email) ou [RecipientIn](#recipientin) | oui | De 1 à 50 destinataires : des adresses, ou des objets avec nom et variables. Chacun reçoit son propre message ; ils ne se voient pas entre eux. |
| `subject` | string ou null | non | Objet, obligatoire sans template ; avec un template, remplace le sien. |
| `html` | string ou null | non | Contenu HTML (sans `template_id`). |
| `text` | string ou null | non | Version texte. Absente, elle est déduite du HTML. |
| `template_id` | string (uuid) ou null | non | Template à utiliser à la place de `html` / `text`. |
| `variables` | object | non | Variables communes à tous les destinataires, lues par `{{ var.nom }}`. |
| `reply_to` | string (email) ou null | non | Adresse de réponse. |
| `tags` | liste de string | non | Jusqu'à 10 étiquettes, renvoyées dans le journal et les webhooks. |
| `attachments` | liste de [AttachmentIn](#attachmentin) | non | Pièces jointes, 10 Mo au total. |
| `tracking` | boolean | non | Suivre les ouvertures et les clics. Désactivé par défaut : les liens (réinitialisation de mot de passe…) restent intacts. Par défaut : `false`. |

### SendResponse

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `messages` | liste de [SentMessageOut](#sentmessageout) | oui |  |

### SentMessageOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui | Identifiant du message, pour `GET /v1/messages/{id}`. |
| `email` | string | oui | Adresse du destinataire, normalisée. |
| `status` | [MessageStatus](#messagestatus) | oui | `queued` : en file d'envoi ; `failed` : refusé tout de suite (voir `error`). |
| `error` | string ou null | oui | Raison d'un refus immédiat (adresse bloquée). |

### ShareOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `label` | string | oui |  |
| `messages` | integer | oui |  |

### StatsOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `period` | `7d` / `30d` / `90d` | oui |  |
| `totals` | [DeliveryStatsOut](#deliverystatsout) | oui |  |
| `series` | liste de [DailyPointOut](#dailypointout) | oui |  |
| `top_campaigns` | liste de [TopCampaignOut](#topcampaignout) | oui |  |
| `breakdown` | [BreakdownOut](#breakdownout) ou null | oui |  |

### TemplateEditor

Valeurs : `builder`, `code`

### TemplateOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |
| `category_id` | string (uuid) ou null | oui |  |
| `editor` | [TemplateEditor](#templateeditor) | oui |  |
| `subject` | string | oui |  |
| `preheader` | string | oui |  |
| `html` | string | oui |  |
| `revision` | integer | oui |  |
| `created_at` | string (date-time) | oui |  |
| `updated_at` | string (date-time) | oui |  |

### TemplateSaved

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |
| `category_id` | string (uuid) ou null | oui |  |
| `editor` | [TemplateEditor](#templateeditor) | oui |  |
| `subject` | string | oui |  |
| `preheader` | string | oui |  |
| `html` | string | oui |  |
| `revision` | integer | oui |  |
| `created_at` | string (date-time) | oui |  |
| `updated_at` | string (date-time) | oui |  |
| `unknown_variables` | liste de string | oui |  |

### TopCampaignOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `name` | string | oui |  |
| `open_rate` | number | oui |  |
| `click_rate` | number | oui |  |

### ValidateRequest

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `emails` | liste de string | oui |  |

### ValidateResponse

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `results` | liste de [AddressResultOut](#addressresultout) | oui |  |
| `credits_remaining` | integer | oui |  |

### ValidationReason

Valeurs : `ok`, `syntax`, `no_mx`, `disposable`, `role`, `catch_all`, `mailbox_not_found`

### ValidationVerdict

Valeurs : `valid`, `risky`, `invalid`

### VariantIn

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `subject` | string | non |  |
| `template_id` | string (uuid) ou null | non |  |

### VariantOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `label` | string | oui |  |
| `subject` | string | oui |  |
| `template` | [RefOut](#refout) ou null | oui |  |
| `sent` | integer | oui |  |
| `measured` | integer | oui |  |
| `opened` | integer | oui |  |
| `anonymous_opened` | integer | non | Par défaut : `0`. |
| `clicked` | integer | oui |  |

### WebhookCreate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `url` | string | oui | Adresse https de votre application ; les adresses privées sont refusées. |
| `events` | liste de [WebhookEventType](#webhookeventtype) | oui | Événements à recevoir. |

### WebhookCreated

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `url` | string | oui |  |
| `events` | liste de [WebhookEventType](#webhookeventtype) | oui |  |
| `enabled` | boolean | oui |  |
| `disabled_reason` | string ou null | oui | Pourquoi le webhook a été désactivé automatiquement, le cas échéant. |
| `secret_prefix` | string | oui | Début du secret, pour le reconnaître sans l'afficher. |
| `last_delivery_status` | [DeliveryStatus](#deliverystatus) ou null | oui | Résultat de la dernière livraison (`success` ou `failed`). |
| `created_at` | string (date-time) | oui |  |
| `secret` | string | oui | Secret de signature (`Sendeo-Signature`), renvoyé uniquement à la création. |

### WebhookEventType

Valeurs : `message.sent`, `message.delivered`, `message.opened`, `message.clicked`, `message.bounced`, `message.complained`, `message.failed`, `contact.unsubscribed`

### WebhookOut

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string (uuid) | oui |  |
| `url` | string | oui |  |
| `events` | liste de [WebhookEventType](#webhookeventtype) | oui |  |
| `enabled` | boolean | oui |  |
| `disabled_reason` | string ou null | oui | Pourquoi le webhook a été désactivé automatiquement, le cas échéant. |
| `secret_prefix` | string | oui | Début du secret, pour le reconnaître sans l'afficher. |
| `last_delivery_status` | [DeliveryStatus](#deliverystatus) ou null | oui | Résultat de la dernière livraison (`success` ou `failed`). |
| `created_at` | string (date-time) | oui |  |

### WebhookUpdate

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `url` | string ou null | non |  |
| `events` | liste de [WebhookEventType](#webhookeventtype) ou null | non |  |
| `enabled` | boolean ou null | non | Réactiver remet à zéro le compteur d'échecs. |

### Erreur

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `detail` | string | oui | Message lisible, destiné à l'utilisateur. |
