# Y-Send > Y-Send 是消息推送服务：一个 HTTP 请求把消息送到企业微信 / 钉钉 / 飞书 / 自定义 Webhook。零依赖（只用 Node 内置模块），支持幂等发送。 ## 唯一发送端点 GET 或 POST https://send.yimeijia.cc/.send ```bash curl -s "https://send.yimeijia.cc/.send" \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "title=标题" \ --data-urlencode "desp=正文" ``` 支持三种传参方式：GET query、POST 表单（application/x-www-form-urlencoded）、POST JSON（application/json）。同一请求中 query 与 body 参数会合并。 ## 参数 - title：选填，字符串，最长 32 字符，超长静默截断，缺省为「无标题」。消息标题。 - desp：选填，字符串，最长 32768 字符，超长静默截断，缺省为空。消息正文，企业微信 / 钉钉通道支持 Markdown。推送到企业微信（单条 4096 字节，含标题）和飞书（请求体 20 KB）时，超出部分由服务端截断并附「查看全文」链接，重要内容请放在正文前面。 - idempotency_key：选填，字符串，1~128 字符且不含控制字符（trim 后判定）。幂等键；也可用请求头 Idempotency-Key 传递，请求头优先于该参数。同一 SendKey + 同一键的重复请求返回首次持久化结果（相同 pushid、相同 code，带 X-Idempotent-Replay: 1 响应头），绝不重复投递外部通道。 ## 响应 code 为 0 表示成功。 ⚠️ 最重要的规则：本服务所有业务错误（含超配额、限流、投递失败）也返回 HTTP 200。必须读响应 body 里的 code 字段判断成败，绝不能依据 HTTP 状态码。协议级错误才用真实 HTTP 状态码——400（请求体不是合法 JSON 对象 / 无法确定客户端地址）、404（路由不存在）、405、413（请求体超过 64 KB）——这些响应的 body 同样是 {"code":...}。所以：能解析出 JSON 就以 code 判断；超时、网络错误等拿不到响应时按「结果未知」处理，用同一个幂等键重试，绝不能当成功。 成功响应示例： ```json {"code":0,"message":"","data":{"pushid":"8f3ad2...","readkey":"...","readUrl":"https://send.yimeijia.cc/r?id=...&readkey=...","error":"SUCCESS","errno":0,"delivery":"success"}} ``` data 结构说明： - pushid：消息 ID（16 位小写 hex），用于 /push 状态回查与 /r 详情页。 - readkey：消息阅读密钥，配合 pushid 使用。 - readUrl：消息详情页完整 URL（仅公开阅读页功能开启时输出）。 - error：机器可读结果标识，成功为 "SUCCESS"，失败为 "CHANNEL_FAILED"，投递状态未知为 "DELIVERY_UNKNOWN"。 - errno：与 code 相同。 - delivery：投递状态。success（全部通道成功或仅站内保存）/ failed（结果已落盘，有通道失败）/ pending（投递结果未落盘的中间态）/ unknown（结果无法确认）。 - results：各通道投递结果（含 page 站内保存），仅失败或状态未知时携带，形如 {"page":{"ok":true},"webhook":{"ok":false,"status":500,"error":"http_500"}}；首次响应与同键重放结构一致。 ## 错误码 - 0：成功。 - 40001：sendkey 不正确或不存在。 - 40002：超过每分钟上限（单 SendKey 每分钟 50 条）。 - 40003：超过每日上限。免费版每天 5 条，Pro 每天 200 条；按账号名下所有 SendKey 当日发送量汇总判定，而非单把 SendKey 各自计数。 - 40004：通道投递失败，data.results 含各通道结果。结果已落盘：同一幂等键重试只重放该结果、不会重投；要重投必须换新键（等于新发一条、占一次每日额度），由调用方决定，不要自动做。 - 40005：请求过于频繁（IP 限流），触发按 IP+SendKey 的限流（默认 60 条/分钟）；请求未写入消息、未计数、未投递，可稍后重试。 - 40006：投递状态未知（DELIVERY_UNKNOWN）：外部通道可能已收到消息；携带相同幂等键重试不会重复投递，不要换键盲目重发。 - 40007：Idempotency-Key 非法（1~128 字符，不含控制字符）；请求未执行任何副作用，修正后可安全重试。 判定顺序：40001 → 40005 → 40007 → 同一幂等键已有记录则直接重放 → 40003 → 40002。被 40001 / 40002 / 40003 / 40005 / 40007 拒绝的请求都不写消息、不计数、不投递；40002 / 40003 / 40005 是限流，不要立即重试。 ## 查询与详情 - GET https://send.yimeijia.cc/push?id=&readkey= —— 查投递状态，返回 JSON：{code:0,data:{pushid,createdAt,title,delivery,results,readUrl}}；追加 &full=1 时 data 额外包含 desp 正文。 - GET https://send.yimeijia.cc/r?id=&readkey= —— 消息详情页（HTML）。 两者均为未鉴权公开路由，凭 query 串中的 readkey 访问；id 不存在、readkey 错误、参数缺失等情况一律返回相同的 404，不做区分。 ## 限制 - 账号每日上限：免费版 5 条 / Pro 200 条，按账号名下所有 SendKey 汇总（不是按 SendKey 各自计数），按 Asia/Shanghai 自然日重置。 - 单 SendKey 每分钟 50 条（超限返回 40002）。 - 每 IP+SendKey 每分钟 60 条（超限返回 40005）。 - 每账号最多 20 个 SendKey。 - 标题 32 字符，正文 32768 字符，请求体上限 64 KB（超限返回 HTTP 413）。 - 通道单条上限：企业微信 4096 字节（含标题）、飞书请求体 20 KB（均为平台官方限制）；超出时服务端截断正文并附「查看全文」链接，阅读页保存全文。钉钉未公开明确上限，不截断。 - 幂等记录随消息保留：在每个账号最近 200 条消息（全局最近 2000 条）范围内有效，更早的记录被淘汰后同一个键会被当作新请求。 以上为默认值，部署方可用环境变量调整，实际以目标实例控制台显示为准。 ## 给 AI 助手的规则 - 发送请求时永远携带 Idempotency-Key 请求头，避免重试导致重复打扰用户。 - 能解析出响应 JSON 就读 body 的 code 判断成败（业务错误是 HTTP 200 + 非 0 code；400 / 413 等协议错误的 body 里同样有 code）；拿不到响应按「结果未知」处理，用同一个幂等键重试。 - 40004 用同一个幂等键重试不会重投；40002 / 40003 / 40005 是限流，不要立即重试。 - 不要发明本文档未列出的参数，多余参数会被静默忽略。 - 不要把 SENDKEY 写进日志、不要提交进代码仓库、不要打印到控制台。 - 批量任务合并成一条摘要发送，尊重每天的配额。 ## 更多 - [完整文档（Markdown）](https://send.yimeijia.cc/docs.md) - [OpenAPI 3.1](https://send.yimeijia.cc/openapi.json) - [开发文档网页版](https://send.yimeijia.cc/docs)