---
title: "메일 상세 조회"
slug: "sens-mail-get"
updated: 2026-09-17T09:15:58Z
published: 2026-09-17T09:15:58Z
canonical: "api.ncloud-docs.com/sens-mail-get"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 메일 상세 조회

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

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

## 요청<a name="요청"></a>
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

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

### 요청 헤더<a name="요청헤더"></a>
Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 [Simple & Easy Notification Service 요청 헤더](/docs/sens-overview#요청헤더)를 참조해 주십시오.

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

### 요청 경로 파라미터<a name="요청경로파라미터"></a>
요청 경로 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `serviceId` | String | Required | 메일 서비스 아이디<ul><li>NRN(NCP Resource Name) 형식 (예: `ncp:mail:kr:1********2:main`)</li><li>[프로젝트 목록 조회](/docs/sens-project-list) 참조</li></ul> |
| `requestId` | String | Required | 발송 요청 아이디<ul><li>[발송 요청 목록 조회](/docs/sens-mail-request-list) 참조</li></ul> |
| `mailId` | String | Required | 메일 아이디<ul><li>경로의 `requestId`에 소속된 메일이어야 함</li><li>[메일 목록 조회](/docs/sens-mail-list) 참조</li></ul> |

### 요청 예시<a name="요청예시"></a>
요청 예시는 다음과 같습니다.

```shell
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'
```

## 응답<a name="응답"></a>
응답 형식을 설명합니다.

### 응답 바디<a name="응답바디"></a>
응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | - | 발송 요청 아이디 |
| `mailId` | String | - | 메일 아이디 |
| `requesterIp` | String | - | 발송을 요청한 클라이언트의 IP 주소<ul><li>콘솔 발송과 API 발송 모두 요청 시점의 출발지 주소 기록</li></ul> |
| `createDateTime` | String | - | 발송 요청 접수 일시<ul><li>ISO 8601 형식</li></ul> |
| `title` | String | - | 메일 제목<ul><li>치환 변수가 실제 값으로 치환된 결과</li></ul> |
| `templateNo` | Integer | - | 사용된 템플릿 번호<ul><li>템플릿을 사용하지 않은 발송은 `null`</li></ul> |
| `templateName` | String | - | 사용된 템플릿 이름<ul><li>템플릿을 사용하지 않은 발송은 `null`</li></ul> |
| `status` | String | - | 메일 발송 상태<ul><li>`READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED`<ul><li>`READY`: 발송 시작을 기다리는 중</li><li>`RESERVED`: 예약한 발송 시각을 기다리는 중</li><li>`SENDING`: 메일을 발송하는 중</li><li>`COMPLETED`: 메일에 속한 모든 수신자에게 발송이 완료됨</li><li>`FAILED`: 메일에 속한 모든 수신자에게 발송이 실패함</li><li>`PARTIAL_FAILED`: 메일에 속한 수신자 중 일부에게만 발송이 실패함</li><li>`CANCELED`: 발송이 취소됨</li></ul></li></ul> |
| `senderAddress` | String | - | 발신자 메일 주소 |
| `senderName` | String | - | 발신자 이름<ul><li>입력하지 않은 발송은 `null`</li></ul> |
| `sendDateTime` | String | - | 발송 완료 일시<ul><li>ISO 8601 형식</li><li>발송이 시작되지 않은 메일은 `null`</li></ul> |
| `reservationDateTime` | String | - | 예약 발송 일시<ul><li>ISO 8601 형식</li><li>즉시 발송은 `null`</li></ul> |
| `body` | String | - | 메일 본문<ul><li>치환 변수가 실제 값으로 치환된 결과</li><li>`advertising`이 `true`이면 수신 거부 문구 포함</li></ul> |
| `advertising` | Boolean | - | 광고 메일 여부<ul><li>`true` \| `false`</li></ul> |
| `attachFiles` | Array | - | 첨부파일 목록: [attachFiles](#attachfiles)<ul><li>첨부파일이 없으면 빈 배열</li></ul> |
| `recipients` | Array | - | 수신자별 발송 결과 목록: [recipients](#recipients)<ul><li>`CC`, `BCC` 수신자 포함</li><li>일반 발송은 수신자를 30명 단위로 나누어 메일을 생성하므로 항목 수는 최대 30</li><li>개인 발송은 수신자당 메일 1건이므로 항목 1개</li></ul> |

#### `attachFiles`<a name="attachfiles"></a>
`attachFiles`에 대한 설명은 다음과 같습니다.

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

#### `recipients`<a name="recipients"></a>
`recipients`에 대한 설명은 다음과 같습니다.

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

#### `sendResultCode`<a name="sendresultcode"></a>
`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` | 수신 서버의 연결 종료로 인한 발송 실패 |

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

### 응답 상태 코드<a name="응답상태코드"></a>
응답 상태 코드에 대한 설명은 다음과 같습니다.

| 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 | 서버 내부 오류 |

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

#### 오류 응답 바디<a name="오류응답바디"></a>
호출이 실패한 경우 응답 바디에 대한 설명은 다음과 같습니다.

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

#### 오류 응답 예시<a name="오류응답예시"></a>
호출이 실패한 경우의 응답 예시는 다음과 같습니다.

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

### 응답 예시<a name="응답예시"></a>
응답 예시는 다음과 같습니다.

```json
{
"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"
}
]
}
```