跳到正文

定时发送 ​

现在发送消息,让它稍后送达。在任意 创建消息 请求中添加 send_at 或 delay,Pocket Alert 会将消息加密保存直到送达时间,然后像普通推送一样发出。

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

两种指定时间的方式 ​

参数接受的格式示例
send_atRFC3339、Unix 时间戳,或 YYYY-MM-DD HH:MM2026-08-15T09:00:00Z、1786867200、2026-08-15 09:00
delayGo 风格的时长,或纯秒数30m、2h、90s、3600

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

不带时区偏移的 send_at 会按你的账户时区解析,因此 2026-08-15 09:00 指的是你所在地的早上九点,而不是 UTC 时间。可在 账户设置 中修改。

定时发送消息 ​

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

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

查询参数可选值说明
statuspending、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 级别送达。定时发送是一种承诺。

每日上限在定时时计算。 定时消息计入你定时当天的每日消息上限,而不是送达当天,并且送达从不会受上限阻止。超出上限时,定时请求本身会返回 429。取消不会退还配额。

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

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

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

付费功能

定时发送仅限付费套餐使用。免费套餐下携带 send_at 或 delay 的请求会返回 403,不会被悄悄丢弃。

相关链接 ​

Pocket Alert 文档