> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 邮件来源读的邮箱

> 配置邮件来源读的 IMAP 邮箱，试连，查看上次读的结果。

```http theme={null}
GET    /api/v1/alerts/sources/{id}/mailbox
PUT    /api/v1/alerts/sources/{id}/mailbox
DELETE /api/v1/alerts/sources/{id}/mailbox
POST   /api/v1/alerts/sources/{id}/mailbox/test
```

[邮件来源](https://docs.molesignal.com/zh-Hans/alerting/sources.md#邮件)读的 IMAP 邮箱。看要 `alerts.sources.read`，改和试连要 `alerts.sources.manage`。只有 `email` 类型的来源有，只能在来源的接收集群上配，不随联邦同步。`PUT` 前要先在来源上写好发件人名单（`email.allowed_senders`）。

**`PUT` 和 `test` 的请求体**

| 字段 | 类型 | 说明 |
| - | - | - |
| `host` | string | 必填，主机名，不带协议和端口。 |
| `port` | integer | 默认 993。 |
| `security` | string | `tls`（默认）、`starttls` 或 `none`。 |
| `username` | string | 必填。 |
| `secret` | string | 密码、授权码或客户端密钥。不再返回；留空保持原样。 |
| `auth` | object | `{"kind": "password"}`（默认），或 `{"kind": "oauth2", "token_url": "https://…", "client_id": "…", "scope": "…"}`：用客户端凭证换令牌，走 `XOAUTH2`。 |
| `folder` | string | 默认 `INBOX`。 |
| `poll_secs` | integer | 多久读一次，15 到 3600，默认 60。 |

连接只去主机名此刻解析到的地址，云厂商元数据服务的地址一律拒绝。换了主机、账号或文件夹时，读到哪了从头算：从下一次连上的那一刻开始。

**`GET` 和 `PUT` 的回答**（没配时 `GET` 回 `null`）

| 字段 | 说明 |
| - | - |
| `settings` | 上面除 `secret` 以外的设置。 |
| `secret_set` | 秘密设了没有。 |
| `reading` | 已经连上过，从那以后的邮件都在读。 |
| `last_polled_at`、`last_success_at` | 上次读和上次读成功的时间（微秒）。 |
| `last_error` | 上次读失败的原因；读成功就清空。 |

`test` 用请求体里的设置连一次（`secret` 留空时用存着的），回 `{"ok": true, "messages": 3}`；连不上回 `503`，写明邮件服务器的回答。

```bash cURL theme={null}
curl -X PUT "http://localhost:5080/api/v1/alerts/sources/$SOURCE_ID/mailbox" \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"host": "imap.example.com", "username": "alerts@example.com", "secret": "<password>"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.