API 参考

邮箱

列出、创建、读取、修改、删除和搜索邮箱。邮箱 ID 就是邮件地址。

docs.simail.ai/zh/api/inboxes

邮箱对象：

{
  "inbox_id": "shop-helper@simail.email",
  "pod_id": "pod_01JZX3S5V7W9X1Y3Z5A7B9C1D4",
  "display_name": "Shop Helper",
  "client_id": "shop-helper",
  "status": "active",
  "metadata": { "team": "support" },
  "created_at": "2026-10-18T16:41:07Z",
  "updated_at": "2026-10-18T16:41:07Z"
}

字段	说明
`inbox_id`	邮件地址；每条路径都用它
`pod_id`	邮箱所属的 pod
`display_name`	发件人名；外发邮件会加上 ” via SiMail”
`client_id`	你的幂等句柄，在组织内唯一
`status`	`active` 或 `paused`（暂停的邮箱拒收新信，也不能发信）
`metadata`	你的 JSON，最多几 KB；永远不要在这里存密钥

指南：邮箱与 pod。

列出邮箱

GET/v0/inboxes

权限 inbox_read。分页参数为 limit、page_token、ascending；返回 { count, limit, next_page_token?, inboxes }。邮箱级 key 只能看到自己的邮箱。

创建邮箱

POST/v0/inboxes

权限 inbox_create，组织级或 pod 级 key。支持 Idempotency-Key。

正文字段	说明
`username`	可选；3–32 个字符，取自 `a-z 0-9 . _ -`。省略时会生成一个好读的随机名。
`domain`	可选；默认是你组织的 simail 邮件域名
`display_name`	可选
`client_id`	可选；相同的 `client_id` 会返回已有邮箱，而不是再创建一个
`pod_id`	可选；默认是这把 key 的 pod，或 `default` pod
`metadata`	可选的 JSON 对象

curl -s https://api.simail.ai/v0/inboxes \
  -H "Authorization: Bearer $SIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-shop-helper" \
  -d '{ "username": "shop-helper", "display_name": "Shop Helper", "client_id": "shop-helper" }'

200 OK，正文是邮箱对象。发布 inbox.created。

状态	`code`	何时
400	`validation_error`	用户名或字段不合法
403	`missing_permission`	没有 `inbox_create`、是邮箱级 key，或组织的邮箱数已达到套餐允许的数量（`reason: "inbox_limit"`）
409	`address_unavailable`	地址已被占用、是保留名、与保留名过于相似，或已退役
409	`idempotency_conflict`	这个键曾经配过不同的正文

读取邮箱

GET/v0/inboxes/{inbox_id}

权限 inbox_read。不存在或在作用域之外时返回 404 not_found。

修改邮箱

PATCH/v0/inboxes/{inbox_id}

权限 inbox_update。正文：display_name 和/或 metadata（整体替换）。暂停和恢复邮箱由人在控制台里做。

删除邮箱

DELETE/v0/inboxes/{inbox_id}

权限 inbox_delete。邮箱立即停止收信，内容被删除。地址退役：你的组织以后可以恢复它，但永远不会给别人。作用域是这个邮箱的 key 随即失效。发布 inbox.deleted。

搜索邮箱

GET/v0/inboxes/search?q=

权限 inbox_read。匹配地址、显示名和 client_id。分页。

不提供

POST /v0/inboxes/{inbox_id}/authorize 返回 501 not_implemented；请改用邮箱级 key。某个 pod 里的邮箱也可以通过 /v0/pods/{pod_id}/inboxes 访问。