> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lekalao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Campagnes

> Créer une campagne depuis votre CMS, la tester, l'envoyer et suivre ses chiffres.

L'API couvre le chemin le plus courant : votre outil rédige le contenu, Lekalao l'envoie. Les réglages fins (segment, A/B test, planification, expéditeur propre à la campagne) se font dans l'interface.

## Créer

```bash theme={null}
curl -X POST https://lekalao.example.com/api/v1/campaigns \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Lettre de septembre",
    "subject": "Les pains de la rentrée",
    "list": "9d5c2a1e-8f3b-4c7a-9e21-3b8f0c6d4a12",
    "editor": "markdown",
    "content": "# La rentrée\n\nBonjour {{ subscriber.first_name }},\n\n…\n\n[Se désabonner]({{ unsubscribe_url }})  \n{{ organisation.address }}",
    "track_opens": true,
    "track_clicks": true
  }'
```

| Champ                         |                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `name`                        | Nom interne.                                                                  |
| `subject`                     | Objet ; accepte les [variables](/fr/content/personalization).                 |
| `list`                        | Uuid de la liste.                                                             |
| `editor`                      | `markdown`, `html`, `mjml` ou `blocks`. Voir [Éditeurs](/fr/content/editors). |
| `content`                     | Le contenu, dans le format de l'éditeur. 500 000 caractères au plus.          |
| `track_opens`, `track_clicks` | `true` par défaut.                                                            |

La campagne est créée en **brouillon**, pour toute la liste, avec l'expéditeur de la liste.

<Tip>
  Le contenu doit contenir `{{ unsubscribe_url }}` et `{{ organisation.address }}`, directement ou par son modèle. Sans eux, la campagne ne partira pas.
</Tip>

## Tester

Jusqu'à 5 adresses. L'objet est préfixé par « \[Test] » ; les abonnés et les statistiques ne sont pas touchés :

```bash theme={null}
curl -X POST https://lekalao.example.com/api/v1/campaigns/$CAMPAIGN/test \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "recipients": ["redaction@maboulangerie.fr"] }'
```

## Envoyer

```bash theme={null}
curl -X POST https://lekalao.example.com/api/v1/campaigns/$CAMPAIGN/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: campagne-septembre-envoi"
```

Si tout est prêt, l'envoi démarre immédiatement :

```json theme={null}
{ "message": "1284 e-mails are on their way.", "queued": 1284 }
```

Sinon, `422` avec la liste de ce qui manque, les mêmes vérifications que dans l'interface ([Envoyer](/fr/campaigns/sending)) :

```json theme={null}
{
    "message": "This campaign cannot be sent yet.",
    "problems": [
        "Configure a mailer in the settings.",
        "Add your postal address to the content, with {{ organisation.address }}."
    ]
}
```

<Warning>
  L'envoi est définitif. Utilisez une `Idempotency-Key` : un appel répété
  après une coupure réseau ne relancera pas l'envoi.
</Warning>

## Suivre

```bash theme={null}
curl https://lekalao.example.com/api/v1/campaigns/$CAMPAIGN \
  -H "Authorization: Bearer $LEKALAO_TOKEN" -H "Accept: application/json"
```

```json theme={null}
{
    "data": {
        "id": "0c9e3f5a-…",
        "name": "Lettre de septembre",
        "subject": "Les pains de la rentrée",
        "status": "sent",
        "list": "9d5c2a1e-…",
        "scheduled_at": null,
        "sent_at": "2026-09-17T08:00:12+00:00",
        "statistics": {
            "recipients": 1284,
            "sent": 1284,
            "delivered": 1270,
            "opens": 812,
            "unique_opens": 655,
            "clicks": 190,
            "unique_clicks": 141,
            "bounces": 9,
            "complaints": 0,
            "unsubscribes": 4
        },
        "created_at": "2026-09-16T15:40:02+00:00"
    }
}
```

| `status`    |                                                                                      |
| ----------- | ------------------------------------------------------------------------------------ |
| `draft`     | Brouillon.                                                                           |
| `scheduled` | Planifiée (depuis l'interface).                                                      |
| `sending`   | En cours d'envoi.                                                                    |
| `paused`    | En pause, à la main ou par la [sécurité d'envoi](/fr/deliverability/sending-safety). |
| `sent`      | Terminée.                                                                            |
| `cancelled` | Annulée.                                                                             |

Les chiffres sont recalculés chaque minute. `delivered` n'est rempli que si le fournisseur envoie ses [retours](/fr/deliverability/feedback). Le webhook `campaign.sent` prévient quand l'envoi est terminé.

`GET /api/v1/campaigns?status=sent&list={id}` liste les campagnes, les plus récentes d'abord.

## Supprimer

`DELETE /api/v1/campaigns/{id}` supprime une campagne et ses statistiques. `409` pendant un envoi : mettez-la en pause dans l'interface d'abord.

## Modèles

Pour que votre CMS n'envoie que le corps de l'e-mail, préparez un [modèle](/fr/content/templates) avec l'en-tête, le pied, le lien de désabonnement et l'adresse postale. Les modèles se gèrent aussi par l'API : `GET|POST /templates`, `GET|PUT|DELETE /templates/{id}`.