# Annuler

`POST` `https://api.pushwoosh.com/messaging/v2/cancel`

Annule un message créé précédemment, identifié par son `message_code`. L'annulation n'est disponible que lorsque le message se trouve dans l'un de ces états :

- **pending :** créé mais pas encore pris en charge pour l'envoi.
- **waiting :** programmé pour un envoi à une date ultérieure.
- **processing :** en cours de préparation pour la livraison.

<Aside type="caution" title="Important">

- Si le message est en état `processing`, l'annulation n'arrête que les livraisons qui n'ont pas encore été effectuées. Toute personne ayant déjà reçu le message peut toujours l'avoir.

- Si le message a déjà été annulé ou si son envoi est terminé, l'API renvoie une erreur `400`. Cet appel n'est pas idempotent. Vérifiez le statut du message avant de réessayer.
</Aside>

Pour vérifier si un message est toujours dans un état annulable, consultez la section [Vérifier le statut du message](#verifier-le-statut-du-message).


## Requête

Authentifiez-vous avec votre [jeton d'API serveur](/fr/developer/api-reference/api-access-token/#server-api-token) dans l'en-tête `Authorization: Token <API_TOKEN>`.

| Champ | Type | Requis | Description |
|---|---|---|---|
| `message_code` | string | Oui | [Code de message](/fr/developer/api-reference/api-identifiers/#message-code) du message à annuler, tel que retourné par [`Notify`](/fr/developer/api-reference/messaging-api-v2/notify/) dans `result.message_code`. |

### Exemple de requête

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/cancel \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX"
  }'
```

## Réponse

En cas de succès, renvoie un statut HTTP 200 avec un corps JSON vide.

```json
{}
```

## Erreurs

Les erreurs utilisent l'enveloppe d'erreur standard de gRPC-Gateway : `{ "code": ..., "message": ..., "details": [...] }`.

| Statut HTTP | Condition |
|---|---|
| `400` | Le `message_code` est manquant. |
| `400` | Le message n'est pas dans un état annulable (il n'est plus `pending`, `waiting`, ou `processing`). |
| `403` | Le message appartient à un autre compte. |
| `404` | Aucun message n'existe pour le `message_code` donné. |
| `500` | Une erreur interne s'est produite lors du chargement du message ou de la publication de l'annulation. Réessayez la requête. |


**Exemple**

L'annulation d'un message qui n'existe plus renvoie un statut HTTP `404` :

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## Vérifier le statut du message

Avant d'annuler, vous pouvez vérifier si un message est toujours dans un état annulable. En plus de lire la colonne **Statut** dans le tableau des messages du Panneau de Contrôle ([**Campagnes → Messages uniques**](/fr/product/statistics-and-analytics/message-history/)), vous pouvez interroger le statut par programmation avec [`messages:list`](/fr/developer/api-reference/statistics-api/message-statistics-api/#messageslist) :

- Passez le `message_code` dans le tableau `filters.messages_codes` (en même temps que le champ requis `filters.application`).
- Lisez le champ `status` de l'entrée correspondante dans `items[]`.

<Aside type="note">
`messages:list` fait partie de l'API de statistiques et utilise un en-tête d'authentification différent de ce point de terminaison : `Authorization: Api <Server Key>`.
</Aside>

## Sujets connexes

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="Statistiques des messages" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Aperçu de l'API de messagerie v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migration depuis la v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>