# Vue d’ensemble pour les développeurs

> URL de base, authentification, ID d’objets, erreurs, pagination, limites de débit, SDK, webhooks et MCP. Les conventions communes à toutes les intégrations Emailit.

Cette page rassemble les conventions à connaître avant d’écrire du code pour Emailit : où se trouve l’API, comment les requêtes sont authentifiées, comment les objets sont identifiés, et comment fonctionnent les erreurs, la pagination et les limites de débit. Chaque section renvoie vers la référence détaillée.

## Modes d’intégration

| Interface | Endpoint | Utilisation |
| --- | --- | --- |
| API REST | `https://api.emailit.com/v2` | Envoyer des e-mails et gérer toutes les ressources depuis votre code. |
| Relais SMTP | `smtp.emailit.com` | Applications, frameworks et CMS qui utilisent déjà le SMTP. Voir [Paramètres SMTP](/fr/docs/smtp/settings/). |
| Webhooks | Votre endpoint HTTPS | Événements de livraison, d’engagement et de ressources en temps réel. |
| Serveur MCP | `https://api.emailit.com/mcp` | Permettre à des assistants IA comme Claude, ChatGPT et Cursor de travailler avec votre espace de travail. |
| OAuth 2.1 | `https://api.emailit.com/oauth/*` | Intégrations qui agissent au nom d’utilisateurs Emailit sans manipuler leurs clés API. |

Vous hésitez entre l’API et le SMTP ? Lisez [API ou SMTP](/fr/docs/get-started/api-or-smtp/).

## URL de base et gestion des versions

Tous les endpoints REST se trouvent sous une même URL de base :

```text
https://api.emailit.com/v2
```

`v2` est la version actuelle et la seule documentée. L’ancienne API `v1` est obsolète ; consultez [Gestion des versions](/fr/docs/api-reference/versioning/).

## Authentification

Envoyez une clé API comme jeton bearer dans l’en-tête `Authorization` de chaque requête :

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

- Les clés API commencent par `secret_`. Les anciennes clés sans ce préfixe continuent de fonctionner.
- Chaque clé appartient à un espace de travail et possède une portée : **Full Access** (`full`) peut appeler tous les endpoints, **Sending Only** (`sending`) peut seulement envoyer et gérer les envois. Consultez [Clés API](/fr/docs/developers/api-keys/).
- Les jetons d’accès OAuth émis pour les [applications OAuth](/fr/docs/developers/oauth-apps/) sont acceptés dans le même en-tête.
- Une clé absente renvoie `401` avec `API key required`, une clé inconnue renvoie `401` avec `Invalid API key`, et un espace de travail suspendu renvoie `403` avec `Workspace is suspended`.

N’appelez jamais l’API avec votre clé depuis un navigateur ou une application mobile. Gardez-la sur votre serveur. Détails : [Authentification](/fr/docs/api-reference/authentication/).

## ID et préfixes

Chaque objet a un ID sous forme de chaîne avec un préfixe de type : vous voyez ainsi d’un coup d’œil à quoi correspond un ID.

| Objet | Préfixe | Exemple |
| --- | --- | --- |
| E-mail | `em_` | `em_4K6oASS7KP9ztzWmSN9ndEu13HW` |
| Domaine d’envoi | `dom_` | `dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6` |
| Clé API | `key_` | `key_4F2kN8sQwE1rT6yU3iO9pA7sD5f` |
| Liste de contacts | `aud_` | `aud_3zR8tY2uI6oP4aS1dF9gH7jK5lM` |
| Abonné | `sub_` | `sub_4K6oASS7KP9ztzWnqS4svxApJzO` |
| Contact | `con_` | `con_4A9sD2fG6hJ1kL8zX3cV7bN5mQw` |
| Modèle | `tem_` | `tem_3wE8rT1yU5iO9pA2sD6fG4hJ7kL` |
| Adresse bloquée | `sup_` | `sup_4K6oASS7KP9ztzWol5ElicOeKFE` |
| Webhook | `wh_` | `wh_3mN7bV2cX6zL9kJ4hG1fD8sA5pO` |
| Requête de webhook | `whr_` | `whr_4K6oASS7KP9ztzWpVUIec9Jneax` |
| Événement | `evt_` | `evt_4K6oASS7KP9ztzWpqId2iIptac5` |
| Campagne | `cmp_` | `cmp_4B1nM5qW9eR3tY7uI2oP6aS8dF4` |
| Formulaire | `frm_` | `frm_4C3vB7nM1qW5eR9tY2uI6oP8aS4` |
| Réponse à un formulaire | `fsub_` | `fsub_4K6oASS7KP9ztzWqvxLV3IsFRs8` |
| Automatisation | `aut_` | `aut_4D5fG9hJ3kL7zX1cV6bN2mQ8wE4` |
| Exécution d’automatisation | `aur_` | `aur_4K6oASS7KP9ztzWrWOjGgqompRo` |
| Vérification d’e-mail | `ev_` | `ev_4E7gH1jK5lZ9xC3vB8nM2qW6eR4` |
| Liste de vérification | `evl_` | `evl_4F9hJ3kL7zX1cV5bN9mQ2wE6rT8` |
| Rapport DMARC | `dmr_` | `dmr_4K6oASS7KP9ztzWsW7e5qkOYHO6` |

