# 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.

```bash
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
  }'
```

```ts
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`.

```json
{
  "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.

```bash
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`. |

```bash
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.

```json
{
  "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. |

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

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

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

Réponse : statut `200`.

```json
{
  "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.