메일 목록 조회

Classic/VPC 환경에서 이용 가능합니다.

발송 요청에 포함된 메일 목록을 조회합니다. 목록 탐색에 필요한 요약 필드만 반환하며, 본문·첨부파일·수신자별 결과가 필요하면 메일 상세 조회 API를 사용해 주십시오.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
GET	/mail/v2/services/{serviceId}/requests/{requestId}/mails

요청 헤더

Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 Simple & Easy Notification Service 요청 헤더를 참조해 주십시오.

필드	필수 여부	설명
`x-ncp-lang`	Optional	응답 메시지 언어 `en-US` (기본값) \| `ko-KR` \| `ja-JP`

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`serviceId`	String	Required	메일 서비스 아이디 NRN(NCP Resource Name) 형식 (예: `ncp:mail:kr:1********2:main`) 프로젝트 목록 조회 참조
`requestId`	String	Required	발송 요청 아이디 메일 발송 요청 생성 시 응답받은 값 입력 발송 요청 목록 조회 참조

요청 쿼리 파라미터

요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`mailId`	String	Optional	메일 아이디 정확히 일치하는 항목 조회
`recipientAddress`	String	Optional	수신자 메일 주소 정확히 일치하는 항목 조회
`title`	String	Optional	메일 제목 부분 일치 검색
`status`	String	Optional	메일 발송 상태 `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` 반복 지정 가능하며, 여러 값을 지정하면 OR로 동작 (예: `status=COMPLETED&status=FAILED`) 쉼표로 구분한 다중 값(`status=A,B`)은 미지원 값의 의미는 응답의 `mails[].status` 참조
`pageNo`	Integer	Optional	페이지 번호 0부터 시작 (기본값: 0)
`pageSize`	Integer	Optional	페이지당 항목 수 1~1000 (기본값: 10)
`sort`	String	Optional	정렬 조건 `{필드},{방향}` 형식 (예: `createDateTime,desc`) 정렬 가능 필드: `mailId` \| `createDateTime` \| `status` 방향: `asc` (기본값) \| `desc` 미지정 시 `createDateTime,desc`로 정렬

참고

서로 다른 필터를 함께 지정하면 AND로 동작합니다.
권한이 있는 호출자에 한해, 경로의 requestId가 존재하지 않으면 404를 반환합니다. 조건에 맞는 메일이 없는 것(빈 배열 + 200)과는 다릅니다.
정렬 키가 고유하지 않으면 동일 값 항목 간 순서는 보장되지 않습니다.

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request GET 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests/20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777/mails?status=PARTIAL_FAILED&pageNo=0&pageSize=10&sort=createDateTime%2Cdesc' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'x-ncp-lang: ko-KR'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`mails`	Array	-	메일 목록: mails 조건에 맞는 항목이 없으면 빈 배열
`totalElements`	Integer	-	조건에 맞는 전체 항목 수
`totalPages`	Integer	-	전체 페이지 수
`pageNo`	Integer	-	현재 페이지 번호
`pageSize`	Integer	-	페이지당 항목 수

`mails`

mails에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`requestId`	String	-	발송 요청 아이디
`mailId`	String	-	메일 아이디 메일 상세 조회 API의 경로 파라미터로 사용
`createDateTime`	String	-	발송 요청 접수 일시 ISO 8601 형식
`title`	String	-	메일 제목
`templateNo`	Integer	-	사용된 템플릿 번호 템플릿을 사용하지 않은 발송은 `null`
`templateName`	String	-	사용된 템플릿 이름 템플릿을 사용하지 않은 발송은 `null`
`status`	String	-	메일 발송 상태 `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `READY`: 발송 시작을 기다리는 중 `RESERVED`: 예약한 발송 시각을 기다리는 중 `SENDING`: 메일을 발송하는 중 `COMPLETED`: 메일에 속한 모든 수신자에게 발송이 완료됨 `FAILED`: 메일에 속한 모든 수신자에게 발송이 실패함 `PARTIAL_FAILED`: 메일에 속한 수신자 중 일부에게만 발송이 실패함 `CANCELED`: 발송이 취소됨
`senderAddress`	String	-	발신자 메일 주소
`senderName`	String	-	발신자 이름 입력하지 않은 발송은 `null`
`sendDateTime`	String	-	발송 완료 일시 ISO 8601 형식 발송이 시작되지 않은 메일은 `null`
`representativeRecipient`	String	-	대표 수신자 메일 주소 수신자가 여러 명이면 그중 한 명의 주소 전체 목록은 메일 상세 조회 API로 확인
`recipientCount`	Integer	-	수신자 수 `CC`, `BCC` 수신자 포함
`sendType`	String	-	발송 유형 `IMMEDIATE` \| `RESERVED` `IMMEDIATE`: 즉시 발송 `RESERVED`: 예약 발송
`advertising`	Boolean	-	광고 메일 여부 `true` \| `false`

참고

수신 거부(UNSUBSCRIBED)·발송 차단(BLOCKED)·처리 오류(ERRORED)로 발송되지 않은 수신자는 성공으로 집계되지 않으므로, 해당 수신자만 있는 메일은 FAILED로 관측됩니다. 수신자별 사유는 메일 상세 조회 API의 recipients[].status와 recipients[].sendResultCode로 확인해 주십시오.

응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

HTTP 상태 코드	코드	메시지	설명
200	-	OK	요청 성공
400	InvalidParameter	Bad Request	요청 파라미터 오류
401	Unauthorized	Unauthorized	인증 실패
403	Forbidden	Forbidden	경로의 `serviceId`에 대한 권한 없음
404	NotFound	Not Found	경로의 `requestId`가 존재하지 않음
500	InternalServerError	Internal Server Error	서버 내부 오류

참고

Simple & Easy Notification Service의 다른 API와 달리, 메일 v2 API는 NCP API 표준 오류 형식으로 오류를 반환합니다. 응답 바디의 status, error(문자열) 필드 대신 아래의 error 객체가 반환됩니다.

오류 응답 바디

호출이 실패한 경우 응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`error`	Object	-	오류 정보
`error.errorCode`	String	-	오류 코드 응답 상태 코드 표의 코드 열 참조
`error.message`	String	-	오류 코드별 고정 메시지 `x-ncp-lang` 헤더에 지정한 언어로 반환
`error.detail`	String	-	요청별 상세 사유 해당하는 사유가 없으면 필드가 생략됨
`error.fieldErrors`	Array	-	파라미터별 오류 목록 `field`: 오류가 발생한 파라미터 이름 `message`: 오류 사유 파라미터 오류가 아니면 필드가 생략됨

오류 응답 예시

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

{
"error": {
"errorCode": "NotFound",
"message": "The requested resource was not found."
}
}

응답 예시

응답 예시는 다음과 같습니다.

{
"mails": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"createDateTime": "2026-07-12T15:19:53+09:00",
"title": "홍길동님 반갑습니다.",
"templateNo": 41,
"templateName": "등급 변경 안내",
"status": "PARTIAL_FAILED",
"senderAddress": "no_reply@company.com",
"senderName": "고객센터",
"sendDateTime": "2026-07-12T15:19:53+09:00",
"representativeRecipient": "hongildong@example.com",
"recipientCount": 30,
"sendType": "IMMEDIATE",
"advertising": false
}
],
"totalElements": 2,
"totalPages": 1,
"pageNo": 0,
"pageSize": 10
}