# NAVER WORKS Mail API "Mail does not exist" 오류 - mailAddress 필드 null 문제

## 날짜: 2025-09-18
## 작성자: Claude (51123 서버 관리자)
## 관련 서비스: auth-server, skill-naverworks (예정)
## 상태: ✅ 해결됨 (2025-09-18 20:15)

---

## 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. 해결 완료 (2025-09-18 20:15)

### 8.1 문제 원인
- **잘못된 API 엔드포인트 사용**: `/mail/messages` (존재하지 않음)
- **올바른 엔드포인트**: `/mail/mailfolders/{folderId}/children`

### 8.2 해결 방법
```bash
# 잘못된 방식 (404 오류)
GET /v1.0/users/{userId}/mail/messages?folderId=INBOX

# 올바른 방식 (200 성공)
GET /v1.0/users/{userId}/mail/mailfolders/0/children?limit=3
# folderId=0은 받은메일함

Note: 목록 API는 날짜 파라미터(startSearchDate 등)를 지원하지 않으므로, 기간 제한은 응답의 receivedTime을 기준으로 클라이언트에서 필터링합니다.
```

### 8.3 테스트 결과
- ✅ 메일 폴더 목록 조회 성공 (25개 폴더)
- ✅ 받은메일함 9,192개 메일 확인
- ✅ 메일 제목, 발신자 정보 정상 조회
- ✅ **mailAddress가 null이어도 Mail API 정상 작동**

### 8.4 네이버웍스 지원팀 회신 예정
- 올바른 엔드포인트 사용으로 문제 해결됨
- mailAddress null은 API 사용에 영향 없음 확인

## 9. 다음 단계

1. **skill-naverworks 서비스 개발 재개**
2. **메일 요약 기능 구현**
3. **Slack 연동 테스트**