{"openapi":"3.0.3","info":{"title":"WisdomEDM Transactional Mail API","version":"1.0.0","description":"公开服务器端集成。文档不包含真实凭据。MCP另见\/developers\/mcp。"},"servers":[{"url":"https:\/\/edm.zhmj.com"}],"paths":{"\/api\/v1\/mail":{"post":{"summary":"提交单封事务邮件","operationId":"sendTransactionalMail","security":[{"ApiBearer":[]}],"description":"JSON总长最多40000字节。幂等键绑定应用和规范化内容。默认20次\/滚动小时、100次\/北京时间自然日、同一收件人5次\/滚动小时，可按应用调整。禁止将本接口当作无限制群发接口。","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MailRequest"}}}},"responses":{"200":{"description":"事务邮件提交结果；accepted不是最终送达","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MailResult"}}}},"202":{"description":"sending或unknown，必须查询\/对账，不换键重发","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MailResult"}}}},"502":{"description":"failed，服务商拒绝","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MailResult"}}}},"400":{"description":"参数错误","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"unauthorized","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"client_disabled","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"payload_too_large","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"json_required","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"mail_service_unavailable","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/mail\/status":{"get":{"summary":"查询本应用消息状态","operationId":"getTransactionalMailStatus","security":[{"ApiBearer":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"所属应用的消息状态，无正文\/收件人","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MailStatus"}}}},"404":{"description":"not_found（也用于其他应用的ID）","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"unauthorized","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"mail_service_unavailable","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/api\/v1\/mail\/supabase":{"post":{"summary":"Supabase Send Email Hook","operationId":"supabaseSendEmailHook","security":[],"description":"平台专用集成，需先配置应用与Hook共享密钥。不是Bearer发信接口。原始body最多80000字节；Standard Webhooks签名时间偏差不超过300秒。签名消息为webhook-id + 点 + webhook-timestamp + 点 + 原始body，HMAC-SHA256再Base64，头为v1,签名。禁止重序列化后验签。","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","description":"由Supabase Auth发送的Hook事件，字段以Supabase官方协议为准；包含user与email_data。不要在日志中保存验证链接或token。"}}}},"responses":{"200":{"description":"发送成功，空JSON对象"},"400":{"description":"JSON不合法"},"401":{"description":"签名错误、缺少签名或时间过期"},"413":{"description":"payload_too_large：原始请求体超过80000字节"},"503":{"description":"事件不受支持或发送不可用，返回嵌套error对象"}}}},"\/api\/email\/send":{"post":{"summary":"旧版发信（保留兼容，不建议新接入）","operationId":"legacySendEmail","deprecated":true,"security":[],"description":"使用平台配置的旧版EMAIL_API_KEYS，不接受edm_应用密钥。没有新版应用隔离状态查询\/幂等保障；新项目使用\/api\/v1\/mail。不要把密钥放在URL。","requestBody":{"required":true,"content":{"application\/x-www-form-urlencoded":{"schema":{"type":"object","required":["api_key","to","subject","html"],"properties":{"api_key":{"type":"string"},"to":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"}}}}}},"responses":{"200":{"description":"历史业务信封：code\/data\/msg。HTTP200不等于业务成功，必须检查code；失败通常为code400。"}}}}},"components":{"securitySchemes":{"ApiBearer":{"type":"http","scheme":"bearer","description":"独立应用edm_凭据，平台安全发放；不在前端使用。"}},"schemas":{"MailRequest":{"type":"object","additionalProperties":false,"required":["to","subject","html"],"properties":{"to":{"type":"string","format":"email","maxLength":254,"description":"单一有效收件地址，最多254字节，不允许换行"},"subject":{"type":"string","minLength":1,"maxLength":240,"description":"最多240个UTF-8字节，不是240个汉字；不允许CR\/LF\/NUL"},"html":{"type":"string","minLength":1,"maxLength":24000,"description":"最多24000个UTF-8字节"},"text":{"type":"string","maxLength":12000,"description":"可选，最多12000字节；省略时从HTML去标签生成"}}},"MailResult":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{32}$"},"status":{"type":"string","enum":["accepted","sending","failed","unknown"]}}},"MailStatus":{"allOf":[{"$ref":"#\/components\/schemas\/MailResult"},{"type":"object","properties":{"created_at":{"type":"integer","description":"Unix秒"},"updated_at":{"type":"integer","description":"Unix秒"}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}