# 邮箱与 pod

Source: https://docs.simail.ai/zh/inboxes/

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

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

## 创建

```http
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`。见[不支持的功能](/zh/not-supported/)。

完整的请求与响应细节:[邮箱 API](/zh/api/inboxes/) 和 [Pod API](/zh/api/pods/)。