이메일 서버 관리 API 가이드 (v1.2)

GIIP 시스템 알람 및 사용자 통지를 위한 SMTP 이메일 서버 설정을 관리하는 API입니다. 이 API는 오직 관리자 권한(uLevel >= 9)을 가진 사용자만 호출할 수 있습니다.

🔌 이메일 서버 관리 페이지로 이동 →

📋 개요

관리자는 이 API를 통해 시스템에서 사용할 발송용 메일 서버 정보를 등록, 수정 및 비활성화할 수 있습니다.

🔐 권한 및 보안

• uLevel: 9 (Admin) 이상 필수
• 암호 관리: SMTP 비밀번호는 DB에 안전하게 저장되지만, 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(고성능 로깅) 활용

메일 서버 설정과 같은 민감한 정보 변경 시 보안 감사(Audit)와 데이터 무결성 검증을 위해 giipApiSk3 엔드포인트를 사용할 수 있습니다.

• 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 관리자 장점: 설정 변경 실패 시 상세한 StackTrace 수집, 호출자의 IP 및 시스템 정보 기록을 통해 보안 사고 예방 및 신속한 트러블슈팅 가능.
• 활용 팁: KVSPut 등을 통한 직접적인 설정 변경보다 정해진 EmailServerConfigPut 명령을 Sk3 엔드포인트로 호출하여 로그 무결성을 확보하십시오.

문제 해결

증상	원인	해결
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-10 소스 파일: giipv3/public/help/api-email.ko.md

---

관련 문서:

• API 결과 코드 가이드 (RstVal)