定时发送
现在发送消息,让它稍后送达。在任意 创建消息 请求中添加 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 时间。可在 账户设置 中修改。
定时发送消息
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 -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"
}'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'
})
});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,而不是已送达的消息:
{
"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。 |
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}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,不会被悄悄丢弃。