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.

   cURL

   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>"
     }'

   Node (fetch)

   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()

   SDK

   Copie le client TypeScript dans ton projet, puis :

   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.

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.

Tous les champs sont dans la référence de l’API. Les erreurs et les limites sont dans Erreurs et 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.