API REST

Tout ce que fait l’interface web de Mankomail passe par une API HTTP qui parle JSON. La même API est ouverte à vos propres outils : un script, un CRM ou un logiciel de gestion peut créer des workflows, les publier, lancer des exécutions, les relire, envoyer des mails ou écrire dans des Tables en votre nom.

Cette section a deux parties : les guides ci-dessous décrivent ce qui est commun à toutes les routes ; la référence liste chaque route, famille par famille, générée depuis le document OpenAPI de l’instance.

Chemin de base

Les routes se trouvent sous <PUBLIC_BASE_URL>/api/v1, par exemple <PUBLIC_BASE_URL>/api/v1/workflows. Les corps de requête et de réponse sont en JSON (Content-Type: application/json), à l’exception de quelques téléchargements (pièces jointes, exports CSV) que la référence signale.

Quelques points d’entrée vivent hors de ce préfixe :

• /healthz et /readyz, les sondes de santé (voir Supervision) ;
• /hooks/…, les points d’entrée appelés par d’autres systèmes : le déclencheur webhook d’un workflow, POST /hooks/wf/<jeton>, et les notifications push des fournisseurs de messagerie. Ils sont autorisés par le jeton de leur URL, pas par une session ni une clé.

L’interface web reçoit aussi des mises à jour en temps réel par un WebSocket, sur /api/v1/ws. Il est réservé à l’interface : il n’est pas ouvert aux clés d’API.

Deux façons de s’authentifier

	Cookie de session	Clé d’API
Pour	L’interface web, un navigateur	Un script, un serveur, une intégration
Comment	POST /api/v1/auth/login pose un cookie nommé session	Authorization: Bearer mk_… sur chaque requête
Agit comme	Le membre connecté	Le membre qui a créé la clé, dans la limite de ses portées
Atteint	Toutes les routes	Toutes les routes qui déclarent une portée ; une poignée de routes sont réservées à la session
Limite de débit	Les tentatives de connexion, par adresse IP	600 requêtes par minute, par clé

Une clé ne fait jamais plus que ce que son membre pourrait faire dans l’interface : elle voit les mêmes workflows, les mêmes boîtes, et les routes d’administration exigent toujours que le membre soit administrateur. Ce qu’une clé ajoute, c’est une restriction : ses portées. Authentification explique comment créer et utiliser une clé ; Portées détaille ce que chaque portée couvre.

Conventions communes à toutes les routes

• Les erreurs ont toujours la forme { "code": "domaine.code", "message": "…", "details": { … } }. Testez le code, jamais le message. Voir Erreurs et la liste des codes d’erreur.
• Les listes sont paginées par un curseur opaque : envoyez cursor et limit, lisez nextCursor. Les lignes des Tables font exception et utilisent un offset. Voir Pagination.
• Les routes qui créent ou déclenchent acceptent un en-tête Idempotency-Key : une requête rejouée après une coupure réseau ne crée ni n’envoie deux fois. Voir Idempotence.
• Les limites : le débit par clé, le corps de requête de 5 Mo, les bornes de chaque liste. Voir Limites.
• Les identifiants sont des chaînes opaques ; les dates sont en ISO 8601, en UTC (2026-10-04T09:00:00.000Z).

Guides

• Authentification — créer une clé, l’envoyer, expiration, révocation, ce qui refuse les clés.
• Portées — la grammaire domaine:verbe et le tableau des domaines.
• Pagination — curseurs, limites, et l’exception des Tables.
• Idempotence — l’en-tête Idempotency-Key, rejeux et conflits.
• Erreurs — la forme des erreurs, les classes de statut HTTP et les codes communs.
• Limites — toutes les bornes qu’un client doit connaître.
• Exemples — un parcours curl de bout en bout, de la clé à la première exécution.
• Document OpenAPI — où il est, comment l’importer, les extensions x-.
• Référence — toutes les routes, générées depuis le document OpenAPI.

Un assistant IA peut aussi piloter l’instance par son serveur MCP, qui utilise les mêmes clés d’API et les mêmes portées : voir MCP.