# 取消
`POST` `https://api.pushwoosh.com/messaging/v2/cancel`
取消先前创建的消息，通过其 `message_code` 进行识别。只有当消息处于以下状态之一时，才能取消：
- **pending：**已创建但尚未开始发送。
- **waiting：**已计划在未来某个时间发送。
- **processing：**正在准备投递。
要检查消息是否仍处于可取消状态，请参阅[检查消息状态](#checking-message-status)。
## 请求
在 `Authorization: Token ` 标头中使用您的[服务器 API 令牌](/zh/developer/api-reference/api-access-token/#server-api-token)进行身份验证。
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `message_code` | 字符串 | 是 | 要取消的消息的[消息代码](/zh/developer/api-reference/api-identifiers/#message-code)，由 [`Notify`](/zh/developer/api-reference/messaging-api-v2/notify/) 在 `result.message_code` 中返回。 |
### 请求示例
```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"
}'
```
## 响应
成功后，返回 HTTP 200 和一个空的 JSON 正文。
```json
{}
```
## 错误
错误使用标准的 gRPC-Gateway 错误封套：`{ "code": ..., "message": ..., "details": [...] }`。
| HTTP 状态 | 条件 |
|---|---|
| `400` | `message_code` 缺失。 |
| `400` | 消息不处于可取消状态（不再是 `pending`、`waiting` 或 `processing`）。 |
| `403` | 消息属于另一个账户。 |
| `404` | 给定的 `message_code` 不存在任何消息。 |
| `500` | 加载消息或发布取消时发生内部错误。请重试请求。 |
**示例**
取消一个不再存在的消息将返回 HTTP `404`：
```json
{
"code": 5,
"message": "message not found",
"details": []
}
```
## 检查消息状态
在取消之前，您可以验证消息是否仍处于可取消状态。除了在控制面板的消息表中读取**状态**列（[**Campaigns → 一次性消息**](/zh/product/statistics-and-analytics/message-history/)），您还可以使用 [`messages:list`](/zh/developer/api-reference/statistics-api/message-statistics-api/#messageslist) 以编程方式查询状态：
- 在 `filters.messages_codes` 数组中传递 `message_code`（以及必需的 `filters.application`）。
- 读取 `items[]` 中匹配条目的 `status` 字段。
## 相关内容