메일 발송 요청 생성

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

메일 발송을 요청합니다. 발송 요청 1건이 리소스 1개(requestId)로 생성되며, 발송은 비동기로 처리되므로 이 API는 접수 결과만 반환합니다.

요청

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

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

요청 헤더

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`) 프로젝트 목록 조회 참조

요청 바디

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

필드	타입	필수 여부	설명
`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 최대 100,000건 입력 가능 `TO` 유형 수신자 1명 이상 필수 `recipientGroupFilter` 미입력 시 필수
`recipientGroupFilter`	Object	Conditional	주소록 그룹 기반 수신자 지정: 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이며, 이후 상태는 발송 요청 조회 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	-	발송 요청 아이디 발송 요청 조회, 메일 목록 조회 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"
}