Email Server Management API Guide (v1.2)

This API manages SMTP email server settings for GIIP system alarms and user notifications. This API can only be called by users with administrator privileges (uLevel >= 9).

🔌 Go to Email Server Management →

📋 Overview

Administrators can use this API to register, modify, and disable mail server information for sending emails from the system.

🔐 Permissions & Security

• uLevel: 9 (Admin) or higher required.
• Password Management: SMTP passwords are stored securely in the database, but care should be taken to avoid exposure when calling the API.

📡 API Details (Sk3)

1. Retrieve Email Server List (EmailServerConfigList)

• Command: text=EmailServerConfigList
• Description: Returns information for all SMTP servers currently registered in the system.

2. Add/Modify Email Server Settings (EmailServerConfigPut)

• Command: text=EmailServerConfigPut
• jsondata:

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

• Note: If escSn is 0, it is a new registration; if greater than 0, it modifies the configuration of the corresponding serial number.

3. Send Test Email (EmailServerConfigSendTest)

• Command: text=EmailServerConfigSendTest
• jsondata: {"escSn": 1, "toEmail": "admin@example.com"}
• Description: Tests whether the specified server configuration can successfully send an email.

🛡️ Using Sk3 (High-fidelity Logging)

You can use the giipApiSk3 endpoint for security auditing and data integrity verification when changing sensitive information such as mail server settings.

• Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
• Admin Advantages: Provides detailed StackTrace collection upon configuration change failure, and records the caller's IP and system information to prevent security incidents and enable quick troubleshooting.
• Usage Tip: Ensure log integrity by calling defined EmailServerConfigPut commands through the Sk3 endpoint rather than directly changing settings via KVSPut, etc.

Troubleshooting

Symptom	Cause	Resolution
401/permission error returned	Called with an account below uLevel 9	Call with an administrator (uLevel ≥ 9) account.
EmailServerConfigPut creates a new entry instead of updating	escSn sent as 0, treated as a new registration	Specify the target serial number in escSn when modifying an existing configuration.
Test email is not delivered	Missing toEmail or wrong SMTP settings (host/port/SSL)	Provide a valid toEmail in jsondata and verify escSmtpHost/escSmtpPort/escUseSsl.
text command not recognized or RstVal error	Command name typo or malformed jsondata JSON	Use the exact command name and valid JSON, and check the API Result Codes Guide.

---

Version: 1.3 Last Updated: 2026-04-11 Source: giipv3/public/help/api-email.en.md

---

Related Documents:

• API Result Codes Guide (RstVal)