# 定时发送

现在发送消息，让它稍后送达。在任意 [创建消息](https://info.pocketalert.app/api/messages/create.md) 请求中添加 `send_at` 或 `delay`，Pocket Alert 会将消息加密保存直到送达时间，然后像普通推送一样发出。

你那边不需要 cron 任务，不需要队列工作进程，也不需要一直保持运行的进程直到下周二。

## 两种指定时间的方式

| 参数 | 接受的格式 | 示例 |
|-----------|---------|----------|
| `send_at` | RFC3339、Unix 时间戳，或 `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`、`1786867200`、`2026-08-15 09:00` |
| `delay` | Go 风格的时长，或纯秒数 | `30m`、`2h`、`90s`、`3600` |

二者只能传一个，同时传入会返回 `400`。

不带时区偏移的 `send_at` 会按**你的账户时区**解析，因此 `2026-08-15 09:00` 指的是你所在地的早上九点，而不是 UTC 时间。可在 [账户设置](https://pocketalert.app/account) 中修改。

## 定时发送消息

**cURL — absolute time**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Certificate expires tomorrow",
    "message": "api.example.com — renew before 09:00 UTC",
    "send_at": "2026-08-15T09:00:00Z",
    "level": "high"
  }'
```

**cURL — relative delay**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check the migration",
    "message": "Started at 14:02 — verify row counts",
    "delay": "2h"
  }'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Check the migration',
    message: 'Started at 14:02 — verify row counts',
    delay: '2h'
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={'Token': 'your-api-key'},
    json={
        'title': 'Check the migration',
        'message': 'Started at 14:02 — verify row counts',
        'delay': '2h'
    }
)
```

定时消息会返回 `201`，并带有 `"scheduled": true`，而不是已送达的消息：

```json
{
  "tid": "n8k2vq7pxr4m",
  "scheduled": true,
  "status": "pending",
  "title": "Check the migration",
  "deliver_at": "09.08.2026 16:02:00",
  "deliver_at_utc": "2026-08-09T13:02:00Z",
  "tz": "Europe/Berlin"
}
```

请保存 `tid`，取消定时消息时需要用到它。

## 列出定时消息 (GET)

```
GET https://api.pocketalert.app/v1/messages/scheduled
```

默认返回待发送的消息，最近的排在最前。

| 查询参数 | 可选值 | 说明 |
|-----------------|--------|-------------|
| `status` | `pending`、`sending`、`sent`、`canceled`、`failed`、`all` | 按状态筛选。默认为 `pending`。 |

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/scheduled?status=all" \
  -H "Token: your-api-key"
```

每个条目包含 `tid`、`title`、`message`、`priority`、`status`、`deliver_at`、`deliver_at_utc`、`tz`、`application`、`device`、`created_at`，若消息带有按钮，还会包含 `actions`。

## 取消 (DELETE)

```
DELETE https://api.pocketalert.app/v1/messages/scheduled/{tid}
```

```bash
curl -X DELETE "https://api.pocketalert.app/v1/messages/scheduled/n8k2vq7pxr4m" \
  -H "Token: your-api-key"
```

| 状态 | 含义 |
|:------:|---------|
| `200` | 已取消。附件也会随之删除。 |
| `404` | 你的账户下没有该 `tid` 对应的定时消息 |
| `409` | 已发送、正在发送或已取消 |

取消操作与分发器之间的竞争是安全的：如果送达已经开始，你会收到 `409`，而不会得到一条只取消了一半的消息。

## 需要了解的规则

**时间范围最远为 30 天。** 超出范围的请求会被拒绝。

**过去的时间会返回 `400`**，但允许 60 秒的时钟偏差。在该容差范围内，消息会立即发送。

**级别和套餐在定时时确定，而不是在送达时确定。** 以 `critical` 级别定时、且处于付费套餐的消息，即使套餐在此期间到期，仍会以 `critical` 级别送达。定时发送是一种承诺。

**每日上限在定时时计算。** 定时消息计入你定时当天的[每日消息上限](https://info.pocketalert.app/features/daily-limits.md)，而不是送达当天，并且送达从不会受上限阻止。超出上限时，定时请求本身会返回 `429`。取消不会退还配额。

**附件在定时时上传**，并在送达时关联到消息。取消时会删除已存储的文件。

**逾期消息会延迟送达，而不会丢弃。** 如果服务在送达时间之后重启，消息会在下一个调度周期发出，而不会消失。

**内容从定时的那一刻起使用你的个人密钥加密存储**，与普通消息相同。

> **Warning: 付费功能**
>
> 定时发送仅限付费套餐使用。免费套餐下携带 `send_at` 或 `delay` 的请求会返回 `403`，不会被悄悄丢弃。

## 相关链接

- [创建消息](https://info.pocketalert.app/api/messages/create.md) — 完整的请求参考
- [优先级](https://info.pocketalert.app/features/priority-levels.md) — 已送达的提醒如何表现
- [操作按钮](https://info.pocketalert.app/features/action-buttons.md) — 定时消息会保留其按钮
- [每日消息上限](https://info.pocketalert.app/features/daily-limits.md) — 定时消息如何计数
