# API modèles

Un modèle est un e-mail réutilisable, avec ses variables comme `{{entreprise}}`. Tu le crées dans l’application, puis tu l’envoies depuis ton code avec `template` (voir [API e-mails](/docs/reference/api-emails/#envoi-avec-un-modele)). L’API lit les modèles, elle ne les crée pas.

## GET `/templates`

Renvoie les 100 modèles les plus récents de ton espace, sans leur contenu HTML ni texte.

```bash
curl https://api.mail.hgdc.ch/templates \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"
```

```ts
const response = await fetch("https://api.mail.hgdc.ch/templates", {
  headers: { Authorization: `Bearer ${process.env.AGENTMAIL_API_KEY}` },
})
const { data } = await response.json()
```

```ts
import { Agentmail } from "./agentmail"

const mail = new Agentmail()
const { data } = await mail.templates.list()
```

### Réponse

Statut `200`.

```json
{
  "object": "list",
  "data": [
    {
      "object": "template",
      "id": "k57w8c2n5d9f1h6j3m0p4q7r",
      "name": "Facture",
      "subject": "Ta facture {{numero}}",
      "preview_text": null,
      "from": "Factures <factures@envoi.atelier.ch>",
      "reply_to": null,
      "variables": [
        { "key": "numero", "type": "string", "fallback_value": null },
        { "key": "entreprise", "type": "string", "fallback_value": "ton entreprise" }
      ],
      "created_at": "2026-10-01T09:00:00.000Z",
      "updated_at": "2026-10-05T14:30:00.000Z"
    }
  ]
}
```

## GET `/templates/:id`

Renvoie un modèle avec son contenu HTML et texte.

| Champ | Type   | Obligatoire         | Description            |
| ----- | ------ | ------------------- | ---------------------- |
| `id`  | string | Oui, dans le chemin | Identifiant du modèle. |

```bash
curl https://api.mail.hgdc.ch/templates/k57w8c2n5d9f1h6j3m0p4q7r \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"
```

```ts
const response = await fetch(
  "https://api.mail.hgdc.ch/templates/k57w8c2n5d9f1h6j3m0p4q7r",
  { headers: { Authorization: `Bearer ${process.env.AGENTMAIL_API_KEY}` } },
)
const template = await response.json()
```

```ts
import { Agentmail } from "./agentmail"

const mail = new Agentmail()
const template = await mail.templates.get("k57w8c2n5d9f1h6j3m0p4q7r")
```

### Réponse

Statut `200`, avec les mêmes champs que la liste, plus `html` et `text`.

```json
{
  "object": "template",
  "id": "k57w8c2n5d9f1h6j3m0p4q7r",
  "name": "Facture",
  "subject": "Ta facture {{numero}}",
  "preview_text": null,
  "from": "Factures <factures@envoi.atelier.ch>",
  "reply_to": null,
  "variables": [
    { "key": "numero", "type": "string", "fallback_value": null },
    { "key": "entreprise", "type": "string", "fallback_value": "ton entreprise" }
  ],
  "created_at": "2026-10-01T09:00:00.000Z",
  "updated_at": "2026-10-05T14:30:00.000Z",
  "html": "<p>Bonjour {{entreprise}}, voici ta facture {{numero}}.</p>",
  "text": "Bonjour {{entreprise}}, voici ta facture {{numero}}."
}
```

Chaque variable de `variables` a un `key`, toujours de type `string`, et son `fallback_value`, ou `null` s’il n’y en a pas. `from` vaut `null` quand le modèle n’a pas d’expéditeur par défaut : il faut alors le donner à l’envoi. Un modèle inconnu de ton espace renvoie `404` avec `name: "not_found"`.