Guides

Intégrer avec un agent de code

Donner à Claude Code, Codex ou Cursor tout ce qu'il faut pour brancher l'envoi d'e-mails dans ton application, proprement et sans fuite de clé.

Un agent de code (Claude Code, Codex, Cursor) écrit l’intégration à ta place s’il a les bonnes consignes : où appeler l’API, comment ranger la clé, que faire en cas d’erreur. Elles sont réunies dans une fiche qu’il lit avant d’écrire une ligne.

Avant de commencer : un domaine Prêt dans ton espace, et une clé d’API créée dans Clés d’API.

Ce que l’agent reçoit

Ressource	Adresse	Pour quoi faire
Fiche d’intégration	mail.hgdc.ch/agent/hgdc-mail/SKILL.md	Règles, routes, erreurs, exemples. Au format Agent Skill.
Client TypeScript	mail.hgdc.ch/sdk/agentmail.ts	Un fichier sans dépendance, à copier dans le projet. Réessaie seul les envois qui ont une clé d’idempotence.
Description OpenAPI	mail.hgdc.ch/openapi.json	Pour générer un client dans un autre langage.
Index de la doc	mail.hgdc.ch/llms.txt	Toutes les pages de cette aide, lisibles par une machine.

Installer la fiche

Pour un projet suivi par Claude Code, pose la fiche dans le dossier des skills du projet :

mkdir -p .claude/skills/hgdc-mail
curl -o .claude/skills/hgdc-mail/SKILL.md https://mail.hgdc.ch/agent/hgdc-mail/SKILL.md

Pour Codex ou Cursor, ajoute une ligne dans AGENTS.md ou dans les règles du projet : « Pour envoyer des e-mails, suis https://mail.hgdc.ch/agent/hgdc-mail/SKILL.md ».

Une demande qui marche

Donne à l’agent le contexte métier et les contraintes, pas seulement la tâche :

Branche l’envoi des factures dans src/billing/send-invoice.ts. Suis la fiche Mail. La clé est dans AGENTMAIL_API_KEY. Utilise une clé d’idempotence construite à partir du numéro de facture. Si l’envoi échoue sans réponse, réessaie avec la même clé.

Une fois l’intégration écrite, relis les trois points qui comptent : la clé n’apparaît dans aucun fichier versionné, chaque envoi qui compte a sa clé d’idempotence, et les erreurs 401, 403 et 422 ne sont pas réessayées.

Si ça ne marche pas

L’agent n’utilise pas la fiche : donne-lui son adresse explicitement dans la demande, ou vérifie que le fichier est bien dans .claude/skills/hgdc-mail/.
L’agent écrit la clé en dur : rappelle-lui la règle, et demande-lui de la retirer. Si la clé a pu être publiée, révoque-la dans Clés d’API et crée-en une nouvelle.
L’agent propose attachments ou scheduled_at : ces champs ne sont pas pris en charge. Voir Venir de Resend.

Cette page t'a aidé ?