# Intégrer avec un agent de code

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](https://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](https://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](https://mail.hgdc.ch/openapi.json)                         | Pour générer un client dans un autre langage.                                                                |
| Index de la doc     | [mail.hgdc.ch/llms.txt](https://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 :

```bash
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> ».

> **Attention**
>
> La clé reste sur le serveur. Demande à l’agent de la lire depuis une variable d’environnement, jamais de l’écrire dans le code, un fichier versionné ou un composant envoyé au navigateur.

## 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](/docs/guides/venir-de-resend/#ce-qui-n-est-pas-encore-pris-en-charge).