指南

邮箱与 pod

创建、列出、修改和删除邮箱;地址规则、暂停、删除,以及 pod。

docs.simail.ai/zh/inboxes

一个邮箱就是一个邮件地址,连同它的线程、消息、草稿和标签。API 里的邮箱 ID 就是地址本身(shop-helper@simail.email);每次调用时 simail 会把它解析成内部 ID。

创建

POST /v0/inboxes
Idempotency-Key: create-shop-helper
Content-Type: application/json

{
  "username": "shop-helper",
  "display_name": "Shop Helper",
  "client_id": "shop-helper",
  "metadata": { "team": "support" }
}

字段	说明
`username`	可选;不填会生成一个好读的随机名
`domain`	可选;默认是你组织的 simail 邮件域名
`display_name`	作为发件人名显示(外发邮件会加上 ” via SiMail”)
`client_id`	可选的幂等句柄;同样的 `client_id` 返回同一个邮箱
`metadata`	自由格式的 JSON,供你自己记账;不要在这里存密钥

需要组织级或 pod 级 key 上的 inbox_create 权限。邮箱数超过套餐允许的数量时返回 403 missing_permission,reason: "inbox_limit"。

地址规则

3–32 个字符,取自 a-z、0-9、.、_、-;不能以点开头或结尾,也不能有连续的点。
一律小写。+tag 后缀永远不算地址的一部分(simail 用它承载回复令牌)。
保留名(postmaster、abuse、security、admin、noreply 等)和看起来像保留名的名字(混用文字、0/o、1/l)会被拒绝。
地址永远不会转给别的组织。 删除邮箱会让地址退役;你的组织以后可以恢复它,但别人永远拿不到。已被占用或已退役的名字返回 409 address_unavailable。

读取、修改、删除

方法与路径	权限
`GET /v0/inboxes`	`inbox_read`
`GET /v0/inboxes/{inbox_id}`	`inbox_read`
`PATCH /v0/inboxes/{inbox_id}`(`display_name`、`metadata`)	`inbox_update`
`DELETE /v0/inboxes/{inbox_id}`	`inbox_delete`
`GET /v0/inboxes/search?q=`	`inbox_read`

列表分页:limit(1–200,默认 50)、page_token(不透明;绑定你 key 的作用域和查询)和 ascending。响应形如 { "count": 2, "limit": 50, "next_page_token": "…", "inboxes": [ … ] }。

邮箱可以在控制台里暂停;暂停的邮箱拒收新信,在恢复之前也不能发信。

Pod

pod 把邮箱分组,比如每个客户一个 pod,或每批 agent 一个 pod。每个组织都有一个 default pod。pod 级 key 只能看到那个 pod。pod 由人在控制台里创建和删除;key 可以读取:

GET /v0/pods、GET /v0/pods/{pod_id}、GET /v0/pods/{pod_id}/inboxes,以及邮箱、线程和草稿接口的 pod 版本。

不提供

不提供自定义域名(/v0/domains)、IMAP/SMTP 访问和独立发信 IP;这些路径返回 501 not_implemented。见不支持的功能。

完整的请求与响应细节:邮箱 API 和 Pod API。