开发文档

Y-Send 只有一个核心接口，与 ServerChan 协议完全兼容。所有能发起 HTTP 请求的语言和工具都可以调用。

快速开始

1. 打开 控制台 注册账号，系统会自动分配一个 SendKey。

2. 在控制台为 SendKey 配置消息通道（企业微信 / 钉钉 / 飞书群机器人 webhook）。

3. 把下面 URL 中的 <SENDKEY> 换成你自己的，粘贴到浏览器地址栏即可收到第一条消息：

https://push.example.com/<SENDKEY>.send?title=你好&desp=这是第一条消息

发送消息

GET 或 POST  https://push.example.com/<SENDKEY>.send

支持三种传参方式：GET query、POST 表单（application/x-www-form-urlencoded）、POST JSON。

投递语义

每条消息带 delivery 状态：success（全部通道成功或仅站内保存）/ failed（结果已落盘，有通道失败）/ pending（投递结果未落盘的中间态）/ unknown（结果无法确认）。响应 data.delivery 可读取该状态。

• 携带幂等键：同键重试返回首次持久化结果（相同 pushid、相同 code，带 X-Idempotent-Replay: 1 头），绝不重复调用外部通道；若首次「外部已投递但结果未落盘」，同键重试返回 40006 DELIVERY_UNKNOWN 与原 pushid，同样不会重复投递。幂等记录重启后仍有效，保证期等于消息保留期。
• 不携带幂等键（ServerChan 兼容旧调用）：每次请求独立投递，至少一次语义——在结果未知时盲目重试可能产生重复通知，需要去重请务必携带幂等键。

成功响应

{"code":0,"message":"","data":{"pushid":"8f3ad2...","readkey":"","error":"SUCCESS","errno":0,"delivery":"success"}}

通道投递失败响应

只要有一个已配置通道投递失败（网络错误、超时、HTTP 非 2xx、平台错误码、重定向），响应就是非 0 状态，不会伪装成 SUCCESS。调用方应据此重试（建议携带幂等键）：

{"code":40004,"message":"通道投递失败：webhook","data":{
  "pushid":"8f3ad2...","error":"CHANNEL_FAILED","errno":40004,"delivery":"failed",
  "results":{"webhook":{"ok":false,"status":500,"error":"http_500"}}}}

投递状态未知响应

外部投递已发生但结果未能落盘（或进程在结果落盘前崩溃）时返回，不会伪装成可安全重试的普通错误：

{"code":40006,"message":"投递结果持久化失败……","data":{
  "pushid":"8f3ad2...","error":"DELIVERY_UNKNOWN","errno":40006,"delivery":"unknown"}}

错误码

调用示例

Shell / crontab

# 每天 9:00 汇报磁盘用量
0 9 * * * curl -s "https://push.example.com/<SENDKEY>.send" \
  --data-urlencode "title=磁盘日报" \
  --data-urlencode "desp=$(df -h / | tail -1)"

Python

import requests

requests.post("https://push.example.com/<SENDKEY>.send", data={
    "title": "备份完成",
    "desp": "共写入 2.3GB，耗时 14 分钟",
})

JavaScript / Node.js

await fetch("https://push.example.com/<SENDKEY>.send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "构建成功", desp: "v2.4.0 已发布" }),
});

第三方工具

在 UptimeKuma、青龙面板、Check酱、短信转发器等工具的 ServerChan 通知配置中，把推送域名换成本站域名、SendKey 换成你的即可。

通道配置

在 控制台 的 SendKey 卡片中粘贴对应通道的 webhook 地址，保存即生效。一个 SendKey 可配置多个通道，推送时同时投递。通道配置接口严格校验：仅接受 wecom/dingtalk/feishu/webhook 四个键，值必须是字符串（空字符串表示移除该通道），未知通道名或非字符串值一律拒绝且不落盘。

企业微信群机器人（微信中可收）

• 企业微信群 → 右上角 →「群机器人」→「添加」→ 复制 webhook 地址
• 形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...

钉钉群机器人

• 钉钉群 → 群设置 →「智能群助手」→「添加机器人」→「自定义」→ 复制 webhook
• 形如 https://oapi.dingtalk.com/robot/send?access_token=...

飞书群机器人

• 飞书群 → 设置 →「群机器人」→「添加机器人」→「Custom Bot」→ 复制 webhook
• 形如 https://open.feishu.cn/open-apis/bot/v2/hook/...

自定义 Webhook

推送时会向该地址发送 POST application/json：

{"title":"标题","desp":"正文","time":"2026-01-01T08:00:00.000Z"}

可用它桥接邮件、短信、Bark 或任何云服务。

使用限制

服务配置

常用环境变量（完整列表与各配置的取值范围见 README——所有数值配置都有最小/最大值，非法值会拒绝启动）。服务按单实例运行，外部投递、管理写操作和过期清扫共用存储写锁，避免响应与数据文件状态分叉；该写锁不覆盖请求体读取，慢速客户端不会阻塞其他请求：