API campagnes

Une campagne envoie un même e-mail à tous les contacts d’une liste. Elle part en brouillon, ou tout de suite avec send: true. Une campagne envoyée ne se modifie plus et ne repart pas. Sans list_id, elle vise tous les contacts de ton espace.

POST /broadcasts

Crée une campagne.

Champ	Type	Obligatoire	Description
name	string	Non	Nom interne, 120 caractères au plus. Les destinataires ne le voient pas.
from	string	Oui pour l’envoi	Expéditeur d’un domaine vérifié de ton espace. Requis au moment de l’envoi.
subject	string	Oui pour l’envoi	Objet, 998 caractères au plus. Requis au moment de l’envoi.
preview_text	string	Non	Texte d’aperçu, 300 caractères au plus.
reply_to	string	Non	Adresse de réponse.
html	string	Non	Contenu HTML, 512 000 caractères au plus. Ne se combine pas avec template_id.
text	string	Non	Contenu texte, 512 000 caractères au plus.
template_id	string	Non	Modèle à utiliser pour le contenu. Ne se combine pas avec html.
list_id	string	Non	Liste qui reçoit la campagne.
segment_id	string	Non	Alias de list_id, pour un code écrit pour Resend.
send	boolean	Non	true lance la campagne tout de suite. Défaut : false, brouillon.

Sans html ni template_id, la campagne part avec le contenu de départ de ton espace, que tu pourras remplacer dans l’application.

cURL

curl -X POST https://api.mail.hgdc.ch/broadcasts \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter octobre",
    "from": "Atelier Rochat <bonjour@envoi.atelier.ch>",
    "subject": "Les nouveautés d'\''octobre",
    "preview_text": "Trois choses à savoir",
    "template_id": "k57w8c2n5d9f1h6j3m0p4q7r",
    "list_id": "jd7q4v2m8x1r5n9c3b6z0h4w",
    "send": false
  }'

SDK

import { Agentmail } from "./agentmail"

const mail = new Agentmail()
const broadcast = await mail.broadcasts.create({
  name: "Newsletter octobre",
  from: "Atelier Rochat <bonjour@envoi.atelier.ch>",
  subject: "Les nouveautés d'octobre",
  preview_text: "Trois choses à savoir",
  template_id: "k57w8c2n5d9f1h6j3m0p4q7r",
  list_id: "jd7q4v2m8x1r5n9c3b6z0h4w",
  send: false,
})

Réponse : statut 200.

{
  "object": "broadcast",
  "id": "jn9s2k5w7d1f4h8c3v6b0m2x"
}

Une campagne sans objet, sans contenu, ou avec un expéditeur hors domaine vérifié ne part pas : l’erreur 422 est renvoyée à l’envoi, et la campagne reste en brouillon.

GET /broadcasts

Renvoie les 100 campagnes les plus récentes de ton espace.

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

Réponse : statut 200, avec des objets de même forme que celui de la section suivante.

GET /broadcasts/:id

Lit une campagne.

Champ	Type	Obligatoire	Description
id	string	Oui, dans le chemin	Identifiant renvoyé par POST /broadcasts.

curl https://api.mail.hgdc.ch/broadcasts/jn9s2k5w7d1f4h8c3v6b0m2x \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

Réponse : statut 200. status vaut draft (brouillon), sending (en cours d’envoi) ou sent (envoyée). recipients reste à null tant que la campagne n’est pas partie.

{
  "object": "broadcast",
  "id": "jn9s2k5w7d1f4h8c3v6b0m2x",
  "name": "Newsletter octobre",
  "from": "Atelier Rochat <bonjour@envoi.atelier.ch>",
  "subject": "Les nouveautés d'octobre",
  "preview_text": "Trois choses à savoir",
  "reply_to": null,
  "list_id": "jd7q4v2m8x1r5n9c3b6z0h4w",
  "status": "sent",
  "recipients": 42,
  "unsubscribes": 0,
  "created_at": "2026-10-09T14:00:00.000Z",
  "sent_at": "2026-10-09T14:05:00.000Z"
}

unsubscribes compte les désabonnements survenus à la suite de cette campagne. Une campagne inconnue de ton espace renvoie 404.

POST /broadcasts/:id/send

Lance une campagne en brouillon.

Champ	Type	Obligatoire	Description
id	string	Oui, dans le chemin	Identifiant de la campagne, en brouillon.

curl -X POST https://api.mail.hgdc.ch/broadcasts/jn9s2k5w7d1f4h8c3v6b0m2x/send \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

SDK

import { Agentmail } from "./agentmail"

const mail = new Agentmail()
await mail.broadcasts.send("jn9s2k5w7d1f4h8c3v6b0m2x")

Réponse : statut 200.

{
  "object": "broadcast",
  "id": "jn9s2k5w7d1f4h8c3v6b0m2x"
}

La campagne passe en sending, puis en sent quand tous les lots sont partis. Lancer une campagne déjà partie renvoie 422 avec le message Cette campagne est déjà partie. : rien ne repart. Une campagne inconnue renvoie 404.

Si ça ne marche pas

• 422 à l’envoi : il manque l’objet, le contenu, ou l’expéditeur n’est pas d’un domaine Prêt. La campagne reste en brouillon : corrige et relance.
• recipients vaut null : la campagne n’est pas encore partie. C’est normal pour un brouillon.