# 邮件通知配置说明

## 1. 配置目的

Scert 的证书申请、续期、部署和校验任务完成后，可以通过第三方邮件服务 API 或 SMTP 服务发送通知。Scert 只实现出站通知客户端，不实现 SMTP、IMAP、POP3 邮件服务器端；HTTP 邮件 API 和 SMTP 出站通知均已接入。

## 2. HTTP 邮件服务配置

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `email_http_enabled` | 是否启用 HTTP 邮件通知 | `false` |
| `email_provider` | 第三方服务标识 | 空 |
| `email_endpoint` | 第三方服务基础地址，必须使用 HTTP 或 HTTPS | 空 |
| `email_http_path` | 请求路径 | `/api/email/send` |
| `email_http_auth_mode` | `none`、`bearer`、`hmac_sha256` 或 `session` | `none` |
| `email_http_login_path` | 会话认证模式的登录请求路径 | `/api/login` |
| `email_http_credential_ref` | 凭据引用，不填写明文 Token 或密钥 | 空 |
| `email_http_headers` | 自定义请求头 JSON 对象 | `{}` |

`email_endpoint` 与 `email_http_path` 分开保存。例如 Smail 服务可以配置基础地址为 `https://mail.example.com`，请求路径使用 `/api/email/send`。

Bearer Token 或 HMAC-SHA256 的实际密钥必须由凭据存储管理，配置文件只保存 `secret://` 等形式的引用。自定义请求头不能覆盖 `Authorization`、`Cookie`、`Origin`、`Referer`、`Content-Type`、`Accept`、`X-CSRF-Token`、`X-Scert-Signature`、`X-Scert-Request-Id` 和 `X-Scert-Timestamp` 等安全请求头。

## 3. Smail 接口适配说明

Smail 的发送接口为：

```text
POST /api/email/send
Content-Type: application/json
```

请求体沿用 Smail 的英文字段名，包括 `from`、`to`、`cc`、`bcc`、`subject`、`text`、`html` 和 `attrs`。Scert 的通知发送器应将证书任务事件转换为邮件标题、纯文本正文和 HTML 正文。

Smail 当前接口需要登录会话 Cookie、`smail_csrf` Cookie、`X-CSRF-Token` 请求头和同源 `Origin` 请求头。Scert 的 `session` 认证模式会使用凭据存储中的账号和密码调用配置的登录路径，读取登录响应中的会话 Cookie，并在发送邮件时携带会话、CSRF 和同源请求头；密码不会写入请求日志、普通配置文件或错误信息。

## 4. 通知内容配置

| 配置项 | 说明 |
|---|---|
| `email_event_mode` | `detailed` 表示发送详细事件，`unified` 表示发送统一事件 |
| `email_include_deployment_details` | 是否包含服务器部署明细 |
| `email_include_certificate_serial` | 是否包含证书序列号 |
| `email_include_management_url` | 是否包含管理后台链接 |
| `email_sender_name` | 发件人名称，默认 `Scert` |
| `email_sender_email` | 发件人地址，留空时使用超级管理员绑定邮箱 |
| `recipients` | 收件人列表；未填写时自动使用超级管理员绑定邮箱 |

## 5. 超时与重试

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `email_timeout_secs` | 单次通知请求超时时间 | `10` |
| `email_retry_count` | 失败后的重试次数 | `3` |
| `email_retry_intervals_secs` | 每次重试前等待的秒数 | `30,120,600` |

重试间隔数量必须与重试次数一致。HTTP 通知发送器应将所有 2xx 响应视为请求成功，其他状态码进入重试或失败流程，并记录请求 ID 和最终错误。

## 6. 当前实现边界

当前阶段已完成邮件通知配置的保存、校验、初始化接口、CLI/Web 表单接入、HTTP 通知发送器和 SMTP 出站通知发送器。SMTP 支持 `plain`、`starttls` 和 `implicit_tls` 三种连接模式；生产环境建议使用 STARTTLS 或隐式 TLS。Smail 登录会话可通过 `session` 认证模式自动建立和刷新。

## 7. 当前开发状态补充

当前版本已经接入 HTTP 邮件通知发送器，支持以下能力：

- 按证书申请、续期、导入和部署结果生成通知事件。
- 按 Smail `/api/email/send` 接口格式发送 JSON 请求。
- 支持 `none`、`bearer`、`hmac_sha256` 和 `session` 四种 HTTP 认证模式。
- `session` 模式支持配置登录路径；收到 HTTP 401、403 或对应业务错误码时，会在重试前重新登录并使用新会话发送。
- 使用加密凭据存储读取 Bearer Token 或 HMAC 签名密钥，配置文件只保存凭据引用。
- 使用 `X-Scert-Request-Id`、`X-Scert-Timestamp` 请求头，并禁止自定义请求头覆盖安全头。
- 将所有 2xx 响应视为成功，其他响应按重试配置处理。
- 证书工作流会在任务成功、失败或部署错误后触发通知；通知发送失败会写入 Scert 日志，不覆盖原证书任务结果。

SMTP 出站通知已经接入。初始化界面和 CLI 可以配置 SMTP 主机、端口、用户名、凭据引用、连接模式和明文认证开关；SMTP 密码只保存到加密敏感信息存储，配置文件仅保存 `secret://` 凭据引用。明文连接认证默认拒绝，只有明确启用 `SMTP 明文认证` 后才允许。CLI 可使用 `scert config set-secret --key notification.smtp_password` 保存敏感值。SMTP 是出站连接，Scert 不需要开放 SMTP 入站端口。Smail 登录会话的自动适配已通过 `session` 模式接入，仍需在目标部署环境使用实际凭据进行上线前复核。