Les domaines créés avant le passage aux ID `dom_` peuvent encore avoir des ID `sd_` ou `sed_`.

Certains endpoints acceptent aussi un identifiant lisible à la place de l’ID : un nom pour les clés API, les domaines, les webhooks, les campagnes et les listes de contacts, et une adresse e-mail pour les contacts et les adresses bloquées. Les e-mails, les modèles et les événements ne se recherchent que par ID.

## Requêtes et réponses

- **JSON en entrée, JSON en sortie.** Envoyez les corps de requête en JSON avec `Content-Type: application/json`. Un JSON mal formé renvoie `400` avec `Invalid JSON in request body`. Un corps de requête peut atteindre 50 Mo ; le message MIME final d’un e-mail peut atteindre 40 Mo.
- **Erreurs.** La plupart des erreurs renvoient `{"statusCode", "error", "message"}`. Les erreurs de validation ajoutent un tableau `details`, et les erreurs d’envoi renvoient `validation_errors`. Les fonctionnalités réservées à certains forfaits renvoient `403` avec `"error": "plan_required"`. Consultez [Erreurs](/fr/docs/api-reference/errors/).
- **Pagination.** Les endpoints de liste acceptent `page` et `limit` (de 1 à 100) et renvoient `data`, `next_page_url` et `previous_page_url`. Les modèles et les automatisations utilisent `page` et `per_page`. Consultez [Pagination](/fr/docs/api-reference/pagination/).
- **Filtrage et tri.** Filtrez avec `field.condition=value`, combinez les filtres avec `match=all` ou `match=or`, et triez avec `order` et `direction`. Par exemple, `GET /v2/emails?status.exact=bounced&order=created_at&direction=desc`. Consultez [Filtrage et tri](/fr/docs/api-reference/filtering/).
- **Idempotence.** Envoyez un en-tête `Idempotency-Key` avec `POST /emails` et `POST /emails/:id/forward` pour pouvoir relancer vos requêtes sans risque. Emailit renvoie la première réponse pendant 24 heures. Consultez [Idempotence](/fr/docs/api-reference/idempotency/).
- **Limites de débit.** L’envoi est limité par espace de travail, par défaut à 2 e-mails par seconde et 5 000 e-mails par jour, partagés entre l’API et le SMTP. Les réponses incluent des en-têtes `ratelimit-*`, et une réponse `429` inclut `retry-after`. Consultez [Limites de débit](/fr/docs/api-reference/rate-limits/) et [Limites](/fr/docs/limits/).

## SDK

Des bibliothèques officielles encapsulent l’API REST pour Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET et Rust. Elles sont toutes sur [GitHub](https://github.com/emailit). Pour les commandes d’installation, consultez [SDK et bibliothèques](/fr/docs/sdks/) ; pour des exemples complets, consultez les guides des frameworks, à commencer par [Node.js](/fr/docs/frameworks/nodejs/).

## Webhooks

Les webhooks envoient les événements à votre endpoint dès qu’ils se produisent : livraisons, rebonds, ouvertures, clics, e-mails entrants et modifications des domaines, des contacts et d’autres ressources. Chaque requête contient un tableau JSON de 100 événements au maximum et est signée en HMAC-SHA256 dans l’en-tête `X-Emailit-Signature`. Emailit réessaie les requêtes en échec, jusqu’à 11 tentatives. Commencez par [Configurer un webhook](/fr/docs/webhooks/set-up/) et [Signature des requêtes](/fr/docs/webhooks/request-signature/).

## Serveur MCP et outils IA

Le [serveur MCP](/fr/docs/mcp/) hébergé, à l’adresse `https://api.emailit.com/mcp`, donne aux assistants IA 109 outils couvrant toute l’API v2, de l’envoi d’e-mails aux campagnes et aux automatisations. Les assistants se connectent via OAuth ou avec une clé API, et les [plugins Emailit](/fr/docs/mcp/plugins-and-skills/) ajoutent des skills pour ChatGPT, Codex, Claude Code, Cursor et Grok.

La documentation est aussi publiée pour l’IA : chaque page a une version Markdown, et [/docs/llms.txt](/fr/docs/developers/llms-txt/) les indexe toutes.

## Étapes suivantes

  - [Créer une clé API](/fr/docs/developers/api-keys/): Choisissez une portée, limitez la clé à un domaine et stockez-la en sécurité.
  - [Envoyer votre premier e-mail](/fr/docs/quickstart/api/): Effectuez votre premier appel API en quelques minutes.
  - [SDK et bibliothèques](/fr/docs/sdks/): Des bibliothèques officielles pour neuf langages et frameworks.
  - [Référence de l’API](/fr/docs/api-reference/): Tous les endpoints, paramètres et réponses.

---
Source: https://emailit.com/fr/docs/developers/