발송 요청 조회

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

메일 발송 요청 1건의 상태와 처리 통계를 조회합니다. 메일 발송 요청 생성 API가 반환한 requestId로 조회하며, 발송 진행 상황을 추적하는 데 사용합니다.

요청

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

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

요청 헤더

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	발송 요청 아이디 메일 발송 요청 생성 시 응답받은 값 입력 발송 요청 목록 조회 참조

요청 예시

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

curl --location --request GET 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests/20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777' \
--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'

응답

응답 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

필드	필수 여부	설명
`retry-after`	-	다음 폴링까지 대기할 시간(초) `status`가 종료 상태(`COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED`)에 도달하기 전까지만 반환 종료 상태에 도달하면 반환되지 않음

응답 바디

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

필드	타입	필수 여부	설명
`requestId`	String	-	발송 요청 아이디 값의 내부 구성은 고정된 계약이 아니므로 파싱하지 말고 그대로 사용
`status`	String	-	발송 요청 상태 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `PREPARING`: 발송 요청을 접수해 준비하는 중 `READY`: 발송 준비가 완료되어 발송 시작을 기다리는 중 `RESERVED`: 예약한 발송 시각을 기다리는 중 `SENDING`: 요청에 포함된 메일을 발송하는 중 `COMPLETED`: 모든 메일의 발송이 완료됨 `FAILED`: 모든 메일의 발송이 실패함 `PARTIAL_FAILED`: 일부 메일의 발송이 실패함 `CANCELED`: 발송 요청이 취소됨
`createDateTime`	String	-	발송 요청 접수 일시 ISO 8601 형식
`requestCount`	Integer	-	발송 메일 건수 일반 발송은 수신자를 나누어 여러 통을 만들므로 수신자 수와 다를 수 있음 개별 발송이면 수신자 수와 동일
`readyCount`	Integer	-	저장이 완료된 메일 건수 전 상태 합계
`sentCount`	Integer	-	발송에 성공한 메일 건수
`finishCount`	Integer	-	처리가 종료된 메일 건수 성공·실패·수신 거부·취소 합계
`reservationDateTime`	String	-	예약 발송 일시 ISO 8601 형식 즉시 발송 요청은 `null`
`countsByStatus`	Array	-	메일 상태별 건수 분포: countsByStatus 건수 합계는 `requestCount`와 동일 건수가 0인 상태는 포함되지 않음

`countsByStatus`

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

필드	타입	필수 여부	설명
`status`	String	-	발송 상태 `READY` \| `RESERVED` \| `SENDING` \| `RETRYING` \| `COMPLETED` \| `FAILED` \| `ERRORED` \| `UNSUBSCRIBED` \| `BLOCKED` \| `CANCELED` `READY`: 발송 시작을 기다리는 중 `RESERVED`: 예약한 발송 시각을 기다리는 중 `SENDING`: 수신자에게 메일 전송을 시도하는 중 `RETRYING`: 일시적인 실패로 재시도가 예약되어 대기하는 중 `COMPLETED`: 수신자에게 메일이 정상적으로 발송됨 `FAILED`: 수신 서버의 거부 등으로 발송이 실패함 `ERRORED`: 발송 처리 중 오류로 종료됨 `UNSUBSCRIBED`: 수신 거부 주소여서 발송되지 않음 `BLOCKED`: 발송 차단 주소여서 발송되지 않음 `CANCELED`: 발송이 취소됨
`count`	Integer	-	해당 상태인 메일 건수

참고

status가 종료 상태에 도달하기 전까지는 응답에 retry-after 헤더가 포함됩니다. 그 값(초)만큼 대기한 뒤 다시 조회해 주십시오.
수신 거부·발송 차단으로 발송되지 않은 수신자는 성공으로 집계되지 않습니다. 실패·오류의 구체적인 원인은 메일 상세 조회 API의 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."
}
}

응답 예시

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

{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"status": "COMPLETED",
"createDateTime": "2026-07-12T10:00:00+09:00",
"requestCount": 35179,
"readyCount": 35179,
"sentCount": 33502,
"finishCount": 35179,
"reservationDateTime": null,
"countsByStatus": [
{
"status": "COMPLETED",
"count": 33502
},
{
"status": "FAILED",
"count": 1415
},
{
"status": "UNSUBSCRIBED",
"count": 262
}
]
}