발송 요청 목록 조회

       <p class="platform-info type-classic-vpc">Classic/VPC 환경에서 이용 가능합니다.</p>

서비스의 메일 발송 요청 목록을 조회합니다. 목록 탐색에 필요한 요약 필드만 반환하며, 처리 통계가 필요하면 발송 요청 조회 API를, 개별 메일이 필요하면 메일 목록 조회 API를 사용해 주십시오.

요청

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

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

요청 헤더

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`) 프로젝트 목록 조회 참조

요청 쿼리 파라미터

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

필드	타입	필수 여부	설명
`fromDateTime`	String	Required	조회 기간의 시작 일시 발송 요청 접수 일시 기준 ISO 8601 형식, 타임존 오프셋(`Z` 또는 `±hh:mm`) 포함 (URL 인코딩 필요)
`toDateTime`	String	Required	조회 기간의 끝 일시 발송 요청 접수 일시 기준 ISO 8601 형식, 타임존 오프셋(`Z` 또는 `±hh:mm`) 포함 (URL 인코딩 필요)
`requestId`	String	Optional	발송 요청 아이디 정확히 일치하는 항목 조회
`mailId`	String	Optional	메일 아이디 해당 메일을 포함하는 발송 요청 조회
`title`	String	Optional	메일 제목 부분 일치 검색
`templateNo`	Integer	Optional	템플릿 번호 정확히 일치하는 항목 조회
`senderAddress`	String	Optional	발신자 메일 주소 정확히 일치하는 항목 조회
`recipientAddress`	String	Optional	수신자 메일 주소 정확히 일치하는 항목 조회
`dispatchType`	String	Optional	발송 경로 `CONSOLE` \| `API` `CONSOLE`: 콘솔에서 발송 `API`: API로 발송
`status`	String	Optional	발송 요청 상태 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` 반복 지정 가능하며, 여러 값을 지정하면 OR로 동작 (예: `status=COMPLETED&status=FAILED`) 쉼표로 구분한 다중 값(`status=A,B`)은 미지원 값의 의미는 응답의 `requests[].status` 참조
`pageNo`	Integer	Optional	페이지 번호 0부터 시작 (기본값: 0)
`pageSize`	Integer	Optional	페이지당 항목 수 1~1000 (기본값: 10)
`sort`	String	Optional	정렬 조건 `{필드},{방향}` 형식 (예: `createDateTime,desc`) 정렬 가능 필드: `createDateTime` \| `recipientCount` \| `reservationDateTime` \| `sendDateTime` \| `status` 방향: `asc` (기본값) \| `desc` 미지정 시 `createDateTime,desc`로 정렬

참고

타임존 오프셋의 +는 쿼리 스트링에서 %2B로 인코딩해야 합니다. (예: fromDateTime=2026-07-01T00:00:00%2B09:00)
서로 다른 필터를 함께 지정하면 AND로 동작합니다.
정렬 키가 고유하지 않으면 동일 값 항목 간 순서는 보장되지 않습니다.

요청 예시

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

curl --location --request GET 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests?fromDateTime=2026-07-01T00%3A00%3A00%2B09%3A00&toDateTime=2026-07-12T23%3A59%3A59%2B09%3A00&status=COMPLETED&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'

응답

응답 형식을 설명합니다.

응답 바디

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

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

`requests`

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

필드	타입	필수 여부	설명
`requestId`	String	-	발송 요청 아이디 발송 요청 조회, 메일 목록 조회 API의 경로 파라미터로 사용
`createDateTime`	String	-	발송 요청 접수 일시 ISO 8601 형식
`templateNo`	Integer	-	사용된 템플릿 번호 템플릿을 사용하지 않은 발송은 `null`
`templateName`	String	-	사용된 템플릿 이름 템플릿을 사용하지 않은 발송은 `null`
`status`	String	-	발송 요청 상태 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `PREPARING`: 발송 요청을 접수해 준비하는 중 `READY`: 발송 준비가 완료되어 발송 시작을 기다리는 중 `RESERVED`: 예약한 발송 시각을 기다리는 중 `SENDING`: 요청에 포함된 메일을 발송하는 중 `COMPLETED`: 모든 메일의 발송이 완료됨 `FAILED`: 모든 메일의 발송이 실패함 `PARTIAL_FAILED`: 일부 메일의 발송이 실패함 `CANCELED`: 발송 요청이 취소됨
`senderAddress`	String	-	발신자 메일 주소
`senderName`	String	-	발신자 이름 입력하지 않은 발송은 `null`
`dispatchType`	String	-	발송 경로 `CONSOLE` \| `API` `CONSOLE`: 콘솔에서 발송 `API`: API로 발송
`elapsedTime`	String	-	발송 소요 시간 `HH:mm:ss.SSS` 형식 (24시간을 넘으면 시간 부분의 자릿수가 늘어남) 발송이 완료되지 않은 요청은 `null`
`sendDateTime`	String	-	발송 완료 일시 ISO 8601 형식 발송이 시작되지 않은 요청은 `null`
`reservationDateTime`	String	-	예약 발송 일시 ISO 8601 형식 즉시 발송 요청은 `null`
`requestCount`	Integer	-	발송 메일 건수 일반 발송은 수신자를 나누어 여러 통을 만들므로 수신자 수와 다를 수 있음 개별 발송이면 `recipientCount`와 동일
`recipientCount`	Integer	-	수신자 수 `CC`, `BCC` 수신자 포함 일반 발송이면 `requestCount`보다 크거나 같음

참고

수신 거부·발송 차단으로 발송되지 않은 수신자는 성공으로 집계되지 않습니다. 따라서 수신 거부 주소만 있는 요청은 FAILED로 판정됩니다. 수신자별 사유는 메일 상세 조회 API의 recipients[]로 확인해 주십시오.

응답 상태 코드

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

HTTP 상태 코드	코드	메시지	설명
200	-	OK	요청 성공
400	InvalidParameter	Bad Request	요청 파라미터 오류 `fromDateTime`, `toDateTime` 누락 또는 형식 오류 포함
401	Unauthorized	Unauthorized	인증 실패
403	Forbidden	Forbidden	경로의 `serviceId`에 대한 권한 없음
404	NotFound	Not Found	경로의 자원이 존재하지 않음
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": "InvalidParameter",
"message": "The request contains an invalid parameter."
}
}

응답 예시

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

{
"requests": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"createDateTime": "2026-07-12T09:59:35+09:00",
"templateNo": null,
"templateName": null,
"status": "COMPLETED",
"senderAddress": "no_reply@company.com",
"senderName": null,
"dispatchType": "API",
"elapsedTime": "00:00:05.230",
"sendDateTime": "2026-07-12T09:59:40+09:00",
"reservationDateTime": null,
"requestCount": 4,
"recipientCount": 100
}
],
"totalElements": 21,
"totalPages": 3,
"pageNo": 0,
"pageSize": 10
}