{"openapi":"3.1.0","info":{"title":"Mailly API","version":"1.0.0","description":"Mailly 邮件服务 API：验证码、计费、事务/营销邮件发送、收件箱、联系人、用户集、Workflow 与模板。默认所有端点使用 Bearer API key 认证，标记 security: [] 的为公开端点。"},"security":[{"bearerAuth":[]}],"tags":[{"name":"public","description":"公开端点（无需 API key；部分使用独立 secret 或签名 token）"},{"name":"verification","description":"验证码发送与校验"},{"name":"billing","description":"余额、扣费与消费日志"},{"name":"sending","description":"邮件发送与发件箱"},{"name":"domains","description":"发件域名与 DNS 配置"},{"name":"inbox","description":"入站邮件与会话"},{"name":"campaigns","description":"营销 Campaign"},{"name":"contacts","description":"联系人与 Suppression"},{"name":"audiences","description":"静态用户集与动态分群"},{"name":"workflows","description":"Lifecycle Workflow 与事件"},{"name":"templates","description":"邮件模板"},{"name":"delivery","description":"投递事件与 Webhook"},{"name":"governance","description":"退订、偏好与 suppression"},{"name":"agents","description":"收件箱 Agent 对话"},{"name":"admin","description":"管理员端点（需 admin 角色）"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Mailly API key（Authorization: Bearer <key>）"}},"schemas":{},"parameters":{}},"paths":{"/verify-code-login":{"post":{"tags":["public"],"security":[],"summary":"验证码登录","description":"邮箱验证码登录，成功后写入 Better Auth session cookie（新用户自动注册）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"登录邮箱"},"code":{"type":"string","description":"验证码"}},"additionalProperties":{},"required":["email","code"]}}}},"responses":{"200":{"description":"登录成功（Set-Cookie 写入 session）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":{}}}}},"400":{"description":"请求体错误或验证码不匹配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"验证码不存在或已过期","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/cli/auth/init":{"post":{"tags":["public"],"security":[],"summary":"CLI 设备授权初始化","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceToken":{"type":"string","description":"CLI 生成的 32-128 位十六进制 token"}},"additionalProperties":{},"required":["deviceToken"]}}}},"responses":{"200":{"description":"已登记待授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deviceToken":{"type":"string"},"expiresIn":{"type":"number"},"interval":{"type":"number"}},"required":["success","deviceToken","expiresIn","interval"],"additionalProperties":{}}}}},"400":{"description":"deviceToken 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"deviceToken 已被使用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/cli/auth/poll":{"post":{"tags":["public"],"security":[],"summary":"CLI 轮询授权状态","description":"pending 返回 202，approved 返回 apiKey 并一次性删除 KV 记录，过期返回 410。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceToken":{"type":"string","description":"CLI 生成的 32-128 位十六进制 token"}},"additionalProperties":{},"required":["deviceToken"]}}}},"responses":{"200":{"description":"已批准（返回 apiKey）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"apiKey":{"type":"string"},"email":{"type":"string"},"error":{"type":"string"}},"required":["success"],"additionalProperties":{}}}}},"202":{"description":"等待用户授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"apiKey":{"type":"string"},"email":{"type":"string"},"error":{"type":"string"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"deviceToken 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"apiKey":{"type":"string"},"email":{"type":"string"},"error":{"type":"string"}},"required":["success"],"additionalProperties":{}}}}},"410":{"description":"授权请求不存在或已过期","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"apiKey":{"type":"string"},"email":{"type":"string"},"error":{"type":"string"}},"required":["success"],"additionalProperties":{}}}}}}}},"/cli/auth/approve":{"post":{"tags":["public"],"security":[],"summary":"网页批准 CLI 授权","description":"需要 Better Auth session cookie（非 API key）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceToken":{"type":"string","description":"CLI 生成的 32-128 位十六进制 token"}},"required":["deviceToken"],"additionalProperties":{}}}}},"responses":{"200":{"description":"已批准","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"email":{"type":"string"}},"required":["success","email"],"additionalProperties":{}}}}},"400":{"description":"请求体或 deviceToken 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未登录","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"授权请求已被处理","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"410":{"description":"授权请求不存在或已过期","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"账户尚未生成 API Key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/unsubscribe":{"get":{"tags":["public"],"security":[],"summary":"托管退订确认页","description":"邮件页脚退订链接落地页，渲染确认表单。","parameters":[{"schema":{"type":"string","description":"签名退订 token"},"required":true,"description":"签名退订 token","name":"token","in":"query"}],"responses":{"200":{"description":"退订确认页","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"链接无效或过期","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"tags":["public"],"security":[],"summary":"执行退订（含 RFC 8058 one-click）","description":"接收 `token`（JSON body、表单字段或 query）。成功后写入 suppression 并记录 unsubscribed 投递事件。","responses":{"200":{"description":"退订成功页","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"链接无效或过期","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/provider-events/ses":{"post":{"tags":["public"],"security":[],"summary":"AWS SNS/SES 投递事件入口","description":"使用独立 secret 鉴权（`x-mailly-provider-secret` 头或 `?token=`）；处理 SNS SubscriptionConfirmation 与 SES 投递/退订事件。","parameters":[{"schema":{"type":"string"},"required":false,"name":"token","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"Type":{"type":"string"}},"additionalProperties":{},"description":"AWS SNS envelope"}},"text/plain":{"schema":{"type":"string","description":"AWS SNS envelope (JSON text, as sent by SNS)"}}}},"responses":{"200":{"description":"事件已处理","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"matched":{"type":"number"},"duplicates":{"type":"number"},"confirmed":{"type":"boolean"},"ignored":{"type":"boolean"},"reason":{"type":"string"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"载荷非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"provider secret 不匹配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"SNS 确认请求失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"未配置或事件暂不可处理（稍后重试）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbound-email/validate":{"post":{"tags":["public"],"security":[],"summary":"校验收件地址是否已分配","description":"RCPT TO 阶段调用；鉴权走 `x-mailly-inbound-secret` 头。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"待校验收件地址"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"校验结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accepted":{"type":"boolean","description":"是否存在对应收件箱"}},"required":["success","accepted"],"additionalProperties":{}}}}},"400":{"description":"请求非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"inbound secret 不匹配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"未配置 ingestion","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbound-email/ingest":{"post":{"tags":["public"],"security":[],"summary":"入站邮件落库（raw MIME）","description":"DATA 阶段提交；`authentication` 为上游 SMTP 服务产出的鉴权元数据（sourceIp/helo/spf/dkim/dmarc/policy/results），缺失或非法返回 503 供上游重试。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"信封发件人"},"to":{"type":"array","items":{"type":"string"},"description":"RCPT TO 收件人列表"},"rawBase64":{"type":"string","description":"base64 编码的完整 MIME"},"authentication":{"description":"SMTP 鉴权元数据"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"入库结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"stored":{"type":"number","description":"新入库收件人数"},"duplicates":{"type":"number","description":"重复/竞争跳过的收件人数"}},"required":["success","stored","duplicates"],"additionalProperties":{}}}}},"400":{"description":"请求非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"inbound secret 不匹配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"没有匹配的收件箱","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"413":{"description":"邮件超过 10 MiB","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"未配置 / 鉴权元数据缺失或临时不可用（上游应重试）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/catalog":{"get":{"tags":["billing"],"summary":"查看 Credits 充值包","security":[],"responses":{"200":{"description":"公开充值包与开放状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"enabled":{"type":"boolean"},"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"credits":{"type":"integer"},"amount":{"type":"integer"},"currency":{"type":"string"},"kind":{"type":"string","enum":["credits","usage"]}},"required":["id","name","credits","amount","currency","kind"]}}},"required":["success","enabled","packs"],"additionalProperties":{}}}}},"503":{"description":"充值配置不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/checkout":{"post":{"tags":["billing"],"summary":"创建 Credits 充值订单","parameters":[{"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{16,100}$"},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pack_id":{"type":"string","minLength":1,"maxLength":40}},"required":["pack_id"]}}}},"responses":{"200":{"description":"Stripe Checkout 地址","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"url":{"type":"string"}},"required":["success","id","url"],"additionalProperties":{}}}}},"409":{"description":"充值请求冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"充值不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/purchases":{"get":{"tags":["billing"],"summary":"查询当前账户最近 50 笔充值","responses":{"200":{"description":"充值记录","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"purchases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"pack_name":{"type":"string"},"credits":{"type":"integer"},"amount":{"type":"integer"},"currency":{"type":"string"},"kind":{"type":"string","enum":["credits","usage"]},"status":{"type":"string","enum":["pending","paid","expired","failed"]},"created_at":{"type":"integer"},"paid_at":{"type":["integer","null"]}},"required":["id","pack_name","credits","amount","currency","kind","status","created_at","paid_at"]}}},"required":["success","purchases"],"additionalProperties":{}}}}}}}},"/billing/purchases/{id}/reconcile":{"post":{"tags":["billing"],"summary":"向 Stripe 核对当前账户的付款状态","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"核对后的充值状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"purchase":{"type":"object","properties":{"id":{"type":"string"},"pack_name":{"type":"string"},"credits":{"type":"integer"},"amount":{"type":"integer"},"currency":{"type":"string"},"kind":{"type":"string","enum":["credits","usage"]},"status":{"type":"string","enum":["pending","paid","expired","failed"]},"created_at":{"type":"integer"},"paid_at":{"type":["integer","null"]}},"required":["id","pack_name","credits","amount","currency","kind","status","created_at","paid_at"]}},"required":["success","purchase"],"additionalProperties":{}}}}},"404":{"description":"充值不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"暂时无法核对付款","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/purchases/{id}":{"get":{"tags":["billing"],"summary":"查询当前账户的充值状态","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"充值状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"purchase":{"type":"object","properties":{"id":{"type":"string"},"pack_name":{"type":"string"},"credits":{"type":"integer"},"amount":{"type":"integer"},"currency":{"type":"string"},"kind":{"type":"string","enum":["credits","usage"]},"status":{"type":"string","enum":["pending","paid","expired","failed"]},"created_at":{"type":"integer"},"paid_at":{"type":["integer","null"]}},"required":["id","pack_name","credits","amount","currency","kind","status","created_at","paid_at"]}},"required":["success","purchase"],"additionalProperties":{}}}}},"404":{"description":"充值不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/entitlements":{"get":{"tags":["billing"],"summary":"查看当前套餐、本期用量与历史 Credits","responses":{"200":{"description":"套餐与用量","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"entitlements":{"type":"object","properties":{"plan":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"period_start":{"type":"integer"},"period_end":{"type":"integer"},"cancel_at_period_end":{"type":"boolean"}},"required":["id","name","status","period_start","period_end","cancel_at_period_end"]},"emails":{"type":["object","null"],"properties":{"used":{"type":"integer"},"quota":{"type":"integer"}},"required":["used","quota"]},"mailboxes":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}},"required":["used","limit"]},"custom_domains":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}},"required":["used","limit"]},"legacy_credits":{"type":"integer"},"model":{"type":"object","properties":{"billing_enforced":{"type":"boolean"},"balance_nano":{"type":"integer"},"period_start":{"type":"integer"},"period_cost_nano":{"type":"integer"},"period_charged_nano":{"type":"integer"},"executions":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":["integer","null"]}},"required":["used","limit"]}},"required":["billing_enforced","balance_nano","period_start","period_cost_nano","period_charged_nano","executions"]}},"required":["plan","emails","mailboxes","custom_domains","legacy_credits","model"]},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mailboxes":{"type":"integer"},"custom_domains":{"type":"integer"},"monthly_emails":{"type":"integer"},"available":{"type":"boolean"}},"required":["id","name","mailboxes","custom_domains","monthly_emails","available"]}}},"required":["success","entitlements","plans"],"additionalProperties":{}}}}}}}},"/billing/subscription/checkout":{"post":{"tags":["billing"],"summary":"创建套餐订阅 Checkout","parameters":[{"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{16,100}$"},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_id":{"type":"string","minLength":1,"maxLength":40}},"required":["plan_id"]}}}},"responses":{"200":{"description":"Stripe Checkout 地址","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"url":{"type":"string"}},"required":["success","id","url"],"additionalProperties":{}}}}},"409":{"description":"订阅请求冲突或已有套餐","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"订阅不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/subscription/checkouts/{id}/reconcile":{"post":{"tags":["billing"],"summary":"向 Stripe 核对当前账户的订阅付款","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"核对后的订阅 Checkout 状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"checkout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","complete","expired"]}},"required":["id","status"]}},"required":["success","checkout"],"additionalProperties":{}}}}},"404":{"description":"订阅请求不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"暂时无法核对","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/billing/subscription/portal":{"post":{"tags":["billing"],"summary":"打开 Stripe 账单管理（取消、换卡、发票）","responses":{"200":{"description":"账单管理地址","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"url":{"type":"string"}},"required":["success","url"],"additionalProperties":{}}}}},"404":{"description":"还没有订阅记录","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"账单管理不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/send-code":{"post":{"tags":["verification"],"summary":"发送验证码","description":"向指定邮箱发送 6 位验证码（5 分钟有效），消耗 1 积分。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"收件邮箱"}},"additionalProperties":{},"required":["email"]}}}},"responses":{"200":{"description":"验证码发送成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":{}}}}},"400":{"description":"请求体或邮箱格式错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"发送失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/verify-code":{"post":{"tags":["verification"],"summary":"校验验证码","description":"校验邮箱验证码，消耗 1 积分。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"待校验邮箱"},"code":{"type":"string","description":"6 位验证码"}},"additionalProperties":{},"required":["email","code"]}}}},"responses":{"200":{"description":"校验通过","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":{}}}}},"400":{"description":"请求体错误或验证码不匹配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"验证码不存在或已过期","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/balance":{"get":{"tags":["billing"],"summary":"查询余额","responses":{"200":{"description":"当前积分余额","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"balance":{"type":"number"}},"required":["success","balance"],"additionalProperties":{}}}}},"500":{"description":"认证上下文缺失","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/deduct":{"post":{"tags":["billing"],"summary":"手动扣费","description":"从当前 API key 余额扣除 1 积分；可选 JSON body 提供 targetEmail 与 idempotencyKey。","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"targetEmail":{"type":"string","description":"关联目标邮箱（可选）"},"idempotencyKey":{"type":"string","description":"幂等键（可选）"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"扣费成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"balance":{"type":"number"}},"required":["success","message","balance"],"additionalProperties":{}}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"扣费失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/logs":{"get":{"tags":["billing"],"summary":"查询消费日志","parameters":[{"schema":{"type":"string","description":"每页条数，默认 50，最大 100"},"required":false,"description":"每页条数，默认 50，最大 100","name":"limit","in":"query"},{"schema":{"type":"string","description":"偏移量，默认 0"},"required":false,"description":"偏移量，默认 0","name":"offset","in":"query"}],"responses":{"200":{"description":"消费日志","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"logs":{"type":"array","items":{"type":"object","properties":{"log_id":{"type":"string"},"timestamp":{"type":"string"},"amount_deducted":{"type":"number"},"caller_email":{"type":"string"},"target_email":{"type":["string","null"]},"from_email":{"type":["string","null"]},"subject":{"type":["string","null"]},"send_mode":{"type":["string","null"]},"recipient_count":{"type":["number","null"]},"task_id":{"type":["string","null"]}},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","logs","limit","offset"],"additionalProperties":{}}}}},"500":{"description":"查询日志失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/logs/download":{"get":{"tags":["billing"],"summary":"下载消费日志 CSV","responses":{"200":{"description":"CSV 文件下载","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"未认证","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"生成下载失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/send-email":{"post":{"tags":["sending"],"summary":"发送邮件（事务/营销）","description":"治理后透传队列服务；支持单发、批量、受众、campaign、定时、模板变量。按收件人扣费。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"email":{"type":"string"},"externalId":{"description":"业务侧联系人 ID，覆盖已存联系人的 external_id","type":"string"}},"required":["email"]}]}}],"description":"收件人：邮箱、邮箱数组或 {email, externalId} 对象数组；与 audience/campaignKey 三选一"},"audience":{"type":"object","properties":{},"additionalProperties":{},"description":"受众过滤 {include, exclude}"},"campaignKey":{"type":"string","description":"使用冻结受众的 campaign key"},"campaignName":{"type":"string"},"subject":{"type":"string","description":"邮件主题"},"html":{"type":"string","description":"HTML 正文"},"text":{"type":"string","description":"纯文本正文"},"fromEmail":{"type":"string","description":"发件地址（须为已验证发件域）"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"cc":{"type":"string"},"bcc":{"type":"string"},"topic":{"type":"string","description":"退订/频控话题"},"emailType":{"type":"string","enum":["transactional","lifecycle","marketing"]},"dryRun":{"type":"boolean","description":"只校验不投递"},"testSend":{"type":"boolean"},"scheduledAt":{"type":"number","description":"Unix 秒级定时发送"},"frequencyCapDays":{"type":"number"},"frequencyCapMax":{"type":"number"},"topicExclusionDays":{"type":"number"},"recipientReason":{"type":"string"},"templateKey":{"type":"string"},"templateVersion":{"type":"number"},"sourceApp":{"type":"string"},"businessGoal":{"type":"string"},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"messageId":{"type":"string"},"inReplyTo":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"attachments":{"type":"array","items":{}},"variables":{"type":"object","additionalProperties":{},"description":"{{var}} 行内模板变量"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"发送结果（由 Queue 服务透传，JSON）"},"400":{"description":"请求体非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"认证上下文缺失或服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"上游发送服务错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/smtp-auth":{"post":{"tags":["sending"],"summary":"SMTP 凭据校验","description":"验证 username 是否为当前 API key 绑定的邮箱，用于 SMTP 发件登录。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"SMTP 用户名（邮箱）"}},"additionalProperties":{},"required":["username"]}}}},"responses":{"200":{"description":"认证成功","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean"},"username":{"type":"string"},"error":{"type":"string"}},"required":["authenticated"],"additionalProperties":{}}}}},"400":{"description":"缺少有效 username","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean"},"username":{"type":"string"},"error":{"type":"string"}},"required":["authenticated"],"additionalProperties":{}}}}},"403":{"description":"凭据无效","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean"},"username":{"type":"string"},"error":{"type":"string"}},"required":["authenticated"],"additionalProperties":{}}}}}}}},"/email-status/{taskId}":{"get":{"tags":["sending"],"summary":"查询批量任务状态","description":"透传 Queue 服务的批量发送任务状态。","parameters":[{"schema":{"type":"string","description":"批量任务 ID"},"required":true,"description":"批量任务 ID","name":"taskId","in":"path"}],"responses":{"200":{"description":"任务状态（由 Queue 服务透传，JSON）"},"400":{"description":"缺少 taskId","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"查询任务状态失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains":{"get":{"tags":["domains"],"summary":"发件域名列表","description":"默认只返回可发件域名（本 workspace verified 及平台默认域）；`include_unverified=1` 返回全部状态。","parameters":[{"schema":{"type":"string","description":"传 1 返回全部域名状态"},"required":false,"description":"传 1 返回全部域名状态","name":"include_unverified","in":"query"}],"responses":{"200":{"description":"域名列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"inboundMxHost":{"type":"string"},"domains":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","inboundMxHost","domains"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["domains"],"summary":"提交自定义域名申请","description":"同一域名全平台唯一；提交后等待归属审核，审核通过后可配置发件/收信。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"域名"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已提交","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"domain":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","message","domain"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"需要订阅邮箱套餐","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"403":{"description":"超出套餐域名数量","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"域名已存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"提交失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/{id}/verify-inbound":{"post":{"tags":["domains"],"summary":"校验收信 MX 配置","description":"检查域名最高优先级 MX 是否指向 Mailly；通过后 inboundStatus=verified。","parameters":[{"schema":{"type":"string","description":"域名记录 ID"},"required":true,"description":"域名记录 ID","name":"id","in":"path"}],"responses":{"200":{"description":"校验结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"ready":{"type":"boolean"},"domain":{"type":"string"},"inboundStatus":{"type":"string"},"expectedMx":{"type":"object","properties":{},"additionalProperties":{}},"records":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"message":{"type":"string"}},"required":["success","ready","domain","inboundStatus","message"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"域名不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"归属未验证","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/{id}/setup-outbound":{"post":{"tags":["domains"],"summary":"启用 SES 发件身份","description":"创建/复用 SES 域名身份并返回需配置的 DNS 记录（DKIM CNAME、MAIL FROM MX/SPF）。","parameters":[{"schema":{"type":"string","description":"域名记录 ID"},"required":true,"description":"域名记录 ID","name":"id","in":"path"}],"responses":{"200":{"description":"发件配置状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"ready":{"type":"boolean"},"domain":{"type":"string"},"outboundStatus":{"type":"string"}},"required":["success","ready","domain","outboundStatus"],"additionalProperties":{}}}}},"400":{"description":"请求非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"域名不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"归属未验证或已被拒","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"SES 上游错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"SES 服务不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/{id}/verify-outbound":{"post":{"tags":["domains"],"summary":"校验 SES 发件记录","description":"向 SES 查询 DKIM/身份验证状态并落库。","parameters":[{"schema":{"type":"string","description":"域名记录 ID"},"required":true,"description":"域名记录 ID","name":"id","in":"path"}],"responses":{"200":{"description":"校验结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"ready":{"type":"boolean"},"domain":{"type":"string"},"outboundStatus":{"type":"string"}},"required":["success","ready","domain","outboundStatus"],"additionalProperties":{}}}}},"400":{"description":"请求非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"域名不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"归属未验证/未启用发件/已被拒","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"SES 上游错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"SES 服务不可用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/{id}/apply-dns":{"post":{"tags":["domains"],"summary":"一键写入 DNS 记录","description":"用（已保存或本次传入的）Cloudflare Token 把 Mailly 所需 DNS 记录直接写入用户 zone；幂等，冲突记录不覆盖。body 可省略。","parameters":[{"schema":{"type":"string","description":"域名记录 ID"},"required":true,"description":"域名记录 ID","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"目前仅支持 cloudflare"},"scope":{"type":"string","enum":["outbound","inbound","all"],"description":"默认 all"},"apiToken":{"type":"string","description":"本次使用的 Cloudflare Token（优先于已保存的）"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"DNS 写入结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"请求非法或未保存 Token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"域名不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"归属未验证/记录冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"写入失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"SES/Cloudflare 上游错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"加密密钥未配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/admin/all":{"get":{"tags":["admin"],"summary":"全部域名申请（管理员）","responses":{"200":{"description":"域名列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"domains":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","domains"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"403":{"description":"需要 admin 权限","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sender-domains/admin/{id}":{"patch":{"tags":["admin"],"summary":"审批域名归属/发件状态（管理员）","description":"独立审批 ownershipStatus 与 outboundStatus；旧 status 字段兼容：会同时更新两项状态。","parameters":[{"schema":{"type":"string","description":"域名记录 ID"},"required":true,"description":"域名记录 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["verified","rejected"],"description":"旧兼容字段，勿与新字段同传"},"ownershipStatus":{"type":"string","enum":["verified","rejected"]},"outboundStatus":{"type":"string","enum":["not_configured","pending","verified","rejected"]}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已审批","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"domain":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","message","domain"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"403":{"description":"需要 admin 权限","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"域名记录不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"状态冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"审批失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/dns-provider/cloudflare":{"get":{"tags":["domains"],"summary":"Cloudflare Token 状态","description":"只返回 token 短后缀提示，不返回 token 本身。","responses":{"200":{"description":"Token 状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"object","properties":{"provider":{"type":"string"},"configured":{"type":"boolean"},"tokenHint":{"type":["string","null"]},"updatedAt":{"type":["number","null"]}},"required":["provider","configured","tokenHint","updatedAt"],"additionalProperties":{}}},"required":["success","status"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"put":{"tags":["domains"],"summary":"保存 Cloudflare API Token","description":"保存前用 Cloudflare 官方接口校验 token 有效性（需 Zone→DNS→Edit 权限），加密落库。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiToken":{"type":"string","description":"Cloudflare API Token"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"Token 已保存","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status":{"type":"object","properties":{"provider":{"type":"string"},"configured":{"type":"boolean"},"tokenHint":{"type":["string","null"]},"updatedAt":{"type":["number","null"]}},"required":["provider","configured","tokenHint","updatedAt"],"additionalProperties":{}}},"required":["success","status"],"additionalProperties":{}}}}},"400":{"description":"token 缺失或 Cloudflare 校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"保存失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"加密密钥未配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["domains"],"summary":"删除 Cloudflare Token","responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status":{"type":"object","properties":{"provider":{"type":"string"},"configured":{"type":"boolean"},"tokenHint":{"type":["string","null"]},"updatedAt":{"type":["number","null"]}},"required":["provider","configured","tokenHint","updatedAt"],"additionalProperties":{}}},"required":["success","status"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/operations-overview":{"get":{"tags":["billing"],"summary":"运营总览计数","description":"返回 workspace 维度的未读会话数、sends、活跃 Campaign、可用发件域名等计数。","parameters":[{"schema":{"type":"string","description":"非负 Unix 秒时间戳，统计该时间之后的 sends"},"required":true,"description":"非负 Unix 秒时间戳，统计该时间之后的 sends","name":"since","in":"query"}],"responses":{"200":{"description":"总览计数","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"stats":{"type":"object","properties":{"unreadThreads":{"type":"number"},"sendsSince":{"type":"number"},"activeCampaigns":{"type":"number"},"outboundDomains":{"type":"number"}},"required":["unreadThreads","sendsSince","activeCampaigns","outboundDomains"],"additionalProperties":{}}},"required":["success","stats"],"additionalProperties":{}}}}},"400":{"description":"since 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"统计失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sent-messages":{"get":{"tags":["sending"],"summary":"已发送消息列表","description":"按 workspace 隔离；支持 source/status/deliveryStatus 枚举过滤，recipient/sender/subject 按 match 精确或模糊匹配，q 跨字段模糊（不含正文），since/until 限定发送时间。","parameters":[{"schema":{"type":"string","description":"默认 50，最大 200"},"required":false,"description":"默认 50，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"来源：api, web, campaign, workflow, template_test, inbox_reply"},"required":false,"description":"来源：api, web, campaign, workflow, template_test, inbox_reply","name":"source","in":"query"},{"schema":{"type":"string","description":"传输状态：reserved, queued, sending, sent, skipped, failed"},"required":false,"description":"传输状态：reserved, queued, sending, sent, skipped, failed","name":"status","in":"query"},{"schema":{"type":"string","description":"投递状态：accepted, queued, sent, delivered, deferred, soft_bounced, hard_bounced, complained, unsubscribed, link_clicked"},"required":false,"description":"投递状态：accepted, queued, sent, delivered, deferred, soft_bounced, hard_bounced, complained, unsubscribed, link_clicked","name":"deliveryStatus","in":"query"},{"schema":{"type":"string","description":"收件人邮箱，匹配方式见 match"},"required":false,"description":"收件人邮箱，匹配方式见 match","name":"recipient","in":"query"},{"schema":{"type":"string","description":"发件人邮箱，匹配方式见 match"},"required":false,"description":"发件人邮箱，匹配方式见 match","name":"sender","in":"query"},{"schema":{"type":"string","description":"主题，匹配方式见 match"},"required":false,"description":"主题，匹配方式见 match","name":"subject","in":"query"},{"schema":{"type":"string","description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）"},"required":false,"description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）","name":"match","in":"query"},{"schema":{"type":"string","description":"发送时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"发送时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"since","in":"query"},{"schema":{"type":"string","description":"发送时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"发送时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"until","in":"query"},{"schema":{"type":"string"},"required":false,"name":"campaignKey","in":"query"},{"schema":{"type":"string"},"required":false,"name":"taskId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"providerMessageId","in":"query"},{"schema":{"type":"string","description":"收件人/发件人/主题/message_id 模糊搜索"},"required":false,"description":"收件人/发件人/主题/message_id 模糊搜索","name":"q","in":"query"}],"responses":{"200":{"description":"消息列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["success","messages","total","limit","offset","hasMore"],"additionalProperties":{}}}}},"400":{"description":"枚举过滤值或搜索参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/sent-messages/{messageId}":{"get":{"tags":["sending"],"summary":"已发送消息详情（含关联投递事件）","parameters":[{"schema":{"type":"string","description":"message_id"},"required":true,"description":"message_id","name":"messageId","in":"path"}],"responses":{"200":{"description":"消息详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"object","properties":{},"additionalProperties":{}},"events":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","message","events"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"消息不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns":{"post":{"tags":["campaigns"],"summary":"创建/准备 Campaign（草稿冻结）","description":"按 campaignKey 幂等：已存在时校验内容一致（不一致 409）。marketing 类型需先配置 Marketing Footer。`audience` 提供时冻结受众快照。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaignKey":{"type":"string"},"name":{"type":"string"},"emailType":{"type":"string","enum":["transactional","lifecycle","marketing"],"description":"默认 marketing"},"senderEmail":{"type":"string"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"topic":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"frequencyCapDays":{"type":"number"},"frequencyCapMax":{"type":"number"},"topicExclusionDays":{"type":"number"},"recipientReason":{"type":"string"},"templateKey":{"type":"string"},"templateVersion":{"type":"number"},"audienceDefinition":{},"audience":{"type":"object","properties":{},"additionalProperties":{},"description":"冻结受众选择条件"},"sourceApp":{"type":"string"},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"businessGoal":{"type":"string"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}},"audienceSnapshot":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["success","campaign","audienceSnapshot"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"campaignKey 冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["campaigns"],"summary":"Campaign 列表","parameters":[{"schema":{"type":"string","description":"默认 50，最大 100"},"required":false,"description":"默认 50，最大 100","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Campaign 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaigns":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","campaigns","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/contact-history":{"get":{"tags":["campaigns"],"summary":"按收件人查 Campaign 投递历史","parameters":[{"schema":{"type":"string","description":"收件人邮箱"},"required":false,"description":"收件人邮箱","name":"email","in":"query"},{"schema":{"type":"string","description":"默认 50，最大 200"},"required":false,"description":"默认 50，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"投递历史","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"email":{"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","email","history","limit","offset"],"additionalProperties":{}}}}},"400":{"description":"缺少 email","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}":{"get":{"tags":["campaigns"],"summary":"Campaign 详情（漏斗 + 报表 + 受众快照）","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"Campaign 详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}},"recipientCounts":{"type":"object","additionalProperties":{"type":"number"}},"deliveryCounts":{"type":"object","additionalProperties":{"type":"number"}},"openedCount":{"type":"number"},"report":{"type":["object","null"],"properties":{},"additionalProperties":{}},"audienceSnapshot":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["success","campaign","recipientCounts","deliveryCounts","openedCount","report","audienceSnapshot"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/audience":{"get":{"tags":["campaigns"],"summary":"Campaign 冻结受众成员","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"},{"schema":{"type":"string","description":"默认 100，最大 500"},"required":false,"description":"默认 100，最大 500","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"受众快照与成员","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"snapshot":{"type":"object","properties":{},"additionalProperties":{}},"members":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","snapshot","members","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/recipients":{"get":{"tags":["campaigns"],"summary":"Campaign 收件人列表","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"默认 100，最大 500"},"required":false,"description":"默认 100，最大 500","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"收件人列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaignKey":{"type":"string"},"recipients":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","campaignKey","recipients","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/recipients.csv":{"get":{"tags":["campaigns"],"summary":"导出收件人 CSV","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"CSV 文件","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/content":{"patch":{"tags":["campaigns"],"summary":"暂停期间改稿","description":"更新 subject/html/text；已入队未投递的消息恢复时按新 content_revision 重建。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"html":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"changed":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}},"deferredRecipientCount":{"type":"number"}},"required":["success","changed","campaign","deferredRecipientCount"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许改稿","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/resend-unsent":{"post":{"tags":["campaigns"],"summary":"一键补发失败收件人","description":"仅 sending 状态可用；重发 failed 收件人并带上冻结受众中未占用成功的成员。`dryRun` 只返回待补发清单。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"补发结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"resend":{"type":"boolean"},"campaignKey":{"type":"string"},"unsentCount":{"type":"number"}},"required":["success","campaignKey","unsentCount"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"仅 sending 可补发","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"认证上下文缺失","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"上游发送服务错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/pause":{"post":{"tags":["campaigns"],"summary":"pause Campaign","description":"pause/resume/cancel/complete 状态流转；cancel 会取消定时派发，cancel/complete 清理内嵌图片。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","campaign"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"流转失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/resume":{"post":{"tags":["campaigns"],"summary":"resume Campaign","description":"pause/resume/cancel/complete 状态流转；cancel 会取消定时派发，cancel/complete 清理内嵌图片。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","campaign"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"流转失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/cancel":{"post":{"tags":["campaigns"],"summary":"cancel Campaign","description":"pause/resume/cancel/complete 状态流转；cancel 会取消定时派发，cancel/complete 清理内嵌图片。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","campaign"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"流转失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/campaigns/{campaignKey}/complete":{"post":{"tags":["campaigns"],"summary":"complete Campaign","description":"pause/resume/cancel/complete 状态流转；cancel 会取消定时派发，cancel/complete 清理内嵌图片。","parameters":[{"schema":{"type":"string","description":"campaign stable key"},"required":true,"description":"campaign stable key","name":"campaignKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","campaign"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Campaign 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"流转失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/marketing-settings":{"get":{"tags":["governance"],"summary":"查询 Marketing Footer 品牌名与邮寄地址","responses":{"200":{"description":"Marketing Footer 设置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"type":["object","null"],"properties":{"brandName":{"type":"string"},"postalAddress":{"type":"string"}},"additionalProperties":{}}},"required":["success","settings"],"additionalProperties":{}}}}}}},"put":{"tags":["governance"],"summary":"配置 Marketing Footer 品牌名与邮寄地址","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandName":{"type":"string","description":"品牌名，≤200 字符，单行"},"postalAddress":{"type":"string","description":"邮寄地址，≤500 字符，最多两行"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"Marketing Footer 设置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"type":["object","null"],"properties":{"brandName":{"type":"string"},"postalAddress":{"type":"string"}},"additionalProperties":{}}},"required":["success","settings"],"additionalProperties":{}}}}},"400":{"description":"参数校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/events":{"post":{"tags":["workflows"],"summary":"上报 Workflow 事件","description":"幂等入库后触发/退出工作流；重复 event 返回 200，新事件 201。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"稳定的事件 ID（幂等键），重试必须复用"},"event_name":{"type":"string","description":"事件名（触发/退出条件匹配）"},"occurred_at":{"type":"string","description":"事件发生时间，ISO-8601"},"contact":{"type":"object","properties":{"external_contact_id":{"type":"string","description":"业务侧稳定的联系人 ID"},"email":{"type":"string","description":"联系人邮箱"},"attributes":{"description":"联系人属性，JSON 不超过 32KB","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["external_contact_id","email"],"description":"联系人"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"事件属性，JSON 不超过 64KB"}},"additionalProperties":{},"required":["event_id","event_name","occurred_at","contact"],"description":"Workflow 事件输入"}}}},"responses":{"200":{"description":"重复事件（幂等）","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"duplicate":{"type":"boolean"},"event":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","duplicate","event"],"additionalProperties":{}}}}},"201":{"description":"已受理","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"duplicate":{"type":"boolean"},"event":{"type":"object","properties":{},"additionalProperties":{}},"triggeredRunIds":{"type":"array","items":{"type":"string"}},"exitedRunIds":{"type":"array","items":{"type":"string"}}},"required":["success","duplicate","event"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"事件冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"处理失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/events/batch":{"post":{"tags":["workflows"],"summary":"批量上报 Workflow 事件","description":"body 为事件数组或 {events: [...]}，1-100 条；逐条返回结果，整体 207。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"string","description":"稳定的事件 ID（幂等键），重试必须复用"},"event_name":{"type":"string","description":"事件名（触发/退出条件匹配）"},"occurred_at":{"type":"string","description":"事件发生时间，ISO-8601"},"contact":{"type":"object","properties":{"external_contact_id":{"type":"string","description":"业务侧稳定的联系人 ID"},"email":{"type":"string","description":"联系人邮箱"},"attributes":{"description":"联系人属性，JSON 不超过 32KB","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["external_contact_id","email"],"description":"联系人"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"事件属性，JSON 不超过 64KB"}},"additionalProperties":{},"required":["event_id","event_name","occurred_at","contact"],"description":"Workflow 事件输入"}}},"additionalProperties":{}}}}},"responses":{"207":{"description":"批量结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"received":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","received","results"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/events/{eventId}":{"get":{"tags":["workflows"],"summary":"事件详情（含触发的 runs）","parameters":[{"schema":{"type":"string","description":"事件 event_id"},"required":true,"description":"事件 event_id","name":"eventId","in":"path"}],"responses":{"200":{"description":"事件详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"event":{"type":"object","properties":{},"additionalProperties":{}},"runs":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","event","runs"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"事件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/events/{eventId}/replay":{"post":{"tags":["workflows"],"summary":"重放处理失败的事件","parameters":[{"schema":{"type":"string","description":"事件 event_id"},"required":true,"description":"事件 event_id","name":"eventId","in":"path"}],"responses":{"200":{"description":"重放结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"event":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","event"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"事件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"仅 failed 事件可重放","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"处理失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts":{"get":{"tags":["contacts"],"summary":"联系人列表","parameters":[{"schema":{"type":"string","description":"默认 100，最大 200"},"required":false,"description":"默认 100，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"默认排除 deleted"},"required":false,"description":"默认排除 deleted","name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tag","in":"query"}],"responses":{"200":{"description":"联系人列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["success","contacts","limit","offset","total","hasMore"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/batch":{"post":{"tags":["contacts"],"summary":"批量创建/更新联系人","description":"body 为联系人数组或 {contacts: [...]}，1-1000 条；逐条返回结果，有失败时整体 207。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"externalId":{"type":"string"},"name":{"type":"string"},"attributes":{"type":"object","additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":{},"description":"联系人字段"}}},"additionalProperties":{}}}}},"responses":{"200":{"description":"全部成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"received":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","received","succeeded","failed","results"],"additionalProperties":{}}}}},"207":{"description":"部分失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"received":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","received","succeeded","failed","results"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/import":{"post":{"tags":["contacts"],"summary":"CSV 导入联系人","description":"Content-Type 须为 text/csv 或 application/csv，body 为 CSV 原文。","responses":{"200":{"description":"全部成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"received":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","received","succeeded","failed","results"],"additionalProperties":{}}}}},"207":{"description":"部分失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"received":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","received","succeeded","failed","results"],"additionalProperties":{}}}}},"400":{"description":"Content-Type 或 CSV 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/{externalContactId}":{"put":{"tags":["contacts"],"summary":"创建或更新联系人（upsert）","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"externalId":{"type":"string"},"name":{"type":"string"},"attributes":{"type":"object","additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":{},"description":"联系人字段"}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"created":{"type":"boolean"},"contact":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","created","contact"],"additionalProperties":{}}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"created":{"type":"boolean"},"contact":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","created","contact"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["contacts"],"summary":"联系人详情","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"}],"responses":{"200":{"description":"联系人详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contact":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","contact"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["contacts"],"summary":"软删除联系人（联动 workspace suppression）","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"suppressionId":{"type":"string"},"contact":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","suppressionId","contact"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/{externalContactId}/suppress":{"post":{"tags":["contacts"],"summary":"抑制联系人（加入 workspace suppression）","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["unsubscribed","hard_bounce","complaint","manual"]},"source":{"type":"string"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已抑制","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"suppressionId":{"type":"string"},"contact":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","suppressionId","contact"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/{externalContactId}/audiences":{"get":{"tags":["contacts"],"summary":"联系人所属受众","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"}],"responses":{"200":{"description":"受众所属关系","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"externalId":{"type":"string"},"audiences":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","externalId","audiences"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/{externalContactId}/history":{"get":{"tags":["contacts"],"summary":"联系人投递历史（含别名邮箱）","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"},{"schema":{"type":"string","description":"默认 100，最大 500"},"required":false,"description":"默认 100，最大 500","name":"limit","in":"query"}],"responses":{"200":{"description":"投递历史","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"contact":{"type":"object","properties":{},"additionalProperties":{}},"emailAliases":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"deliveries":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"campaignDeliveries":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"workflowSends":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"transactionalSends":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"}},"required":["success","contact","emailAliases","deliveries","campaignDeliveries","workflowSends","transactionalSends","limit"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/contacts/{externalContactId}/timeline":{"get":{"tags":["contacts"],"summary":"联系人事件时间线","parameters":[{"schema":{"type":"string","description":"外部联系人 stable key"},"required":true,"description":"外部联系人 stable key","name":"externalContactId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"事件时间线","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"limit":{"type":"number"},"events":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","limit","events"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences/preview":{"post":{"tags":["audiences"],"summary":"预览受众解析结果","description":"不落库地解析 {audiences, contacts, exclude…} 选择条件，返回人数与样本。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include":{"type":"object","properties":{},"additionalProperties":{}},"exclude":{"type":"object","properties":{},"additionalProperties":{}},"contacts":{"type":"array","items":{"type":"string"}},"audiences":{"type":"array","items":{"type":"string"}},"sampleLimit":{"type":"number","description":"样本数，默认 20，最大 100"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"解析结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"selection":{"type":"object","properties":{},"additionalProperties":{}},"count":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"directRecipientCount":{"type":"number"},"includedContactCount":{"type":"number"},"excludedContactCount":{"type":"number"},"audiences":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","selection","count","sample"],"additionalProperties":{}}}}},"400":{"description":"选择条件非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"引用的受众不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences":{"post":{"tags":["audiences"],"summary":"创建受众","description":"type=static 可附 members（外部联系人 ID，≤1000）；type=dynamic 必须给 filter。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"stable key"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["static","dynamic"]},"filter":{"type":"object","properties":{},"additionalProperties":{},"description":"dynamic 受众的过滤条件"},"members":{"type":"array","items":{"type":"string"},"description":"外部联系人 ID 列表（仅 static）"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audience":{"type":"object","properties":{},"additionalProperties":{}},"memberCount":{"type":"number"}},"required":["success","audience","memberCount"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"成员联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"key 已存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["audiences"],"summary":"受众列表","parameters":[{"schema":{"type":"string","description":"默认 100，最大 200"},"required":false,"description":"默认 100，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"受众列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audiences":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","audiences","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences/{audienceKey}/preview":{"get":{"tags":["audiences"],"summary":"预览已有受众的成员样本","parameters":[{"schema":{"type":"string","description":"audience stable key"},"required":true,"description":"audience stable key","name":"audienceKey","in":"path"},{"schema":{"type":"string","description":"默认 20，最大 100"},"required":false,"description":"默认 20，最大 100","name":"sampleLimit","in":"query"}],"responses":{"200":{"description":"成员预览","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audience":{"type":"object","properties":{},"additionalProperties":{}},"count":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","audience","count","sample"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences/{audienceKey}":{"get":{"tags":["audiences"],"summary":"受众详情","parameters":[{"schema":{"type":"string","description":"audience stable key"},"required":true,"description":"audience stable key","name":"audienceKey","in":"path"}],"responses":{"200":{"description":"受众详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audience":{"type":"object","properties":{},"additionalProperties":{}},"memberCount":{"type":["number","null"]}},"required":["success","audience","memberCount"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"put":{"tags":["audiences"],"summary":"更新受众","parameters":[{"schema":{"type":"string","description":"audience stable key"},"required":true,"description":"audience stable key","name":"audienceKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter":{"type":"object","properties":{},"additionalProperties":{},"description":"仅 dynamic 受众"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audience":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","audience"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["audiences"],"summary":"删除受众","parameters":[{"schema":{"type":"string","description":"audience stable key"},"required":true,"description":"audience stable key","name":"audienceKey","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences/{audienceKey}/members":{"post":{"tags":["audiences"],"summary":"添加/替换静态受众成员","parameters":[{"schema":{"type":"string","description":"audience stable key"},"required":true,"description":"audience stable key","name":"audienceKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalIds":{"type":"array","items":{"type":"string"},"description":"外部联系人 ID，≤1000"},"mode":{"type":"string","enum":["add","replace"],"description":"默认 add"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"成员已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"audienceKey":{"type":"string"},"memberCount":{"type":"number"}},"required":["success","audienceKey","memberCount"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众或联系人不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/audiences/{audienceKey}/members/{externalContactId}":{"delete":{"tags":["audiences"],"summary":"移除静态受众成员","parameters":[{"schema":{"type":"string"},"required":true,"name":"audienceKey","in":"path"},{"schema":{"type":"string","description":"外部联系人 ID"},"required":true,"description":"外部联系人 ID","name":"externalContactId","in":"path"}],"responses":{"200":{"description":"已移除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"受众/联系人/成员关系不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows":{"post":{"tags":["workflows"],"summary":"创建 Workflow（草稿）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workflowKey":{"type":"string"},"name":{"type":"string"},"definition":{"description":"工作流定义（trigger/steps/exitOn/reentry）"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","workflow"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"workflowKey 已存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["workflows"],"summary":"Workflow 列表","responses":{"200":{"description":"Workflow 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflows":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","workflows"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}":{"get":{"tags":["workflows"],"summary":"Workflow 详情（含版本历史）","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"responses":{"200":{"description":"Workflow 详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}},"versions":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","workflow","versions"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/draft":{"put":{"tags":["workflows"],"summary":"更新 Workflow 草稿定义","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"definition":{"description":"workflow 定义 JSON"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","workflow"],"additionalProperties":{}}}}},"400":{"description":"定义非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"archived 不可编辑","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/publish":{"post":{"tags":["workflows"],"summary":"发布 Workflow 新版本","description":"已发布过版本时必须给 inFlightPolicy；V1 只支持 continue。","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inFlightPolicy":{"type":"string","enum":["continue","migrate"],"description":"进行中 run 的处理策略"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已发布","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}},"versionId":{"type":"string"}},"required":["success","workflow","versionId"],"additionalProperties":{}}}}},"400":{"description":"参数非法或模板绑定校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"archived 不可发布","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/pause":{"post":{"tags":["workflows"],"summary":"pause Workflow","description":"pause/resume/archive 状态流转；archive 会终止进行中 run。","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}},"platformFailures":{"type":"array","items":{"type":"string"}}},"required":["success","workflow","platformFailures"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/resume":{"post":{"tags":["workflows"],"summary":"resume Workflow","description":"pause/resume/archive 状态流转；archive 会终止进行中 run。","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}},"platformFailures":{"type":"array","items":{"type":"string"}}},"required":["success","workflow","platformFailures"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/archive":{"post":{"tags":["workflows"],"summary":"archive Workflow","description":"pause/resume/archive 状态流转；archive 会终止进行中 run。","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"}],"responses":{"200":{"description":"已流转","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{},"additionalProperties":{}},"platformFailures":{"type":"array","items":{"type":"string"}}},"required":["success","workflow","platformFailures"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许该操作","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/runs":{"get":{"tags":["workflows"],"summary":"Workflow run 列表","parameters":[{"schema":{"type":"string","description":"workflow stable key"},"required":true,"description":"workflow stable key","name":"workflowKey","in":"path"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"默认 100，最大 200"},"required":false,"description":"默认 100，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"run 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"runs":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","runs","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/workflows/{workflowKey}/runs/{runId}":{"get":{"tags":["workflows"],"summary":"Workflow run 详情（日志 + 发送执行）","parameters":[{"schema":{"type":"string"},"required":true,"name":"workflowKey","in":"path"},{"schema":{"type":"string","description":"run ID"},"required":true,"description":"run ID","name":"runId","in":"path"}],"responses":{"200":{"description":"run 详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"run":{"type":"object","properties":{},"additionalProperties":{}},"logs":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"sends":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","run","logs","sends"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Workflow 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates":{"post":{"tags":["templates"],"summary":"创建邮件模板（草稿）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"templateKey":{"type":"string"},"name":{"type":"string"},"definition":{"description":"模板定义（from/subject/body/variables/emailType/topic 等）"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","template"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"templateKey 已存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["templates"],"summary":"模板列表","parameters":[{"schema":{"type":"string","description":"默认 100，最大 200"},"required":false,"description":"默认 100，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"模板列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"templates":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","templates","limit","offset"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}":{"get":{"tags":["templates"],"summary":"模板详情（含版本历史）","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"responses":{"200":{"description":"模板详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{},"additionalProperties":{}},"versions":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","template","versions"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}/draft":{"put":{"tags":["templates"],"summary":"更新模板草稿","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"definition":{}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","template"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"archived 不可编辑","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}/publish":{"post":{"tags":["templates"],"summary":"发布模板新版本","description":"发布前校验 from 域名验证状态与营销 Footer 配置。","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"responses":{"200":{"description":"已发布","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{},"additionalProperties":{}},"version":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","template","version"],"additionalProperties":{}}}}},"400":{"description":"发布校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"archived 不可发布","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}/render":{"post":{"tags":["templates"],"summary":"渲染模板预览","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","description":"已发布版本号"},"draft":{"type":"boolean","description":"渲染草稿（与 version 互斥）"},"locale":{"type":"string"},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":{}}}}},"responses":{"200":{"description":"渲染结果","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"templateKey":{"type":"string"},"version":{"anyOf":[{"type":"number"},{"type":"string"}]},"rendered":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","templateKey","version","rendered"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}/test-send":{"post":{"tags":["templates"],"summary":"模板测试发送","description":"以 testSend=true 走治理发送通道，计为 template_test 来源。","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","description":"已发布版本号"},"draft":{"type":"boolean","description":"渲染草稿（与 version 互斥）"},"locale":{"type":"string"},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"to":{"type":"string","description":"测试收件人"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"发送结果（由 Queue 服务透传，JSON）"},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 或版本不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/templates/{templateKey}/archive":{"post":{"tags":["templates"],"summary":"归档模板","parameters":[{"schema":{"type":"string","description":"template stable key"},"required":true,"description":"template stable key","name":"templateKey","in":"path"}],"responses":{"200":{"description":"已归档","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"template":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","template"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"Template 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/delivery-events":{"get":{"tags":["delivery"],"summary":"投递事件列表","parameters":[{"schema":{"type":"string","description":"每页数量，默认 50，最大 200"},"required":false,"description":"每页数量，默认 50，最大 200","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"campaignKey","in":"query"},{"schema":{"type":"string"},"required":false,"name":"recipientId","in":"query"},{"schema":{"type":"string","description":"外部联系人 ID"},"required":false,"description":"外部联系人 ID","name":"externalId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"messageId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"providerMessageId","in":"query"},{"schema":{"type":"string","description":"事件类型：accepted, queued, sent, delivered, opened, deferred, soft_bounced, hard_bounced, complained, unsubscribed, link_clicked"},"required":false,"description":"事件类型：accepted, queued, sent, delivered, opened, deferred, soft_bounced, hard_bounced, complained, unsubscribed, link_clicked","name":"type","in":"query"}],"responses":{"200":{"description":"事件列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"events":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["success","events","limit","offset"],"additionalProperties":{}}}}},"400":{"description":"非法的 type","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/delivery-events/{eventId}":{"get":{"tags":["delivery"],"summary":"投递事件详情","parameters":[{"schema":{"type":"string","description":"投递事件 ID"},"required":true,"description":"投递事件 ID","name":"eventId","in":"path"}],"responses":{"200":{"description":"事件详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"event":{"type":"object","properties":{},"additionalProperties":{}},"webhook":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["success","event","webhook"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"事件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/delivery-events/{eventId}/replay":{"post":{"tags":["delivery"],"summary":"重投事件的 Webhook","parameters":[{"schema":{"type":"string","description":"投递事件 ID"},"required":true,"description":"投递事件 ID","name":"eventId","in":"path"}],"responses":{"200":{"description":"已入队重投","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"eventId":{"type":"string"},"webhookStatus":{"type":"string"}},"required":["success","eventId","webhookStatus"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"事件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不允许重投","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/delivery-webhook":{"get":{"tags":["delivery"],"summary":"查询投递事件 Webhook 配置","responses":{"200":{"description":"Webhook 配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":["object","null"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"signingSecretConfigured":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["url","events","active"],"additionalProperties":{}}},"required":["success","webhook"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"put":{"tags":["delivery"],"summary":"创建/更新投递事件 Webhook","description":"url 须为公网 HTTPS（不允许凭据/自定义端口/内网）。`signingSecret`（32-256 字符）与 `rotateSecret` 二选一；首次配置或 rotateSecret 时响应返回生成的新 secret。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Webhook URL"},"events":{"type":"array","items":{"type":"string"},"description":"订阅事件类型，默认全部"},"active":{"type":"boolean"},"signingSecret":{"type":"string"},"rotateSecret":{"type":"boolean"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","webhook"],"additionalProperties":{}}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","webhook"],"additionalProperties":{}}}}},"400":{"description":"配置非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["delivery"],"summary":"停用投递事件 Webhook","responses":{"200":{"description":"已停用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"disabled":{"type":"boolean"}},"required":["success","disabled"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/addresses":{"get":{"tags":["inbox"],"summary":"收件地址列表（含可用收发域名）","responses":{"200":{"description":"地址与域名","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"domain":{"type":"string","description":"平台默认收件域名（兼容字段）"},"domains":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","domain","domains","addresses"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["inbox"],"summary":"分配收件地址","description":"body 可省略；prefix 缺省随机生成，domain 缺省用平台域名。每账户最多 20 个。","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prefix":{"type":"string","description":"地址前缀（小写字母数字 . _ -）"},"domain":{"type":"string","description":"收信域名（须 inbound verified）"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已分配","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"address":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","address"],"additionalProperties":{}}}}},"400":{"description":"前缀/域名非法或超出数量上限","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"402":{"description":"需要订阅邮箱套餐","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"403":{"description":"域名归属未验证，或超出套餐邮箱数量","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"地址被占用或 MX 未配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/addresses/{id}":{"delete":{"tags":["inbox"],"summary":"删除收件地址及其全部邮件","parameters":[{"schema":{"type":"string","description":"收件地址 ID"},"required":true,"description":"收件地址 ID","name":"id","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages":{"get":{"tags":["inbox"],"summary":"收件列表（不含正文）","description":"keyset 分页，cursor 为 `${received_at}|${id}`。支持 recipient/sender/subject（match=exact|fuzzy）、sender_domain 发件人域名、q 模糊搜索与 since/until 收件时间范围，不检索正文。","parameters":[{"schema":{"type":"string","description":"按收件地址过滤"},"required":false,"description":"按收件地址过滤","name":"address_id","in":"query"},{"schema":{"type":"string","description":"inbox 或 quarantine，默认 inbox"},"required":false,"description":"inbox 或 quarantine，默认 inbox","name":"folder","in":"query"},{"schema":{"type":"string","description":"默认 20，最大 100"},"required":false,"description":"默认 20，最大 100","name":"limit","in":"query"},{"schema":{"type":"string","description":"keyset 分页游标"},"required":false,"description":"keyset 分页游标","name":"cursor","in":"query"},{"schema":{"type":"string","description":"收件人（to_address），匹配方式见 match"},"required":false,"description":"收件人（to_address），匹配方式见 match","name":"recipient","in":"query"},{"schema":{"type":"string","description":"发件人邮箱；模糊匹配时也匹配显示名"},"required":false,"description":"发件人邮箱；模糊匹配时也匹配显示名","name":"sender","in":"query"},{"schema":{"type":"string","description":"主题，匹配方式见 match"},"required":false,"description":"主题，匹配方式见 match","name":"subject","in":"query"},{"schema":{"type":"string","description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）"},"required":false,"description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）","name":"match","in":"query"},{"schema":{"type":"string","description":"收件人/发件人/显示名/主题跨字段模糊搜索，不含正文"},"required":false,"description":"收件人/发件人/显示名/主题跨字段模糊搜索，不含正文","name":"q","in":"query"},{"schema":{"type":"string","description":"发件人域名，忽略大小写的整域名等值匹配（不含子域名），走索引"},"required":false,"description":"发件人域名，忽略大小写的整域名等值匹配（不含子域名），走索引","name":"sender_domain","in":"query"},{"schema":{"type":"string","description":"收件时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"收件时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"since","in":"query"},{"schema":{"type":"string","description":"收件时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"收件时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"until","in":"query"}],"responses":{"200":{"description":"邮件列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"cursor":{"type":["string","null"]}},"required":["success","messages","cursor"],"additionalProperties":{}}}}},"400":{"description":"folder/游标/搜索参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/threads":{"get":{"tags":["inbox"],"summary":"会话列表（每会话带最新邮件摘要）","description":"keyset 分页，cursor 为 `${last_received_at}|${thread_id}`。搜索参数同收件列表；会话内任一邮件同时满足全部条件即返回整条会话。","parameters":[{"schema":{"type":"string","description":"按收件地址过滤"},"required":false,"description":"按收件地址过滤","name":"address_id","in":"query"},{"schema":{"type":"string","description":"inbox 或 quarantine，默认 inbox"},"required":false,"description":"inbox 或 quarantine，默认 inbox","name":"folder","in":"query"},{"schema":{"type":"string","description":"默认 20，最大 100"},"required":false,"description":"默认 20，最大 100","name":"limit","in":"query"},{"schema":{"type":"string","description":"keyset 分页游标"},"required":false,"description":"keyset 分页游标","name":"cursor","in":"query"},{"schema":{"type":"string","description":"收件人（to_address），匹配方式见 match"},"required":false,"description":"收件人（to_address），匹配方式见 match","name":"recipient","in":"query"},{"schema":{"type":"string","description":"发件人邮箱；模糊匹配时也匹配显示名"},"required":false,"description":"发件人邮箱；模糊匹配时也匹配显示名","name":"sender","in":"query"},{"schema":{"type":"string","description":"主题，匹配方式见 match"},"required":false,"description":"主题，匹配方式见 match","name":"subject","in":"query"},{"schema":{"type":"string","description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）"},"required":false,"description":"recipient/sender/subject 的匹配方式：exact（默认，忽略大小写的完整匹配）或 fuzzy（包含）","name":"match","in":"query"},{"schema":{"type":"string","description":"收件人/发件人/显示名/主题跨字段模糊搜索，不含正文"},"required":false,"description":"收件人/发件人/显示名/主题跨字段模糊搜索，不含正文","name":"q","in":"query"},{"schema":{"type":"string","description":"发件人域名，忽略大小写的整域名等值匹配（不含子域名），走索引"},"required":false,"description":"发件人域名，忽略大小写的整域名等值匹配（不含子域名），走索引","name":"sender_domain","in":"query"},{"schema":{"type":"string","description":"收件时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"收件时间下界（含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"since","in":"query"},{"schema":{"type":"string","description":"收件时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点"},"required":false,"description":"收件时间上界（不含）：Unix 秒或 ISO 8601；只写日期按 UTC 零点","name":"until","in":"query"}],"responses":{"200":{"description":"会话列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"threads":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"cursor":{"type":["string","null"]}},"required":["success","threads","cursor"],"additionalProperties":{}}}}},"400":{"description":"folder/游标/搜索参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/threads/{threadId}":{"get":{"tags":["inbox"],"summary":"会话内全部邮件（含正文，时间正序）","parameters":[{"schema":{"type":"string","description":"会话 ID"},"required":true,"description":"会话 ID","name":"threadId","in":"path"},{"schema":{"type":"string","description":"默认 inbox"},"required":false,"description":"默认 inbox","name":"folder","in":"query"}],"responses":{"200":{"description":"会话邮件","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"thread_id":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","thread_id","messages"],"additionalProperties":{}}}}},"400":{"description":"folder 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}":{"get":{"tags":["inbox"],"summary":"邮件详情（含正文）","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"responses":{"200":{"description":"邮件详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","message"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["inbox"],"summary":"删除单封邮件","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/release":{"post":{"tags":["inbox"],"summary":"把隔离邮件放回收件箱","description":"只改可见性，不会重放自动化。","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"responses":{"200":{"description":"已放回","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","message"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/content":{"get":{"tags":["inbox"],"summary":"无副作用正文读取（Webhook/Agent 用）","description":"不带 format 返回 text+html；format=text/html/markdown 时只返回该表示。strip_quotes=true 去掉引用块。","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"},{"schema":{"type":"string","description":"text / html / markdown"},"required":false,"description":"text / html / markdown","name":"format","in":"query"},{"schema":{"type":"string","description":"true / false"},"required":false,"description":"true / false","name":"strip_quotes","in":"query"}],"responses":{"200":{"description":"正文内容","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"content":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","content"],"additionalProperties":{}}}}},"400":{"description":"format/strip_quotes 非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/read-state":{"patch":{"tags":["inbox"],"summary":"设置单封邮件已读状态","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_read":{"type":"boolean","description":"true 标记已读，false 标记未读"}},"additionalProperties":{},"required":["is_read"]}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"is_read":{"type":"boolean"},"changed":{"type":"boolean"}},"required":["success","id","is_read","changed"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"发件记录不可改","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/threads/{threadId}/read-state":{"patch":{"tags":["inbox"],"summary":"设置会话内入站邮件已读状态","parameters":[{"schema":{"type":"string","description":"会话 ID"},"required":true,"description":"会话 ID","name":"threadId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_read":{"type":"boolean","description":"true 标记已读，false 标记未读"},"folder":{"type":"string","description":"inbox 或 quarantine，默认 inbox"}},"additionalProperties":{},"required":["is_read"]}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"thread_id":{"type":"string"},"is_read":{"type":"boolean"},"updated_count":{"type":"number"}},"required":["success","thread_id","is_read","updated_count"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/attachments/{attachmentId}":{"get":{"tags":["inbox"],"summary":"下载邮件附件","description":"`disposition=inline` 时图片类附件内联返回。","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"attachmentId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"disposition","in":"query"}],"responses":{"200":{"description":"附件二进制内容"},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/reply":{"post":{"tags":["inbox"],"summary":"回复邮件","description":"走 governed send 计费链路；成功后回复以 direction=outbound 写入同一会话。支持 `Idempotency-Key` 头（8-200 位字母数字 . _ : -）。","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"html":{"type":"string"},"subject":{"type":"string"},"to":{"type":"string","description":"覆盖收件人"},"fromName":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{}}}}},"responses":{"200":{"description":"回复结果（由发送链路透传，JSON）"},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/messages/{id}/forward":{"post":{"tags":["inbox"],"summary":"转发邮件","description":"正文 = 备注 + 原信引用块；原附件默认一并带上（include_attachments 控制）。支持 `Idempotency-Key` 头。","parameters":[{"schema":{"type":"string","description":"邮件 ID"},"required":true,"description":"邮件 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"转发目标邮箱"},"text":{"type":"string"},"html":{"type":"string"},"subject":{"type":"string"},"fromName":{"type":"string"},"include_attachments":{"type":"boolean","description":"默认 true"},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{}}}}},"responses":{"200":{"description":"转发结果（由发送链路透传，JSON）"},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/replies/{requestId}":{"get":{"tags":["inbox"],"summary":"查询幂等回复请求状态","parameters":[{"schema":{"type":"string","description":"回复请求 ID"},"required":true,"description":"回复请求 ID","name":"requestId","in":"path"}],"responses":{"200":{"description":"请求状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"request":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","request"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/webhook":{"get":{"tags":["inbox"],"summary":"收件 Webhook 配置","responses":{"200":{"description":"配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["success","webhook"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"put":{"tags":["inbox"],"summary":"创建/更新收件 Webhook","description":"url 须为公网 HTTPS。bodyFormat 省略时沿用既有配置；signingSecret（32-256 字符）与 rotateSecret 二选一，生成的 secret 只在响应里返回一次。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"active":{"type":"boolean"},"bodyFormat":{"type":"string","description":"text / html / markdown"},"stripQuotes":{"type":"boolean"},"signingSecret":{"type":"string"},"rotateSecret":{"type":"boolean"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","webhook"],"additionalProperties":{}}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","webhook"],"additionalProperties":{}}}}},"400":{"description":"配置非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["inbox"],"summary":"停用收件 Webhook（保留配置与历史）","responses":{"200":{"description":"已停用","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"disabled":{"type":"boolean"}},"required":["success","disabled"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/inbox/webhook/addresses/{addressId}":{"put":{"tags":["inbox"],"summary":"设置单个收件地址的专属 Webhook","description":"配置后该地址邮件只推送到此端点；签名密钥仅在创建或 rotateSecret 时返回。","parameters":[{"schema":{"type":"string","description":"收件地址 ID"},"required":true,"description":"收件地址 ID","name":"addressId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"active":{"type":"boolean"},"bodyFormat":{"type":"string","description":"text / html / markdown"},"stripQuotes":{"type":"boolean"},"signingSecret":{"type":"string"},"rotateSecret":{"type":"boolean"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","subscription"],"additionalProperties":{}}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"type":"object","properties":{},"additionalProperties":{}},"signingSecret":{"type":"string"}},"required":["success","subscription"],"additionalProperties":{}}}}},"400":{"description":"配置非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"get":{"tags":["inbox"],"summary":"查询地址专属 Webhook 订阅","parameters":[{"schema":{"type":"string","description":"收件地址 ID"},"required":true,"description":"收件地址 ID","name":"addressId","in":"path"}],"responses":{"200":{"description":"订阅配置","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["success","subscription"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["inbox"],"summary":"删除地址专属订阅（回落到默认端点）","parameters":[{"schema":{"type":"string","description":"收件地址 ID"},"required":true,"description":"收件地址 ID","name":"addressId","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"removed":{"type":"boolean"}},"required":["success","removed"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"资源不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"服务端错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/mail-drafts":{"get":{"tags":["mail-drafts"],"summary":"查询独立邮件草稿","parameters":[{"schema":{"type":"string","maxLength":128},"required":false,"name":"thread_id","in":"query"}],"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["mail-drafts"],"summary":"保存宿主起草的回复，不调用模型或发信","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"anchor_email_id":{"type":"string","minLength":1,"maxLength":128},"text":{"type":"string","minLength":1,"maxLength":524288},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"required":["anchor_email_id","text","idempotency_key"]}}}},"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/mail-drafts/{id}":{"get":{"tags":["mail-drafts"],"summary":"读取草稿","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"patch":{"tags":["mail-drafts"],"summary":"修改待批准草稿，必须提供当前版本","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":524288},"revision":{"type":"integer","exclusiveMinimum":0}},"required":["text","revision"]}}}},"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/mail-drafts/{id}/discard":{"post":{"tags":["mail-drafts"],"summary":"放弃待批准草稿","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","exclusiveMinimum":0}},"required":["revision"]}}}},"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/mail-drafts/{id}/approve":{"post":{"tags":["mail-drafts"],"summary":"批准已审核的草稿版本并发送","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","exclusiveMinimum":0},"text":{"type":"string","minLength":1,"maxLength":524288}},"required":["revision","text"]}}}},"responses":{"200":{"description":"草稿操作成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"未授权","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"草稿或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"草稿版本或状态已改变","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"503":{"description":"发送结果未确认，可重试同一版本","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents":{"get":{"tags":["agents"],"summary":"Agent 档案列表","description":"带运行统计（run 数、待批草稿数、失败数、最近运行时间）。","responses":{"200":{"description":"Agent 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"agents":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","agents"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["agents"],"summary":"创建 Agent 档案","description":"mode 取值 off / summarize / draft（auto 待护栏验证后开放）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"名称，≤100 字符"},"persona_prompt":{"type":"string","description":"人设提示词，≤8000 字符"},"mode":{"type":"string","description":"off / summarize / draft"},"address_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"绑定的收件地址 ID；null 表示暂不绑定"},"allowed_senders":{"type":"array","items":{"type":"string"},"description":"发件人白名单，≤100 条"},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":900},"instructions":{"type":"string","minLength":1,"maxLength":16000},"enabled":{"type":"boolean"}},"required":["id","name","description","instructions","enabled"]},"maxItems":20,"description":"用户录入的技能；空数组删除全部技能"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"}},"required":["success","id"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/{id}":{"patch":{"tags":["agents"],"summary":"更新 Agent 档案","description":"只更新传入的字段；address_id 传 null 解除绑定。","parameters":[{"schema":{"type":"string","description":"agent ID"},"required":true,"description":"agent ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"persona_prompt":{"type":"string"},"mode":{"type":"string"},"address_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"allowed_senders":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"skills":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":900},"instructions":{"type":"string","minLength":1,"maxLength":16000},"enabled":{"type":"boolean"}},"required":["id","name","description","instructions","enabled"]}}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"delete":{"tags":["agents"],"summary":"删除 Agent（连同评估记录）","description":"已发出的回信留在会话/发件箱里，不受影响。","parameters":[{"schema":{"type":"string","description":"agent ID"},"required":true,"description":"agent ID","name":"id","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/{id}/console-token":{"post":{"tags":["agents"],"summary":"签发对话 WebSocket 短期 token","description":"浏览器直连 agent 对话用；body.thread_id 可选——给的是该会话的对话实例，否则是总对话。","parameters":[{"schema":{"type":"string","description":"agent ID"},"required":true,"description":"agent ID","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","description":"收件箱会话 ID"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"token 已签发","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"runtime":{"type":"string"},"url":{"type":"string"},"token":{"type":"string"},"expires_at":{"type":"number"},"name":{"type":"string"},"host":{"type":"string"},"secure":{"type":"boolean"},"prefix":{"type":"string"},"agent":{"type":"string"}},"required":["success","runtime","url","token","expires_at","name","host","secure","prefix","agent"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/{id}/memories":{"get":{"tags":["agents"],"summary":"Agent 记忆列表","parameters":[{"schema":{"type":"string","description":"agent ID"},"required":true,"description":"agent ID","name":"id","in":"path"}],"responses":{"200":{"description":"记忆列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"memories":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","memories"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["agents"],"summary":"新增 Agent 记忆","parameters":[{"schema":{"type":"string","description":"agent ID"},"required":true,"description":"agent ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"记忆内容，≤1000 字符"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"}},"required":["success","id"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/{id}/memories/{memoryId}":{"delete":{"tags":["agents"],"summary":"删除单条记忆","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"memoryId","in":"path"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"记忆不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/runs":{"get":{"tags":["agents"],"summary":"评估流水列表","description":"过滤：agent_id / status / email_id / thread_id / approval_status；limit 默认 100 上限 200。","parameters":[{"schema":{"type":"string"},"required":false,"name":"agent_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"email_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"thread_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"approval_status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"run 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"runs":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","runs"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["agents"],"summary":"手动评估一封来信","description":"同一 agent 对同一封邮件已有 run 返回 409，客户端走 rerun。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"email_id":{"type":"string"}},"additionalProperties":{}}}}},"responses":{"202":{"description":"已受理","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"run_id":{"type":"string"}},"required":["success","run_id"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"agent 或邮件不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"已有评估记录","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"唤醒 agent 失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/runs/{id}/rerun":{"post":{"tags":["agents"],"summary":"重新评估","description":"清空上次结果回到 running 再唤醒。已批准/已发送不能重跑；pending 草稿被新结果覆盖。","parameters":[{"schema":{"type":"string","description":"run ID"},"required":true,"description":"run ID","name":"id","in":"path"}],"responses":{"202":{"description":"已受理","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"run_id":{"type":"string"}},"required":["success","run_id"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"run 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"当前状态不可重跑","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"502":{"description":"唤醒 agent 失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/runs/{id}":{"get":{"tags":["agents"],"summary":"run 详情（含草稿与 trace）","parameters":[{"schema":{"type":"string","description":"run ID"},"required":true,"description":"run ID","name":"id","in":"path"}],"responses":{"200":{"description":"run 详情","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"run":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","run"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"run 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/runs/{id}/approve":{"post":{"tags":["agents"],"summary":"批准草稿并发送","description":"pending → approved → 走 reply 管道发送 → sent；幂等键 agent-run:{runId}。body.text 可覆盖草稿原文。","parameters":[{"schema":{"type":"string","description":"run ID"},"required":true,"description":"run ID","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"覆盖草稿正文"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已发送","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"run_id":{"type":"string"},"reply_id":{"type":"string"},"sent_message_id":{"type":["string","null"]}},"required":["success","run_id"],"additionalProperties":{}}}}},"400":{"description":"参数非法或无草稿","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"run 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"不在待批准状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/agents/runs/{id}/discard":{"post":{"tags":["agents"],"summary":"放弃草稿","parameters":[{"schema":{"type":"string","description":"run ID"},"required":true,"description":"run ID","name":"id","in":"path"}],"responses":{"200":{"description":"已放弃","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"run 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"不在待批准状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/preferences":{"get":{"tags":["governance"],"summary":"查询收件人订阅偏好","parameters":[{"schema":{"type":"string","description":"收件人邮箱"},"required":false,"description":"收件人邮箱","name":"email","in":"query"}],"responses":{"200":{"description":"偏好列表与状态","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"preferences":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"status":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","preferences","status"],"additionalProperties":{}}}}},"400":{"description":"缺少 email","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"put":{"tags":["governance"],"summary":"设置订阅偏好（退订/按域订阅）","description":"workspace 级恢复订阅请走 POST /preferences/resubscribe；workspace 级退订会联动把 workflow 联系人置为 suppressed。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"scope":{"type":"string","enum":["workspace","sender","topic"]},"senderEmail":{"type":"string","description":"scope=sender 时必填"},"topic":{"type":"string","description":"scope=topic 时必填"},"subscribed":{"type":"boolean"},"source":{"type":"string"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已更新偏好","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"preference":{"type":"object","properties":{},"additionalProperties":{}}},"required":["success","preference"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"需走 resubscribe 端点","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/preferences/resubscribe":{"post":{"tags":["governance"],"summary":"恢复订阅（需同意凭证）","description":"恢复 workspace 级订阅必须提供来源与同意凭证（consentAt + consentReference）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"收件人邮箱"},"scope":{"type":"string","enum":["workspace","sender","topic"],"description":"V1 只支持 workspace"},"source":{"type":"string","description":"恢复来源，≤100 字符"},"consentAt":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"同意时间（ISO 或 epoch 秒）"},"consentReference":{"type":"string","description":"同意凭证引用，≤200 字符"}},"additionalProperties":{}}}}},"responses":{"200":{"description":"已恢复订阅","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"状态不允许恢复","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"冲突","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/suppressions":{"get":{"tags":["governance"],"summary":"suppression 列表","parameters":[{"schema":{"type":"string","description":"按收件人过滤"},"required":false,"description":"按收件人过滤","name":"email","in":"query"}],"responses":{"200":{"description":"suppression 列表","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"suppressions":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["success","suppressions"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}},"post":{"tags":["governance"],"summary":"新增 suppression","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"scope":{"type":"string","enum":["workspace","sender","topic"]},"senderEmail":{"type":"string"},"topic":{"type":"string"},"reason":{"type":"string","enum":["unsubscribed","hard_bounce","complaint","manual"]},"source":{"type":"string"},"campaignId":{"type":"string"},"messageId":{"type":"string"}},"additionalProperties":{}}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"}},"required":["success","id"],"additionalProperties":{}}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/suppressions/{id}":{"delete":{"tags":["governance"],"summary":"解除 suppression","parameters":[{"schema":{"type":"string","description":"suppression ID"},"required":true,"description":"suppression ID","name":"id","in":"path"}],"responses":{"200":{"description":"已解除","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":{}}}}},"401":{"description":"API key 缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"suppression 不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/admin/add-balance":{"post":{"tags":["admin"],"summary":"增加积分","description":"为指定邮箱的账户充值积分（需 admin 角色）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"目标用户邮箱"},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"充值积分数（正整数）"}},"additionalProperties":{},"required":["email","amount"]}}}},"responses":{"200":{"description":"充值成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"balance":{"type":"number"}},"required":["success","message","balance"],"additionalProperties":{}}}}},"400":{"description":"请求体错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"充值失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/admin/create-user":{"post":{"tags":["admin"],"summary":"创建用户","description":"为邮箱创建新的 API key（需 admin 角色）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"新用户邮箱"}},"additionalProperties":{},"required":["email"]}}}},"responses":{"200":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"apiKey":{"type":"string"},"message":{"type":"string"}},"required":["success","apiKey","message"],"additionalProperties":{}}}}},"400":{"description":"请求体错误","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"409":{"description":"用户已存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}},"/admin/check-email":{"get":{"tags":["admin"],"summary":"查询用户","description":"检查邮箱是否已注册（需 admin 角色）。","parameters":[{"schema":{"type":"string","description":"待查询邮箱"},"required":true,"description":"待查询邮箱","name":"email","in":"query"}],"responses":{"200":{"description":"邮箱存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"exists":{"type":"boolean"},"apiKey":{"type":"string"}},"required":["success","exists","apiKey"],"additionalProperties":{}}}}},"400":{"description":"email 参数缺失或非法","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"404":{"description":"用户不存在","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}},"500":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"false"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":{}}}}}}}}},"webhooks":{}}