郵件伺服器管理 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-TW.md

相關文檔:

API 結果代碼指南 (RstVal)