# Référence de l’API

> L’API REST d’Emailit en un coup d’œil. URL de base, authentification, requêtes et réponses JSON, ID d’objets, gestion des versions et toutes les ressources que vous pouvez gérer.

L’API Emailit est une API REST servie en HTTPS. Vous envoyez du JSON, vous recevez du JSON, et vous authentifiez chaque requête avec un jeton bearer. Utilisez-la pour envoyer des e-mails et pour gérer tout le reste d’un espace de travail : domaines d’envoi, clés API, contacts, listes de contacts, campagnes, modèles, webhooks et plus encore.

## URL de base

Toutes les requêtes sont adressées à l’URL de base de la version 2 :

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

Les chemins de cette référence sont relatifs à cette URL. Par exemple, `POST /emails` signifie `POST https://api.emailit.com/v2/emails`.

## Effectuer votre première requête

Cette requête envoie un e-mail. Remplacez l’expéditeur par une adresse d’un [domaine d’envoi vérifié](/fr/docs/domains/verification/) et définissez `EMAILIT_API_KEY` avec l’une de vos [clés API](/fr/docs/developers/api-keys/).

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>"
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Welcome to Acme',
  html: '<p>Thanks for signing up.</p>',
});
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>",
})
```

La réponse est le nouvel objet e-mail, avec son ID (`em_…`) et le statut `accepted`. Pour toutes les options, consultez [Envoyer un e-mail](/fr/docs/api-reference/emails/send/).

## Authentification

Transmettez une clé API ou un jeton d’accès OAuth dans l’en-tête `Authorization` :

```http
Authorization: Bearer secret_••••••••••••••••••••••••••••••••
```

Les clés API commencent par `secret_` et appartiennent à un espace de travail. Une clé a la portée `full` (tous les endpoints) ou la portée `sending` (endpoints d’envoi uniquement), et une clé d’envoi peut être limitée à un domaine d’envoi. Les requêtes sans clé valide échouent avec `401`. Consultez [Authentification](/fr/docs/api-reference/authentication/).

## 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 corps qui n’est pas un JSON valide renvoie `400` avec le message `Invalid JSON in request body`. Le corps de requête ne peut pas dépasser 50 Mo.
- **Méthodes.** `GET` lit, `POST` crée et met à jour, et `DELETE` supprime. L’API n’utilise ni `PUT` ni `PATCH`.
- **Objets.** Chaque objet possède un champ `object` qui indique son type (`email`, `domain`, `api_key`, `audience`, `subscriber`, `contact`, …) et un `id`.
- **Horodatages.** Les dates sont des chaînes ISO 8601 en UTC, précises à la microseconde, par exemple `2026-10-01T09:30:12.482913Z`. Les champs non définis valent `null`.
- **Listes.** Les endpoints de liste sont paginés et la plupart acceptent des filtres et un tri. Consultez [Pagination](/fr/docs/api-reference/pagination/) et [Filtrage et tri](/fr/docs/api-reference/filtering/).
- **Erreurs.** Les requêtes en échec renvoient un code de statut `4xx` ou `5xx` et un corps JSON qui explique le problème. Consultez [Erreurs](/fr/docs/api-reference/errors/).

## ID d’objets

Les ID sont des chaînes composées d’un préfixe de type et de 27 lettres et chiffres, par exemple `em_4KYof1ZzXndZE2VPi0DgULiekG8`. Ils sont sensibles à la casse et à peu près ordonnés par date de création.

| Préfixe | Objet | Préfixe | Objet |
| --- | --- | --- | --- |
| `em_` | E-mail | `aud_` | Liste de contacts |
| `dom_` | Domaine d’envoi | `sub_` | Abonné |
| `key_` | Clé API | `con_` | Contact |
| `tem_` | Modèle | `cmp_` | Campagne |
| `sup_` | Adresse bloquée | `frm_` | Formulaire |
| `wh_` | Webhook | `fsub_` | Réponse de formulaire |
| `whr_` | Requête de webhook | `aut_` | Automatisation |
| `evt_` | Événement | `aur_` | Exécution d’automatisation |
| `dmr_` | Rapport DMARC | `ev_` | Vérification d’e-mail |
| `evl_` | Liste de vérification | | |

Certaines ressources acceptent aussi un identifiant lisible dans le chemin. Les domaines, les clés API, les listes de contacts, les campagnes et les webhooks acceptent leur nom (`GET /domains/acme.com`). Les contacts et les adresses bloquées acceptent une adresse e-mail, et les abonnés acceptent l’adresse e-mail du contact. Encodez pour l’URL les noms et les adresses qui contiennent des caractères spéciaux. Les domaines créés avant le passage aux ID `dom_` conservent leur ID `sd_` ou `sed_`, et ces ID fonctionnent toujours.

## Gestion des versions

La version actuelle est `v2` et fait partie de l’URL de base. Les nouveaux champs et endpoints sont ajoutés à `v2` sans changement de version : écrivez donc des clients qui ignorent les champs qu’ils ne reconnaissent pas. Consultez [Gestion des versions](/fr/docs/api-reference/versioning/).

## Ressources

  - [E-mails](/fr/docs/api-reference/emails/): Envoyez des e-mails, lisez les messages et leur contenu, et programmez, annulez, relancez ou transférez-les.
  - [Domaines](/fr/docs/api-reference/domains/): Ajoutez des domaines d’envoi, consultez leurs enregistrements DNS et vérifiez-les.
  - [Rapports DMARC](/fr/docs/api-reference/dmarc/): Consultez les rapports DMARC agrégés et forensiques d’un domaine, ou importez les vôtres.
  - [Clés API](/fr/docs/api-reference/api-keys/): Créez, renommez, régénérez et supprimez les clés API d’un espace de travail.
  - [Listes de contacts](/fr/docs/api-reference/audiences/): Gérez les listes d’abonnés utilisées par les campagnes et les formulaires d’inscription.
  - [Abonnés](/fr/docs/api-reference/audiences/subscribers/): Ajoutez, mettez à jour et retirez les abonnés d’une liste de contacts.
  - [Contacts](/fr/docs/api-reference/contacts/): Gérez les profils de contacts et les champs personnalisés, un par un ou en masse.
  - [Campagnes](/fr/docs/api-reference/campaigns/): Créez des campagnes, choisissez leurs listes de contacts, puis envoyez-les ou programmez-les.
  - [Automatisations](/fr/docs/api-reference/automations/): Construisez des workflows à partir de déclencheurs et d’étapes, exécutez-les et examinez leurs exécutions.
  - [Formulaires](/fr/docs/api-reference/forms/): Créez des formulaires d’inscription, publiez-les et effectuez la rotation de leur jeton public.
  - [Modèles](/fr/docs/api-reference/templates/): Créez des versions de modèle, publiez-en une par alias et utilisez-la pour vos envois.
  - [Adresses bloquées](/fr/docs/api-reference/suppressions/): Consultez et gérez les adresses auxquelles Emailit n’envoie pas d’e-mails.
  - [Webhooks](/fr/docs/api-reference/webhooks/): Enregistrez des endpoints qui reçoivent des notifications d’événements signées.
  - [Événements](/fr/docs/api-reference/events/): Consultez le flux d’événements qui alimente les webhooks : livraisons, rebonds, ouvertures et plus encore.
  - [Vérification d’e-mails](/fr/docs/api-reference/email-verifications/): Vérifiez une adresse en temps réel.
  - [Listes de vérification](/fr/docs/api-reference/email-verifications/lists/): Vérifiez jusqu’à 10 000 adresses à la fois et exportez les résultats.

Pour un tableau unique de tous les endpoints et de la portée qu’ils nécessitent, consultez [Tous les endpoints](/fr/docs/api-reference/endpoints/).

## SDK

Des bibliothèques officielles encapsulent l’API pour les langages les plus courants. Leur code source est ouvert, sur [GitHub](https://github.com/emailit).

| Langage | Paquet | Guide |
| --- | --- | --- |
| Node.js | `@emailit/node` | [Node.js](/fr/docs/frameworks/nodejs/) |
| Python | `emailit` | [Python](/fr/docs/frameworks/python/) |
| PHP | `emailit/emailit-php` | [PHP](/fr/docs/frameworks/php/) |
| Laravel | `emailit/emailit-laravel` | [Laravel](/fr/docs/frameworks/laravel/) |
| Ruby | `emailit` | [Ruby on Rails](/fr/docs/frameworks/rails/) |
| Go | `github.com/emailit/emailit-go/v2` | [Go](/fr/docs/frameworks/go/) |
| Java | `com.emailit` | [Java](/fr/docs/frameworks/java/) |
| .NET | `Emailit` | [.NET](/fr/docs/frameworks/dotnet/) |
| Rust | `emailit` | [SDK](/fr/docs/sdks/) |

## Webhooks et événements

Plutôt que d’interroger régulièrement l’API pour suivre les changements de statut, enregistrez un [webhook](/fr/docs/webhooks/) : Emailit envoie à votre endpoint des lots d’événements signés au fil de l’eau (livraisons, rebonds, ouvertures, clics, nouveaux contacts et plus encore). Les mêmes événements sont disponibles via [Lister les événements](/fr/docs/api-reference/events/list/). Pour la liste complète, consultez [Types d’événements](/fr/docs/webhooks/event-types/).

## Serveur MCP

Le serveur MCP hébergé à l’adresse `https://api.emailit.com/mcp` permet aux assistants IA comme ChatGPT, Claude, Cursor, Codex et Grok d’appeler cette API pour votre compte : 109 outils couvrent toutes les ressources de cette page. Les assistants se connectent avec OAuth ou utilisent une clé API, avec les mêmes portées. Consultez [Serveur MCP](/fr/docs/mcp/) et la [référence des outils](/fr/docs/mcp/tools/).

## Voir aussi

  - [Authentification](/fr/docs/api-reference/authentication/): Clés API, portées, restrictions de domaine et jetons OAuth.
  - [Limites de débit](/fr/docs/api-reference/rate-limits/): Limites d’envoi, en-têtes de réponse et intervalle exponentiel entre les relances.
  - [Erreurs](/fr/docs/api-reference/errors/): Formats d’erreur, codes de statut et solutions courantes.
  - [Envoyer votre premier e-mail](/fr/docs/quickstart/api/): Un démarrage rapide pas à pas, de la clé API à la boîte de réception.

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