Vue d’ensemble pour les développeurs

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

Vous hésitez entre l’API et le SMTP ? Lisez API ou SMTP.

URL de base et gestion des versions

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

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.

Authentification

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

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.
• Les jetons d’accès OAuth émis pour les applications OAuth 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.

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.

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.
• 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.
• 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.
• 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.
• 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 et Limites.

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. Pour les commandes d’installation, consultez SDK et bibliothèques ; pour des exemples complets, consultez les guides des frameworks, à commencer par Node.js.

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 et Signature des requêtes.

Serveur MCP et outils IA

Le serveur 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 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 les indexe toutes.

Étapes suivantes