Introduction à l'API

L’API sert à envoyer des e-mails depuis ton site ou ton logiciel (factures, confirmations, codes), et à gérer depuis ton code tes contacts, listes, campagnes et modèles. Elle a la forme de l’API Resend : un code écrit pour Resend marche en changeant l’adresse et la clé. Voir Venir de Resend.

Adresse de base

https://api.mail.hgdc.ch

Chaque chemin de cette section s’ajoute à cette adresse : POST /emails s’appelle https://api.mail.hgdc.ch/emails.

Authentification

Chaque requête porte l’en-tête Authorization: Bearer am_….

Crée la clé dans Clés d’API, avec le nom de l’application qui va s’en servir, et choisis ce qu’elle peut faire :

• Envoi seulement : envoyer des e-mails, éventuellement depuis un seul domaine.
• Accès complet : aussi lire les e-mails, gérer contacts, listes, campagnes et modèles.

Donne à chaque application le minimum : une clé d’envoi qui fuit ne peut ni lire tes contacts ni lancer une campagne. Une clé par application : si l’une fuit, tu la révoques, et les autres continuent de marcher. La clé ne s’affiche qu’une fois, copie-la tout de suite.

Range-la dans une variable d’environnement côté serveur, par exemple AGENTMAIL_API_KEY. Elle ne doit jamais arriver dans un navigateur : celui qui la lit peut envoyer au nom de ton espace.

Cas	Statut	name
Pas d’en-tête Authorization	401	missing_api_key
Clé inconnue ou révoquée	403	invalid_api_key
Clé « envoi seulement » sur une autre route que l’envoi et GET /emails/:id	401	restricted_api_key

Format

• Les requêtes et les réponses sont en JSON. Les requêtes avec un corps envoient Content-Type: application/json.
• Les champs s’écrivent en minuscules avec _, comme reply_to ou preview_text.
• Chaque objet porte un champ object (email, contact, list, broadcast, template ou event). Une liste porte object: "list" et un tableau data.
• Les dates sont en ISO 8601, en UTC : 2026-10-10T08:00:00.000Z.
• Les identifiants sont des chaînes opaques. Ne suppose rien de leur forme.

Les erreurs ont toujours la même forme, voir Erreurs.

Idempotence

Un envoi peut être répété sans doublon : ajoute l’en-tête Idempotency-Key (256 caractères au plus). La même clé renvoie le même id, sans second envoi. Utilise un identifiant de ton métier, comme le numéro de facture. Voir Envoyer sans doublon.

Pagination

Seule la liste des contacts est paginée : GET /contacts renvoie des pages avec limit et after. Les autres listes ne sont pas paginées :

• GET /lists renvoie toutes les listes de l’espace ;
• GET /broadcasts renvoie les 100 campagnes les plus récentes ;
• GET /templates renvoie les 100 modèles les plus récents.

Détail dans API contacts.

Limites

Les envois sont limités à 600 par minute, et à la limite quotidienne de l’espace (1 000 destinataires au départ, relevée sur demande). Un e-mail porte 50 destinataires au plus, to, cc et bcc réunis, et un lot 100 e-mails au plus. La liste complète est dans Limites.

Routes

Méthode	Chemin	Page
POST	/emails	E-mails
POST	/emails/batch	E-mails
GET	/emails/:id	E-mails
POST	/contacts	Contacts
GET	/contacts	Contacts
GET	/contacts/:id_ou_adresse	Contacts
PATCH	/contacts/:id_ou_adresse	Contacts
DELETE	/contacts/:id_ou_adresse	Contacts
GET	/lists	Listes
POST	/lists	Listes
GET	/segments	Listes, alias de /lists
POST	/segments	Listes, alias de /lists
POST	/broadcasts	Campagnes
GET	/broadcasts	Campagnes
GET	/broadcasts/:id	Campagnes
POST	/broadcasts/:id/send	Campagnes
GET	/templates	Modèles
GET	/templates/:id	Modèles
POST	/events	Voir Événements, plus bas

Deux routes ne sont pas destinées à ton logiciel. /unsubscribe reçoit les clics de désabonnement des destinataires, et /webhooks/ses reçoit les événements d’Amazon SES. Le désabonnement est décrit dans API e-mails.

Événements

POST /events fait entrer un contact dans les workflows qui attendent un événement. Il crée le contact s’il n’existe pas, sinon le complète. Un contact entre une seule fois par workflow, et un contact désabonné n’entre dans aucun.

Corps : name (requis, 1 à 64 caractères : lettres, chiffres, ., _, -, en minuscules ; un nom invalide renvoie 422), email (requis), first_name et last_name (texte ou null, 100 caractères au plus), properties (50 clés au plus, valeurs texte, nombre ou booléen).

Réponse : { "object": "event", "name", "contact_id", "workflows_started" }. workflows_started compte les workflows où le contact vient d’entrer.

Cette route partage la limite d’écriture de /contacts : au-delà, 429 rate_limit_exceeded. Pas à pas, avec cURL et le SDK : Déclencher un workflow depuis ton application.

Outils

• SDK TypeScript : un fichier à copier, sans dépendance.
• /openapi.json : la description OpenAPI des routes, pour générer un client ou importer dans un outil. Disponible sur mail.hgdc.ch.
• /llms.txt : l’index de la documentation pour les agents de code. Disponible sur mail.hgdc.ch.