一句话答案

在讯蜂个人控制台创建消息读取 API Key，把完整值只保存到服务端，然后用 Authorization: Bearer <API_KEY> 请求 GET https://cc.akuwan.cn/api/v1/inbox/messages；可用 channel、source_ref、keyword、limit 缩小查询范围。

第一步：创建并保存只读 API Key

  1. 先完成账号注册和套餐激活，并绑定企业自有或已获授权的 SIM、邮箱。
  2. 在个人控制台创建 API Key，使用能识别系统和环境的名称，例如“订单服务-生产”。
  3. 设置所需有效期；当前创建范围为 1–365 天。
  4. 创建后立即保存完整 Key。列表只保留前缀、范围、有效期和状态，不应依赖再次显示明文。
  5. 每个系统、环境分别创建，避免多人和多个服务共用一个 Key。

第二步：发送第一条请求

curl --get 'https://cc.akuwan.cn/api/v1/inbox/messages' \
  --header 'Authorization: Bearer <YOUR_MESSAGE_API_KEY>' \
  --data-urlencode 'channel=email' \
  --data-urlencode 'keyword=verification' \
  --data-urlencode 'limit=20'

只查询短信时把 channel 改为 sms。不要把真实 Key 粘贴到网页、聊天、Issue、截图或公开仓库；示例中的占位符必须由服务端安全配置替换。

当前支持哪些查询参数？

参数取值作用
channelemail 或 sms只查询邮箱或短信；省略时查询两类消息。
source_ref来源标识，1–128 字符只查询某个邮箱绑定或设备来源。
keyword1–128 字符按当前消息内容筛选；应使用业务相关且不过窄的关键词。
limit1–100，默认 20限制本次返回数量。
refreshtrue 或 false控制是否刷新邮箱来源；省略时，查询邮箱或不指定通道会按当前实现尝试刷新。

返回数据怎么读？

{
  "ok": true,
  "data": [
    {
      "id": "<MESSAGE_ID>",
      "channel": "email",
      "source_ref": "<MAILBOX_OR_DEVICE_REF>",
      "expires_at": "<ISO_TIME_OR_NULL>",
      "created_at": "<ISO_TIME>",
      "payload": {
        "code": "<EXTRACTED_CODE_OR_NULL>",
        "sender": "<SENDER>",
        "subject": "<SUBJECT>",
        "received_at": "<ISO_TIME>"
      }
    }
  ]
}

payload 随消息来源不同而变化：邮箱可包含主题、发件人、正文片段和提取结果；短信可包含发件人、内容和接收时间。业务逻辑应允许 code 为空，并优先依据来源与 received_at 判断是否为本次请求对应的最新消息。

限流、错误与安全边界

  • 当前普通消息查询按每个租户与 Key 限制为每分钟 120 次；邮箱刷新另有限制，每分钟 12 次。不要写无间隔死循环。
  • 缺失、错误、过期或已撤销的 Key 返回未授权错误；Key 配额取决于当前套餐。
  • 公开读取 API 使用 messages:read 范围，不包含确认消息的 messages:ack 权限。
  • 当前没有面向任意业务地址的出站 Webhook；如需主动送达，使用已开放的飞书、钉钉或企业微信群机器人。
  • 不要把验证码、邮件正文或 API Key 记录到无保护日志；只记录请求 ID、状态码、时间和脱敏来源。
  • 服务下线、密钥疑似泄露或人员变更时立即撤销 Key，并创建新的独立 Key。

常见问题

消息读取 API 的地址是什么？

生产环境读取地址为 GET https://cc.akuwan.cn/api/v1/inbox/messages，使用 Authorization: Bearer <API_KEY> 鉴权。

API Key 可以写在前端网页里吗？

不可以。API Key 应只保存在受控服务端或密钥管理系统中，不要写入浏览器代码、公开仓库、日志或截图。

接口会主动回调业务系统吗？

当前公开能力是授权查询，不是任意出站 Webhook。业务系统应按合理间隔查询，或使用已开放的飞书、钉钉、企业微信群机器人转发。

当前能力说明：转发通道与消息读取 API、安全与合规、团队验证消息协作。接口版本与限制以控制台及当前生产实现为准。