---
title: "메일 발송 요청 생성"
slug: "sens-mail-request-create"
updated: 2026-09-17T09:15:58Z
published: 2026-09-17T09:15:58Z
canonical: "api.ncloud-docs.com/sens-mail-request-create"
---

> ## 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건이 리소스 1개(`requestId`)로 생성되며, 발송은 비동기로 처리되므로 이 API는 접수 결과만 반환합니다.

## 요청

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

| 메서드 | URI |
| --- | --- |
| POST | /mail/v2/services/{serviceId}/requests |

### 요청 헤더

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) 참조 |

### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `senderAddress` | String | Conditional | 발신자 메일 주소 - 최대 254 Byte - `templateNo` 미입력 시 필수 |
| `senderName` | String | Optional | 발신자 이름 - 최대 69 Byte (UTF-8 기준) |
| `templateNo` | Integer | Conditional | 템플릿 번호 - 입력 시 템플릿에 저장된 발신자·제목·본문 사용 - `senderAddress`, `title`, `body`를 함께 입력하면 입력값이 템플릿 값을 대체 - 미입력 시 `senderAddress`, `title`, `body` 필수 |
| `title` | String | Conditional | 메일 제목 - 최대 500 Byte (UTF-8 기준) - `${key}` 형식의 치환 변수 사용 가능 - `templateNo` 미입력 시 필수 |
| `body` | String | Conditional | 메일 본문 - 최대 500 KB (UTF-8 기준, 치환 변수가 값으로 바뀐 뒤의 크기를 수신자별로 판정) - 광고 메일(`advertising`이 `true`)은 수신 거부 문구를 포함하여 크기 계산 - HTML 및 `${key}` 형식의 치환 변수 사용 가능 - `templateNo` 미입력 시 필수 |
| `individual` | Boolean | Optional | 개인 발송 여부 - `true` (기본값) \| `false` - `true`: 수신자별로 메일을 개별 발송하며, 다른 수신자 주소가 노출되지 않음 - `false`: 여러 수신자를 하나의 메일에 함께 담아 발송하며, 수신자끼리 서로의 주소를 볼 수 있음 - `true`인 경우 `CC`, `BCC` 수신자 사용 불가 |
| `confirmAndSend` | Boolean | Optional | 확인 후 발송 여부 - `true` \| `false` (기본값) - `true`: 발송 준비 상태로 접수하며, 별도 확인 절차 후 발송 |
| `advertising` | Boolean | Optional | 광고 메일 여부 - `true` \| `false` (기본값) - `true`: 제목에 광고 표기가 추가되고 수신 거부 안내가 본문에 포함 - `individual`이 `false`인 일반 발송에서는 사용 불가 |
| `parameters` | Object | Optional | 전체 수신자에 공통 적용되는 치환 변수 - `{"key": "value"}` 형식 - 제목·본문의 `${key}`가 값으로 치환 - 입력 시 수신자별 `recipients[].parameters`는 적용되지 않음 - 제목·본문에 `${key}`가 있으면 적용되는 쪽(요청 수준 또는 수신자별)에 해당 키가 모두 존재해야 하며, 키가 없으면 요청 거부 |
| `reservationDateTime` | String | Optional | 예약 발송 일시 - ISO 8601 형식, 타임존 오프셋(`Z` 또는 `±hh:mm`) 포함 (예: `2026-07-10T09:00:00+09:00`) - 미입력 시 즉시 발송 - 현재 시각으로부터 최대 30일 이후까지 지정 가능 |
| `attachFileIds` | Array | Optional | 첨부파일 아이디 목록 - 개별 파일 최대 10 MB, 합계 최대 20 MB |
| `recipients` | Array | Conditional | 수신자 목록: [recipients](/docs/sens-mail-request-create#recipients) - 최대 100,000건 입력 가능 - `TO` 유형 수신자 1명 이상 필수 - `recipientGroupFilter` 미입력 시 필수 |
| `recipientGroupFilter` | Object | Conditional | 주소록 그룹 기반 수신자 지정: [recipientGroupFilter](/docs/sens-mail-request-create#recipientgroupfilter) - `individual`이 `true`인 개인 발송에서만 사용 가능 - `recipients` 미입력 시 필수 |
| `useBasicUnsubscribeMessage` | Boolean | Optional | 기본 수신 거부 문구 사용 여부 - `true` (기본값) \| `false` - `true`: 서비스가 제공하는 기본 수신 거부 문구 사용 - `false`: `unsubscribeMessage`에 입력한 문구 사용 - 기본 수신 거부 문구의 크기는 약 900바이트 - 광고 메일(`advertising`이 `true`)에만 적용 |
| `unsubscribeMessage` | String | Optional | 사용자 지정 수신 거부 문구 - `useBasicUnsubscribeMessage`가 `false`인 경우 적용 - `useBasicUnsubscribeMessage`가 `false`이더라도 미입력 시 기본 수신 거부 문구 적용 - 기본적으로 `body` 뒤에 추가되며, 본문 안에 삽입하려면 `body`의 원하는 위치에 `#{UNSUBSCRIBE_MESSAGE}` 태그 입력 - `body`와 합산해 500 KB 이하여야 함 - 광고 메일(`advertising`이 `true`)에만 적용되며, 일반 메일에는 수신 거부 문구가 포함되지 않음 |

참고

- `recipients`와 `recipientGroupFilter`를 모두 입력하면 두 목록을 이어 붙여 처리하며, 같은 주소가 양쪽에 있어도 중복은 제거되지 않습니다. 이 경우 해당 주소로 메일이 2통 발송되고 월 발송 한도도 2건 차감됩니다.
- `recipientGroupFilter`로 수신자를 지정하면 100,000명 건수 상한이 적용되지 않으며, 월 발송 한도만 적용됩니다.
- `CC`와 `BCC`는 각각 최대 30명입니다.
- 월 발송 한도를 초과하면 `429 ResourceQuotaExceeded`를 반환합니다.
- 접수 응답에는 발송 상태가 포함되지 않습니다. 접수 직후 상태는 즉시 발송 `READY`, 예약 발송 `RESERVED`이며, 이후 상태는 [발송 요청 조회](/docs/sens-mail-request-get) API를 폴링해 확인합니다. 폴링 간격은 해당 API의 `retry-after` 응답 헤더를 따릅니다.

#### `recipients`

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `address` | String | Required | 수신자 메일 주소 - 최대 254 Byte |
| `name` | String | Optional | 수신자 이름 - 최대 69 Byte (UTF-8 기준) |
| `type` | String | Optional | 수신자 유형 - `TO` (기본값) \| `CC` \| `BCC` - `TO`: 받는 사람 - `CC`: 참조 (최대 30명) - `BCC`: 숨은 참조 (최대 30명) - `individual`이 `true`인 경우 `CC`, `BCC` 사용 불가 |
| `parameters` | Object | Optional | 해당 수신자에만 적용되는 치환 변수 - `{"key": "value"}` 형식 - 요청 수준 `parameters`를 입력하지 않은 경우에만 적용 |

#### `recipientGroupFilter`

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `operator` | String | Optional | 그룹 조건 결합 연산자 - `OR` (기본값) \| `AND` - `OR`: 지정한 그룹 중 하나 이상에 속한 수신자 - `AND`: 지정한 모든 그룹에 속한 수신자 |
| `groups` | Array | Required | 주소록 그룹명 목록 |

### 요청 예시

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

```
curl --location --request POST 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests' \
--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' \
--header 'Content-Type: application/json' \
--data '{
"senderAddress": "no_reply@company.com",
"senderName": "고객센터",
"title": "${customer_name}님 반갑습니다.",
"body": "귀하의 등급이 ${BEFORE_GRADE}에서 ${AFTER_GRADE}로 변경되었습니다.",
"individual": true,
"advertising": false,
"recipients": [
{
"address": "hongildong@example.com",
"name": "홍길동",
"type": "TO",
"parameters": {
"customer_name": "홍길동",
"BEFORE_GRADE": "SILVER",
"AFTER_GRADE": "GOLD"
}
}
],
"useBasicUnsubscribeMessage": true
}'
```

## 응답

응답 형식을 설명합니다.

### 응답 바디

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

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | - | 발송 요청 아이디 - [발송 요청 조회](/docs/sens-mail-request-get), [메일 목록 조회](/docs/sens-mail-list) API의 경로 파라미터로 사용 - 값의 내부 구성은 고정된 계약이 아니므로 파싱하지 말고 그대로 사용 |
| `requestCount` | Integer | - | 발송 메일 건수 - 일반 발송은 수신자를 나누어 여러 통을 만들므로 수신자 수와 다를 수 있음 - 개별 발송(`individual`이 `true`)이면 수신자 수와 같음 |
| `createDateTime` | String | - | 발송 요청 접수 일시 - ISO 8601 형식 |

### 응답 상태 코드

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

| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
| --- | --- | --- | --- |
| 202 | - | Accepted | 발송 요청 접수 성공 |
| 400 | InvalidParameter | Bad Request | 요청 파라미터 오류 - `templateNo`, `attachFileIds`, `recipientGroupFilter.groups`가 가리키는 자원을 사용할 수 없는 경우 포함 |
| 401 | Unauthorized | Unauthorized | 인증 실패 |
| 403 | Forbidden | Forbidden | 경로의 `serviceId`에 대한 권한 없음 |
| 404 | NotFound | Not Found | 경로의 자원이 존재하지 않음 |
| 413 | ContentTooLarge | Content Too Large | 요청 본문 크기 초과 |
| 429 | ResourceQuotaExceeded | Too Many Requests | 월 발송 한도 초과 |
| 429 | ThrottlingExceeded | Too Many Requests | 호출 빈도 제한 초과 |
| 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."
}
}
```

### 응답 예시

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

```
{
"requestId": "20260702-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"requestCount": 1,
"createDateTime": "2026-07-02T10:00:00+09:00"
}
```