# 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](/docs/guides/venir-de-resend/). ## Adresse de base ```text 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](/docs/reference/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](/docs/guides/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](/docs/reference/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](/docs/reference/limites/). ## Routes | Méthode | Chemin | Page | | ------- | -------------------------- | -------------------------------------------------------- | | POST | `/emails` | [E-mails](/docs/reference/api-emails/) | | POST | `/emails/batch` | [E-mails](/docs/reference/api-emails/) | | GET | `/emails/:id` | [E-mails](/docs/reference/api-emails/) | | POST | `/contacts` | [Contacts](/docs/reference/api-contacts/) | | GET | `/contacts` | [Contacts](/docs/reference/api-contacts/) | | GET | `/contacts/:id_ou_adresse` | [Contacts](/docs/reference/api-contacts/) | | PATCH | `/contacts/:id_ou_adresse` | [Contacts](/docs/reference/api-contacts/) | | DELETE | `/contacts/:id_ou_adresse` | [Contacts](/docs/reference/api-contacts/) | | GET | `/lists` | [Listes](/docs/reference/api-listes/) | | POST | `/lists` | [Listes](/docs/reference/api-listes/) | | GET | `/segments` | [Listes](/docs/reference/api-listes/), alias de `/lists` | | POST | `/segments` | [Listes](/docs/reference/api-listes/), alias de `/lists` | | POST | `/broadcasts` | [Campagnes](/docs/reference/api-campagnes/) | | GET | `/broadcasts` | [Campagnes](/docs/reference/api-campagnes/) | | GET | `/broadcasts/:id` | [Campagnes](/docs/reference/api-campagnes/) | | POST | `/broadcasts/:id/send` | [Campagnes](/docs/reference/api-campagnes/) | | GET | `/templates` | [Modèles](/docs/reference/api-modeles/) | | GET | `/templates/:id` | [Modèles](/docs/reference/api-modeles/) | | 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](/docs/reference/api-emails/#lien-de-desabonnement). ## É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](/docs/guides/declencher-un-workflow/). ## Outils - [SDK TypeScript](/docs/reference/sdk/) : 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](https://mail.hgdc.ch/openapi.json). - `/llms.txt` : l’index de la documentation pour les agents de code. Disponible sur [mail.hgdc.ch](https://mail.hgdc.ch/llms.txt).