메일 상세 조회

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

발송 요청에 포함된 메일 1건의 상세 정보를 조회합니다. 메일 제목·본문과 첨부파일 목록, 수신자별 발송 결과(recipients[])를 함께 반환합니다.

요청

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

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

요청 헤더

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	Required	메일 아이디 경로의 `requestId`에 소속된 메일이어야 함 메일 목록 조회 참조

요청 예시

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

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

응답

응답 형식을 설명합니다.

응답 바디

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

필드	타입	필수 여부	설명
`requestId`	String	-	발송 요청 아이디
`mailId`	String	-	메일 아이디
`requesterIp`	String	-	발송을 요청한 클라이언트의 IP 주소 콘솔 발송과 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`
`reservationDateTime`	String	-	예약 발송 일시 ISO 8601 형식 즉시 발송은 `null`
`body`	String	-	메일 본문 치환 변수가 실제 값으로 치환된 결과 `advertising`이 `true`이면 수신 거부 문구 포함
`advertising`	Boolean	-	광고 메일 여부 `true` \| `false`
`attachFiles`	Array	-	첨부파일 목록: attachFiles 첨부파일이 없으면 빈 배열
`recipients`	Array	-	수신자별 발송 결과 목록: recipients `CC`, `BCC` 수신자 포함 일반 발송은 수신자를 30명 단위로 나누어 메일을 생성하므로 항목 수는 최대 30 개인 발송은 수신자당 메일 1건이므로 항목 1개

`attachFiles`

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

필드	타입	필수 여부	설명
`fileId`	String	-	첨부파일 아이디
`fileName`	String	-	첨부파일 이름 최대 100자
`fileSize`	Integer	-	첨부파일 크기(Byte)

`recipients`

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

필드	타입	필수 여부	설명
`address`	String	-	수신자 메일 주소
`name`	String	-	수신자 이름 입력하지 않은 수신자는 `null`
`type`	String	-	수신자 유형 `TO` \| `CC` \| `BCC` `TO`: 받는 사람 `CC`: 참조 `BCC`: 숨은 참조
`received`	Boolean	-	수신 확인 여부 `true` \| `false` `true`: 수신자가 메일을 열람함 `false`: 열람하지 않음
`receivedDateTime`	String	-	수신 확인 일시 ISO 8601 형식 열람하지 않았으면 `null`
`status`	String	-	수신자별 발송 상태 `READY` \| `RESERVED` \| `SENDING` \| `RETRYING` \| `COMPLETED` \| `FAILED` \| `ERRORED` \| `UNSUBSCRIBED` \| `BLOCKED` \| `CANCELED` `READY`: 발송 시작을 기다리는 중 `RESERVED`: 예약한 발송 시각을 기다리는 중 `SENDING`: 수신자에게 메일 전송을 시도하는 중 `RETRYING`: 일시적인 실패로 재시도가 예약되어 대기하는 중 `COMPLETED`: 수신자에게 메일이 정상적으로 발송됨 `FAILED`: 수신 서버의 거부 등으로 발송이 실패함 `ERRORED`: 발송 처리 중 오류로 종료됨 `UNSUBSCRIBED`: 수신 거부 주소여서 발송되지 않음 `BLOCKED`: 발송 차단 주소여서 발송되지 않음 `CANCELED`: 발송이 취소됨
`retryCount`	Integer	-	발송 재시도 횟수 최초 발송은 재시도에 포함되지 않음
`sendResultCode`	String	-	발송 결과 코드 전체 값은 sendResultCode 참조 값이 추가될 수 있는 열린 집합 발송이 완료되지 않은 수신자는 `null`
`sendResultMessage`	String	-	발송 결과 원문 메시지 수신 메일 서버가 반환한 SMTP 응답 원문 발송이 완료되지 않은 수신자는 `null`

`sendResultCode`

recipients[].sendResultCode에 대한 설명은 다음과 같습니다.

코드	설명
`CANCELED_MAIL`	발송 취소
`CONNECTION_ABNORMAL`	연결 이상으로 인해 일시적 발송 실패
`CONTENT_HAS_TAG_FORM`	메일 콘텐츠 내 치환 태그가 존재하여 발송 실패
`DKIM_FAIL`	DKIM 오류로 인해 메일 발송 실패
`EMPTY_BODY_CONTENT`	시스템 오류로 메일 본문을 설정하지 못하여 발송 실패
`MAILBOX_ABNORMAL`	수신자 메일함 이상으로 인해 일시적 발송 실패
`MAILBOX_ERROR`	수신자 메일함 오류로 인해 발송 실패
`MAIL_CONTENTS_ERROR`	메일 콘텐츠 오류로 인해 발송 실패
`MAIL_SENT`	발송 성공
`MIME_MESSAGE_CREATE_FAIL`	시스템 오류로 MIME 메시지를 생성하지 못하여 발송 실패
`NETWORK_ABNORMAL`	네트워크 이상으로 인해 일시적 발송 실패
`NETWORK_ERROR`	네트워크 오류로 인해 발송 실패
`NONEXISTENT_DOMAIN_ADDRESS`	수신자 도메인이 존재하지 않아 발송 실패
`RECEIVE_MAIL_SERVICE_ABNORMAL`	수신자 메일 서비스 이상으로 인해 일시적 발송 실패
`RECEIVE_MAIL_SERVICE_ERROR`	수신자 메일 서비스 오류로 인해 발송 실패
`RECIPIENT_ADDRESS_ERROR`	수신자 주소 오류로 인해 발송 실패
`RESENDING_MAIL`	재발송 중
`RESEND_MAIL_FAIL`	재발송 시도 초과로 인해 발송 실패
`SECURITY_AND_POLICY_ABNORMAL`	보안 및 정책 이상으로 인해 일시적 발송 실패
`SECURITY_AND_POLICY_ERROR`	보안 및 정책 오류로 인해 발송 실패
`SEND_BLOCK_ADDRESS`	발송 차단된 수신자로 발송 요청하여 차단
`SMTP_ABNORMAL`	수신 측과의 SMTP 이상으로 인해 일시적 발송 실패
`SMTP_ERROR`	수신 측과의 SMTP 오류로 인해 발송 실패
`TEST_MAIL_SEND`	시스템의 테스트 메일 발송
`UNDEFINED_ERROR`	정의되지 않은 오류로 인해 발송 실패
`UNKNOWN_CAUSE_FAIL`	시스템 내외에서 발생한 알 수 없는 오류로 인해 발송 실패
`UNKNOWN_DOMAIN_ADDRESS`	알 수 없는 도메인 또는 차단된 도메인이 포함된 주소로 발송 요청하여 실패
`UNSUBSCRIBE_ADDRESS`	수신 거부한 주소로 발송 요청하여 차단
`UNSUPPORTED_ENCODING_ADDRESS`	수신자 주소 인코딩 실패로 인해 발송 실패
`READ_TIMED_OUT`	수신 서버 미응답으로 인한 발송 실패
`CONNECTION_ERROR`	수신 서버의 연결 종료로 인한 발송 실패

참고

mailId는 경로의 requestId에 소속된 메일이어야 합니다. 권한이 있는 호출자에 한해, 소속이 아니면 404를 반환합니다.
발송이 완료되지 않은 메일은 sendDateTime, recipients[].sendResultCode, recipients[].sendResultMessage가 null입니다.

응답 상태 코드

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

HTTP 상태 코드	코드	메시지	설명
200	-	OK	요청 성공
400	InvalidParameter	Bad Request	요청 파라미터 오류
401	Unauthorized	Unauthorized	인증 실패
403	Forbidden	Forbidden	경로의 `serviceId`에 대한 권한 없음
404	NotFound	Not Found	경로의 `requestId` 또는 `mailId`가 존재하지 않음
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",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"requesterIp": "203.0.113.42",
"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",
"reservationDateTime": null,
"body": "<body>귀하의 등급이 SILVER에서 GOLD로 변경되었습니다.</body>",
"advertising": false,
"attachFiles": [
{
"fileId": "8f14e45fceea167a5a36dedd4bea2543",
"fileName": "등급안내.pdf",
"fileSize": 204800
}
],
"recipients": [
{
"address": "hongildong@example.com",
"name": "홍길동",
"type": "TO",
"received": false,
"receivedDateTime": null,
"status": "COMPLETED",
"retryCount": 0,
"sendResultCode": "MAIL_SENT",
"sendResultMessage": "Mail sent."
},
{
"address": "test12@example.com",
"name": null,
"type": "CC",
"received": false,
"receivedDateTime": null,
"status": "FAILED",
"retryCount": 0,
"sendResultCode": "RECIPIENT_ADDRESS_ERROR",
"sendResultMessage": "550 5.1.1 No such user - nsmtp"
}
]
}