# Envoyer depuis ton logiciel

Ton site ou ton logiciel envoie ses e-mails (factures, confirmations, codes) par un simple appel HTTP. L’API a la même forme que celle de Resend : un code écrit pour Resend fonctionne en changeant l’adresse et la clé.

**Avant de commencer** : un domaine **Prêt** dans ton espace, et un accès aux variables d’environnement de ton serveur.

1. **Crée une clé d'API**

   Dans **Clés d’API**, donne un nom à l’application qui va s’en servir, puis choisis son type. Pour un site qui envoie ses e-mails, **Envoi seulement** suffit. Copie la clé tout de suite : elle commence par `am_` et ne s’affiche qu’une fois.

2. **Range la clé côté serveur**

   Ajoute-la à l’environnement de ton serveur, sous `AGENTMAIL_API_KEY`. Elle ne doit jamais être écrite dans du code envoyé au navigateur.

3. **Envoie un e-mail**

   Choisis l’appel qui correspond à ton outil.

   ```bash
   curl -X POST https://api.mail.hgdc.ch/emails \
     -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "from": "Factures <factures@envoi.atelier.ch>",
       "to": "client@exemple.ch",
       "subject": "Ta facture d'\''octobre",
       "html": "<p>Merci pour ta commande.</p>"
     }'
   ```

   ```ts
   const response = await fetch("https://api.mail.hgdc.ch/emails", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.AGENTMAIL_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       from: "Factures <factures@envoi.atelier.ch>",
       to: "client@exemple.ch",
       subject: "Ta facture d'octobre",
       html: "<p>Merci pour ta commande.</p>",
     }),
   })
   const { id } = await response.json()
   ```

   Copie le [client TypeScript](/docs/reference/sdk/) dans ton projet, puis :

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

   const mail = new Agentmail()
   const { id } = await mail.emails.send({
     from: "Factures <factures@envoi.atelier.ch>",
     to: "client@exemple.ch",
     subject: "Ta facture d'octobre",
     html: "<p>Merci pour ta commande.</p>",
   })
   ```

4. **Vérifie dans l'application**

   La réponse contient l’`id` de l’e-mail. Il apparaît aussitôt dans **E-mails**, avec son parcours en direct.

> **Attention**
>
> Ne renvoie jamais un envoi après une erreur réseau sans clé d’idempotence : le premier message est peut-être déjà parti. Ajoute un `Idempotency-Key` à chaque envoi qui compte. Voir [Envoyer sans doublon](/docs/guides/envoyer-sans-doublon/).

Tous les champs sont dans la [référence de l’API](/docs/reference/api-emails/). Les erreurs et les limites sont dans [Erreurs](/docs/reference/erreurs/) et [Limites](/docs/reference/limites/).

## Si ça ne marche pas

- **`403 invalid_api_key`** : la clé est mal copiée ou révoquée. Crée-en une nouvelle dans **Clés d’API**.
- **`401 missing_api_key`** : l’en-tête `Authorization` est absent, ou il manque l’espace après `Bearer`.
- **`422 validation_error` sur `from`** : l’adresse n’appartient pas à un domaine **Prêt** de ton espace.