# Stornieren

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

Storniert eine zuvor erstellte Nachricht, die durch ihren `message_code` identifiziert wird. Die Stornierung ist nur möglich, während sich die Nachricht in einem dieser Zustände befindet:

- **pending:** erstellt, aber noch nicht zum Senden abgeholt.
- **waiting:** für einen zukünftigen Sendezeitpunkt geplant.
- **processing:** wird gerade für die Zustellung vorbereitet.

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

- Wenn sich die Nachricht im Zustand `processing` befindet, stoppt die Stornierung nur Zustellungen, die noch nicht versendet wurden. Jeder, der die Nachricht bereits erhalten hat, kann sie weiterhin haben.

- Wenn die Nachricht bereits storniert wurde oder der Versand abgeschlossen ist, gibt die API `400` zurück. Dieser Aufruf ist nicht idempotent. Überprüfen Sie den Nachrichtenstatus, bevor Sie es erneut versuchen.
</Aside>

Um zu überprüfen, ob eine Nachricht noch stornierbar ist, siehe [Nachrichtenstatus überprüfen](#checking-message-status).


## Anfrage

Authentifizieren Sie sich mit Ihrem [Server API-Token](/de/developer/api-reference/api-access-token/#server-api-token) im `Authorization: Token <API_TOKEN>`-Header.

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `message_code` | string | Ja | [Nachrichtencode](/de/developer/api-reference/api-identifiers/#message-code) der zu stornierenden Nachricht, wie von [`Notify`](/de/developer/api-reference/messaging-api-v2/notify/) in `result.message_code` zurückgegeben. |

### Beispielanfrage

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

## Antwort

Bei Erfolg wird HTTP 200 mit einem leeren JSON-Body zurückgegeben.

```json
{}
```

## Fehler

Fehler verwenden den standardmäßigen gRPC-Gateway-Fehlerumschlag: `{ "code": ..., "message": ..., "details": [...] }`.

| HTTP-Status | Bedingung |
|---|---|
| `400` | `message_code` fehlt. |
| `400` | Die Nachricht befindet sich nicht in einem stornierbaren Zustand (sie ist nicht mehr `pending`, `waiting` oder `processing`). |
| `403` | Die Nachricht gehört zu einem anderen Konto. |
| `404` | Für den angegebenen `message_code` existiert keine Nachricht. |
| `500` | Beim Laden der Nachricht oder Veröffentlichen der Stornierung ist ein interner Fehler aufgetreten. Versuchen Sie die Anfrage erneut. |


**Beispiel**

Das Stornieren einer nicht mehr existierenden Nachricht gibt HTTP `404` zurück:

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

## Nachrichtenstatus überprüfen

Vor der Stornierung können Sie überprüfen, ob eine Nachricht noch stornierbar ist. Neben dem Lesen der Spalte **Status** in der Nachrichtentabelle im Control Panel ([**Kampagnen → Einmalige Nachrichten**](/de/product/statistics-and-analytics/message-history/)) können Sie den Status auch programmatisch mit [`messages:list`](/de/developer/api-reference/statistics-api/message-statistics-api/#messageslist) abfragen:

- Übergeben Sie den `message_code` im `filters.messages_codes`-Array (zusammen mit dem erforderlichen `filters.application`).
- Lesen Sie das `status`-Feld des passenden Eintrags in `items[]`.

<Aside type="note">
`messages:list` ist Teil der Statistik-API und verwendet einen anderen Authentifizierungs-Header als dieser Endpunkt: `Authorization: Api <Server Key>`.
</Aside>

## Verwandte Themen

<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="Nachrichtenstatistiken" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Messaging API v2 Übersicht" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migration von v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>