Connecter un agent IA avec MCP

Présentation

Le serveur MCP Postline hébergé est disponible sur https://api.srs-postline.com/mcp et fournit des outils typés pour les e-mails, domaines, suppressions et webhooks.

Avant d'écrire le moindre code

• Demandez à l'utilisateur une clé API de projet, ou proposez-lui de créer une clé sandbox sur https://app.srs-postline.com/fr/login — n'inventez, ne devinez et ne réutilisez jamais une clé provenant d'un autre projet.
• Placez la clé dans une variable d'environnement côté serveur. Ne la placez pas dans du code frontend, un bundle d'application mobile, un dépôt public ou un fichier .env committé.
• Commencez avec une clé srs_test_ sur un projet sandbox. Le sandbox ne peut livrer qu'aux destinataires que l'utilisateur a vérifiés, donc la livraison réelle en boîte de réception nécessite un projet live ayant passé la revue — ne promettez pas que l'envoi live fonctionne avant que cette revue soit terminée.
• Lisez /llms.txt et openapi/postline.yaml avant de générer du code de requête ; ne devinez pas les noms de champs ou les points de terminaison.

Connexion

Connectez le endpoint hébergé avec une clé Bearer Postline ; aucun téléchargement ni build local n’est nécessaire.

claude mcp add --scope user --transport http postline \
  https://api.srs-postline.com/mcp \
  --header "Authorization: Bearer srs_live_xxx"

export POSTLINE_API_KEY='srs_live_xxx'
codex mcp add postline --url https://api.srs-postline.com/mcp \
  --bearer-token-env-var POSTLINE_API_KEY

Vérifications à exécuter avant chaque envoi

• Envoyez toujours un Idempotency-Key dérivé de l'action déclenchante (ID de commande, ID d'événement) afin que les nouvelles tentatives ne puissent pas provoquer un double envoi.
• Ne placez jamais de codes OTP, de jetons de réinitialisation de mot de passe ou d'autres secrets dans un champ qui est journalisé ou transmis en dehors du corps du message.
• Demandez la portée de clé API la plus étroite dont la tâche a besoin (emails:send suffit pour l'envoi ; ne demandez pas domains:write ou api_keys:write sauf si la tâche l'exige).
• Limitez les destinataires à 100 par appel. L’API actuelle n’accepte ni pièces jointes ni en-têtes personnalisés ; refusez le fichier ou partagez un lien sans prétendre qu’il a été joint.
• Ne relancez pas silencieusement en cas de réponse 4xx. Seuls 429 et 503 peuvent être relancés en toute sécurité, et uniquement avec un backoff.

Traiter chaque code de réponse

• 202 — mis en file d'attente, pas livré. Enregistrez l'id retourné si vous devez consulter le statut plus tard.
• 400 — payload invalide ; corrigez la requête, ne relancez pas telle quelle.
• 401 — clé invalide ou expirée ; arrêtez-vous et signalez-le à l'utilisateur, ne fabriquez pas de nouvelle clé.
• 403 — portée manquante ou le domaine d'envoi n'est pas encore vérifié ; demandez à l'utilisateur de vérifier le domaine avant de continuer.
• 409 — conflit d'idempotence ; considérez que la requête originale a déjà été envoyée.
• 422 — le destinataire est supprimé (bounce/plainte antérieurs) ; ne relancez pas l'envoi vers ce destinataire.
• 429 — limite de débit atteinte ; patientez et relancez plus tard, ne bouclez pas de manière serrée.
• 503 — file d'attente indisponible ; relancez avec un backoff, ne basculez pas vers un transport non officiel.

Références lisibles par machine

• /llms.txt — index condensé de ces règles pour les fenêtres de contexte des agents.
• /openapi/postline.yaml — schéma OpenAPI 3.1 complet de chaque point de terminaison.
• /fr/api/ — référence API pour humains.
• /fr/webhooks/ — détails sur la signature et les relances des webhooks.