开发文档

Y-Send 只有一个核心接口，所有能发起 HTTP 请求的语言和工具都可以调用。

机器可读资源：/llms.txt · /openapi.json · /docs.md

快速开始

1. 打开 控制台，用懿美嘉账号登录（账号由懿美嘉中央账号服务统一管理，无需在 Y-Send 单独注册），首次登录系统会自动分配一个 SendKey。

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

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

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

发送消息

GET 或 POST  https://send.yimeijia.cc/<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，同样不会重复投递。幂等记录重启后仍有效，随消息一起保留：在该账号最近 200 条消息（全局最近 2000 条）范围内有效，更早的记录被淘汰后，同一个键会被当作新请求。
• 不携带幂等键：每次请求独立投递，至少一次语义——在结果未知时盲目重试可能产生重复通知，需要去重请务必携带幂等键。

成功响应

{"code":0,"message":"","data":{"pushid":"8f3ad2...","readkey":"aB3x9K...","readUrl":"https://send.yimeijia.cc/r?id=8f3ad2...&readkey=aB3x9K...","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":{"page":{"ok":true},"webhook":{"ok":false,"status":500,"error":"http_500"}}}}

投递状态未知响应

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

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

消息详情页

GET  https://send.yimeijia.cc/r?id=<PUSHID>&readkey=<READKEY>

无需登录的公开页面：凭 pushid + readkey 直接阅读一条消息的完整内容，适合把链接发给没有控制台账号的同事或粘贴到工单里。

• 有效期等于消息保留期：链接没有独立过期时间，消息被保留策略淘汰（默认每用户 200 条、全局 2000 条）或其 SendKey 被删除后，链接立即失效。
• 纯文本呈现：正文以纯文本展示，不渲染 Markdown，所有内容经 HTML 转义，页面脚本被 CSP 完全禁用。
• 不被搜索引擎收录：响应带 X-Robots-Tag: noindex，且 /r 在 robots.txt 中为 Disallow。
• 防枚举：未知 id、错误 readkey、缺参数一律返回完全相同的 404 页面，无法用来探测消息是否存在。

状态回查

GET  https://send.yimeijia.cc/push?id=<PUSHID>&readkey=<READKEY>[&full=1]

无需登录的公开端点，凭 pushid + readkey 查询一条消息的投递状态，适合在无登录态的脚本/看板里做结果回查。

成功响应

{"code":0,"message":"","data":{
  "pushid":"8f3ad2...","createdAt":1757..., "title":"磁盘日报",
  "delivery":"success","results":{"page":"stored"},
  "readUrl":"https://send.yimeijia.cc/r?id=8f3ad2...&readkey=aB3x9K..."}}
// 加 full=1 时 data 里多一个 desp 字段

错误码

判断成败：能解析出响应 JSON 就以 code 为准（0 才是成功）；超时、网络错误等拿不到响应时按「结果未知」处理，用同一个幂等键重试，不会重复通知。

判定顺序：SendKey 不存在（40001）→ IP+SendKey 限流（40005）→ 幂等键非法（40007）→ 同一幂等键已有记录则直接重放 → 账号每日额度（40003）→ 单 SendKey 每分钟上限（40002）。被 40001 / 40002 / 40003 / 40005 / 40007 拒绝的请求都不写消息、不计数、不投递；其中 40002 / 40003 / 40005 是限流，不要立即重试。

调用示例

Shell / crontab

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

Python

import requests

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

JavaScript / Node.js

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

第三方工具

在监控面板、自动化平台、短信转发器等工具的 Webhook / 自定义通知设置中，把请求地址填成 https://send.yimeijia.cc/<SENDKEY>.send，用 GET 参数或 POST JSON 传 title 和 desp 即可。

通道配置

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

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

• 企业微信群 → 右上角 →「群机器人」→「添加」→ 复制 webhook 地址
• 形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...
• 单条消息最长 4096 字节（含标题，企业微信官方限制），超出时 Y-Send 自动截断正文并附「查看全文」链接；每个机器人每分钟最多 20 条

钉钉群机器人

• 钉钉群 → 群设置 →「智能群助手」→「添加机器人」→「自定义」→ 复制 webhook
• 形如 https://oapi.dingtalk.com/robot/send?access_token=...
• 安全设置必须选一项：推荐「IP 地址（段）」填 14.103.66.221，或「自定义关键词」（之后每条消息的标题或正文都得包含这个词）；不要选「加签」——Y-Send 推送不带签名，选了会全部失败

飞书群机器人

• 飞书群 → 设置 →「群机器人」→「添加机器人」→「Custom Bot」→ 复制 webhook
• 形如 https://open.feishu.cn/open-apis/bot/v2/hook/...
• 请求体最大 20 KB（飞书官方限制），超出时 Y-Send 自动截断正文并附「查看全文」链接；每个机器人每分钟 100 次、每秒 5 次
• 安全设置可以不开；要开请选「IP 白名单」填 14.103.66.221 或关键词，不要开「签名校验」（原因同钉钉）

自定义 Webhook

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

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

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

使用限制

退款政策

Pro 订阅为虚拟服务，一经开通不支持退款；支付或到账如有问题，请联系管理员处理。

服务配置

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

给 AI 助手的接入说明

想让 Claude Code / Cursor 等 AI 助手替你完成接入，把下面这段提示词原样贴给它即可：

你是接入 Y-Send 消息推送服务的助手。请按以下约定帮我完成接入：

1. 端点：GET 或 POST https://send.yimeijia.cc/<SENDKEY>.send，
   支持 GET query、POST 表单、POST JSON 三种传参方式。
2. 参数：
   - title：消息标题，最长 32 字符，超长截断，缺省为「无标题」。
   - desp：消息正文，最长 32768 字符，企业微信 / 钉钉通道支持 Markdown。
     企业微信单条约 4KB、飞书约 20KB，超出时服务端自动截断并附「查看全文」链接，
     重要内容请放在正文前面。
   - idempotency_key：幂等键，1~128 字符、不含控制字符。
3. 能解析出响应 JSON 就读 body 的 code 判断成败，code 为 0 才是成功：业务错误是 HTTP 200
   + 非 0 code，请求格式错误是 HTTP 400/413，body 里同样有 code。拿不到响应（超时、网络错误）
   一律按「结果未知」处理，绝不能当成功。
4. 永远携带 Idempotency-Key 请求头（与 idempotency_key 参数等价，请求头优先）。超时、网络错误
   或 code 40006 时用同一个键重试，不会重复通知；code 40004（通道投递失败）用同一个键重试
   只会拿回原结果、不会重投，要重投必须换新键（等于新发一条、占一次额度），由调用方决定，
   不要自动做。40002 / 40003 / 40005 是限流，不要立即重试。
5. SendKey 一律从环境变量（如 YSEND_SENDKEY）读取：不要硬编码、不要写进日志、不要提交进仓库。
6. 批量或高频任务把多条消息合并成一条摘要再发送；每日额度按账号计（名下所有 SendKey 共享），
   不要循环逐条推送。

复制提示词