邮件服务器管理 API 指南 (v1.2)

本 API 用于管理 SMTP 邮件服务器设置，以便发送 GIIP 系统警报和用户通知。只有具有管理员权限 (uLevel >= 9) 的用户才能调用此 API。

🔌 前往邮件服务器管理 →

📋 概述

管理员可以通过此 API 注册、修改或禁用系统中用于发送邮件的服务器信息。

🔐 权限与安全

uLevel: 必须达到 9 (Admin) 或以上
密码管理: 虽然 SMTP 密码安全地存储在数据库中，但在调用 API 时仍应注意防止密码泄露。

📡 API 详情 (Sk3)

1. 查询邮件服务器列表 (EmailServerConfigList)

命令:
```
text=EmailServerConfigList
```
说明: 返回当前系统中注册的所有 SMTP 服务器信息。

2. 添加/修改邮件服务器配置 (EmailServerConfigPut)

命令:
```
text=EmailServerConfigPut
```
jsondata:

{
  "escSn": 0,
  "escName": "警报专用 SMTP",
  "escSmtpHost": "smtp.example.com",
  "escSmtpPort": 587,
  "escSmtpUser": "sender@example.com",
  "escSmtpPassword": "password",
  "escFromEmail": "noreply@giip.com",
  "escFromName": "GIIP Monitoring",
  "escUseSsl": true,
  "escIsActive": true
}

注意: 若
```
escSn
```
为 0，则为新增注册；若大于 0，则修改对应序列号的配置。

3. 发送测试邮件 (EmailServerConfigSendTest)

命令:
```
text=EmailServerConfigSendTest
```

jsondata:

{"escSn": 1, "toEmail": "admin@example.com"}

说明: 测试指定的服务器配置是否能正常发送邮件。

🛡️ 巧用 Sk3 (高性能日志)

在更改邮件服务器设置等敏感信息时，可以使用

giipApiSk3

端点进行安全审计 (Audit) 和数据完整性校验。

端点:

https://giipfaw.azurewebsites.net/api/giipApiSk3

管理员优势: 在配置更改失败时收集详细的堆栈跟踪 (StackTrace)，记录调用者的 IP 和系统信息，从而预防安全事故并实现快速排障。
使用技巧: 建议通过 Sk3 端点调用预定义的
```
EmailServerConfigPut
```
命令，而不是通过
```
KVSPut
```
直接更改设置，以确保日志的完整性。

故障排除

症状	原因	解决
返回 401/权限错误	使用低于 uLevel 9 的账户调用	使用管理员(uLevel ≥ 9)权限的账户调用。
执行 `EmailServerConfigPut` 时创建了新条目而非更新现有配置	`escSn` 以 0 发送，被视为新增注册	修改现有配置时，请在 `escSn` 中指定对应的序列号。
测试邮件未能发送	缺少 `toEmail` 或 SMTP 设置(host/port/SSL)错误	在 `jsondata` 中提供有效的 `toEmail` ，并核对 `escSmtpHost` / `escSmtpPort` / `escUseSsl` 。
`text` 命令无法识别或出现 `RstVal` 错误	命令名拼写错误或 `jsondata` 的 JSON 格式错误	使用正确的命令名和有效的 JSON，并查阅 API 结果代码指南。

版本: 1.3 最后更新: 2026-04-11 源文件:

giipv3/public/help/api-email.zh-CN.md

相关文档:

API 结果代码指南 (RstVal)