docs: NAVER WORKS Mail API mailAddress null 문제 문서화 - info@company-x.partners 계정 Mail API 접근 불가 이슈 정리

troubleshooting/250918_naverworks_mail_api_mailaddress_null_issue.md

@@ -0,0 +1,147 @@
+# NAVER WORKS Mail API "Mail does not exist" 오류 - mailAddress 필드 null 문제
+
+## 날짜: 2025-09-18
+## 작성자: Claude (51123 서버 관리자)
+## 관련 서비스: auth-server, skill-naverworks (예정)
+## 상태: 미해결 - 네이버웍스 지원팀 문의 진행 중
+
+---
+
+## 1. 문제 상황 요약
+
+### 발견된 문제
+- **Mail API 호출 실패**: "Mail does not exist" 오류 발생
+- **Directory API 응답 이상**: mailAddress 필드가 null
+- **웹메일은 정상 작동**: 18GB/100GB 사용 중으로 메일 서비스는 활성화됨
+- **OAuth 토큰 정상**: mail scope 포함되어 있음
+
+### 영향 범위
+- info@company-x.partners 계정 Mail API 접근 불가
+- 메일 자동화 기능 구현 차단
+- skill-naverworks 서비스 개발 지연
+
+---
+
+## 2. 기술적 상세 정보
+
+### 2.1 계정 정보
+```
+User ID: 795cf95e-396b-42d0-16f0-0323ee92a179
+OAuth User ID: 3550cef6-63e1-4ceb-8802-a25c9d1c6917
+Email: info@company-x.partners
+Domain ID: 155032
+플랜: Standard
+```
+
+### 2.2 API 호출 실패 케이스
+
+#### Mail API 요청
+```
+GET https://www.worksapis.com/v1.0/users/795cf95e-396b-42d0-16f0-0323ee92a179/mail/messages?folderId=INBOX&limit=1
+Authorization: Bearer kr1AAABAaxRvBHczSOI8fT5gTg6QsK...
+```
+
+#### 응답 (오류)
+```json
+{
+  "code": "NOT_FOUND",
+  "description": "Mail does not exist."
+}
+```
+
+### 2.3 Directory API 응답 분석
+
+#### 동일 토큰으로 Directory API 호출
+```
+GET https://www.worksapis.com/v1.0/users/795cf95e-396b-42d0-16f0-0323ee92a179
+```
+
+#### 응답 (문제 확인)
+```json
+{
+  "userId": "795cf95e-396b-42d0-16f0-0323ee92a179",
+  "email": "info@company-x.partners",
+  "mailAddress": null,    // ← 문제의 핵심
+  "primaryEmail": null,   // ← 이것도 null
+  "userName": {
+    "firstName": "X",
+    "lastName": "COMPANY"
+  }
+}
+```
+
+---
+
+## 3. 시도한 해결 방법 (모두 실패)
+
+### 3.1 권한 세트 재설정
+- Admin 콘솔에서 권한 그룹 재할당
+- mail 권한 명시적 부여
+- 결과: 변화 없음
+
+### 3.2 메일 별칭 추가/삭제
+- 별칭 추가 시도
+- 기존 별칭 삭제 후 재생성
+- 결과: mailAddress 여전히 null
+
+### 3.3 메일 서비스 재활성화
+- 서비스 비활성화 → 활성화
+- MX 레코드 재확인
+- 결과: 웹메일은 작동하나 API는 실패
+
+---
+
+## 4. 네이버웍스 지원팀 답변 분석
+
+### 4.1 첫 번째 답변 요약
+- Directory API는 구성원 관련 API
+- 구성원 추가 시 email 파라미터 필수 (ID@Domain 형식)
+- JWT(서비스 계정)로는 mail scope 사용 불가
+
+### 4.2 답변의 한계
+- **기존 계정의 mailAddress 수정 방법 언급 없음**
+- **Admin 권한으로도 수정 불가능한 이유 설명 없음**
+- **웹메일 정상 작동과 API 실패의 불일치 원인 미설명**
+
+---
+
+## 5. 추정 원인 분석
+
+### 5.1 계정 생성 시점 문제
+- 구 버전 API로 생성된 계정일 가능성
+- 메일 서비스 활성화 이전 생성 계정
+- Directory와 Mail 서비스 간 동기화 누락
+
+### 5.2 시스템 불일치
+- Directory DB와 Mail DB 간 데이터 불일치
+- mailAddress 필드 마이그레이션 누락
+- 내부 시스템 간 동기화 실패
+
+---
+
+## 6. 해결 방안 (요청 사항)
+
+### 6.1 네이버웍스 지원팀 추가 요청
+1. **mailAddress 필드 수동 설정 방법**
+2. **Directory와 Mail 서비스 간 강제 동기화**
+3. **계정 재생성 없이 해결 가능 여부**
+4. **API 콘솔에서 디버깅 도구 제공 여부**
+
+### 6.2 임시 해결책 검토
+- 새 계정 생성 후 데이터 마이그레이션
+- Service Account 활용 검토 (OAuth 제약 회피)
+- 웹메일 크롤링 (최후의 수단)
+
+---
+
+## 7. 관련 문서 및 참고사항
+
+- NAVER WORKS Developers: https://developers.worksmobile.com
+- Mail API 문서: https://developers.worksmobile.com/kr/reference/mail-message-list
+- Directory API 문서: https://developers.worksmobile.com/kr/reference/directory-user-get
+
+## 8. 다음 단계
+
+1. **네이버웍스 지원팀 2차 문의 진행**
+2. **응답 대기 중 Service Account 방식 테스트**
+3. **문제 해결 시 skill-naverworks 서비스 구현 재개**