# 邮箱

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

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

邮箱对象：

```json
{
  "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](/zh/inboxes/)。

## 列出邮箱

`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 对象 |

```sh
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`](/zh/api/pods/) 访问。