---
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.

# 메일 상세 조회

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

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

## 요청

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

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

### 요청 헤더

Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 [Simple & Easy Notification Service 요청 헤더](/docs/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

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

### 요청 경로 파라미터

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

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

### 요청 예시

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

```
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](/docs/sens-mail-get#attachfiles) - 첨부파일이 없으면 빈 배열 |
| `recipients` | Array | - | 수신자별 발송 결과 목록: [recipients](/docs/sens-mail-get#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](/docs/sens-mail-get#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"
}
]
}
```