createMailRequest

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

수신자, 발신자, 메일 내용 등을 지정하여 이메일 발송을 요청합니다. 발송 작업은 비동기로 처리됩니다.

참고

한 번에 최대 100,000명에게 발송할 수 있고, 기본적으로 30건씩 나누어서 처리됩니다. 단, 수신자 그룹 조합 발송 조건(recipientGroupFilter) 입력 시 100,000명을 초과하여 발송할 수 있습니다.
참조 및 숨은 참조는 최대 30명씩 추가할 수 있습니다.
이메일 본문은 최대 500 KB까지 허용됩니다.
기본 발송 한도는 월별 1,000,000건이며, 고객 지원을 통해 한도 상향을 요청할 수 있습니다.
발송 요청 한도는 이메일 수신인의 수에 따라 계산됩니다. 수신인 100명에 대한 발송 요청 시 100건의 발송 요청으로 간주합니다.

요청

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

메서드	URI
POST	/mails

요청 헤더

Cloud Outbound Mailer API에서 공통으로 사용하는 헤더에 대한 자세한 내용은 Cloud Outbound Mailer 요청 헤더를 참조해 주십시오.

요청 바디

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

필드	타입	필수 여부	설명
`senderAddress`	String	Conditional	발송자 이메일 주소 임의의 도메인을 사용할 수 있으나, 발신자가 실제로 소유하는 도메인 사용 권고 DMARC가 적용된 'id@naver.com'과 같은 포털 사이트의 웹 메일 계정 사용 시 DMARC 검사에 실패하여 수신측 정책에 따라 스팸 처리될 수 있음 `templateSid`를 설정하지 않으면 입력 필수 도메인에 naver.com, navercorp.com, ncloud.com 등 사용 불가
`senderName`	String	Optional	발송자 이름(Byte) 0~69
`templateSid`	Integer	Optional	이메일 작성에 사용할 템플릿의 SID getTemplateStructure 참조
`title`	String	Conditional	이메일 제목(Byte) 0~500 `templateSid`를 설정하지 않으면 입력 필수
`body`	String	Conditional	이메일 본문(KB) 0~500(광고 메일은 수신 거부 메시지를 포함하여 계산) `templateSid`를 설정하지 않으면 입력 필수
`individual`	Boolean	Optional	일반 또는 개인별 발송 여부 `true` (기본값) \| `false` `true`: 개인별 발송 `false`: 일반 발송 개인별 발송 시 `recipients`에 `R`(수신자)만 입력 가능. 복수 값 입력 시 개인별로 나누어 발송됨.
`confirmAndSend`	Boolean	Optional	확인 후 발송 여부 `true` \| `false` `true`: 확인 후 발송 `false`: 확인 없이 바로 발송
`advertising`	Boolean	Optional	광고 메일 여부 `true` \| `false` `true`: 광고 메일 `false`: 일반 메일
`parameters`	Object	Optional	치환 파라미터 전체 수신자에게 적용 치환 ID를 Key, 치환 ID에 매핑되는 값을 Value로 가지는 Map 형태의 오브젝트 구체적인 적용 방법은 사용 가이드 참조
`referencesHeader`	String	Optional	References 헤더 0~100개로 <unique_id@domain.com> 형식의 문자열 특정 이메일을 모아서 보기 위한 고유한 값 필드에 값을 입력하면 추후 동일 값이 입력된 메일만 모아서 조회 가능 네이버 메일에서는 이메일을 모아서 보기 위해 사용 값이 중복되는 경우 같은 메일 스레드로 판단하여 메일을 묶어서 노출 References 헤더의 최상단 값으로만 판단
`reservationUtc`	Long	Optional	예약 발송 일시 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 1/1000초로 환산한 정수 현재 시점부터 최대 30일 후까지 지정 가능 `reservationDateTime` 값보다 우선 적용
`reservationDateTime`	String	Optional	예약 발송 일시(yyyy-MM-dd HH:mm) UTC+9:00 기준 현재 시점부터 최대 30일 후까지 지정 가능 `reservationUtc` 값이 우선 적용
`attachFileIds`	List[String]	Optional	첨부 파일의 ID 목록 파일 ID는 createFile을 통해 확인 파일의 총용량은 20 MB 이하여야 함
`recipients`	List	Conditional	수신자 목록 `recipientGroupFilter` 값이 없으면 입력 필수 RecipientForRequest 참조
`recipientGroupFilter`	Object	Optional	수신자 그룹 조합 필터 RecipientGroupFilter 참조
`useBasicUnsubscribeMsg`	Boolean	Optional	광고 메일에서 수신 거부 메시지 사용 여부 `true` (기본값) \| `false` `true`: 기본 수신 거부 메시지 사용 `false`: 사용자 정의 수신 거부 메시지 사용 수신 거부 메시지 크기는 약 900 바이트
`unsubscribeMessage`	String	Conditional	사용자 정의 수신 거부 메시지 문구 기본적으로 `body` 값 뒤에 추가 메일 내용 안에 삽입하려면 `body` 값의 원하는 위치에 `#{UNSUBSCRIBE_MESSAGE}` 태그 입력 useBasicUnsubscribeMsg 값이 `false`일 경우 필수 `body`와 합산해 500 KB 이하여야 함

요청 예시

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

템플릿 없이 작성

템플릿을 사용하지 않고 이메일 내용을 직접 작성하는 요청 예시는 다음과 같습니다.

curl --location --request POST 'https://mail.apigw.gov-ntruss.com/api/v1/mails' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data-raw '{"senderAddress":"no_reply@company.com","title":"${customer_name}님 반갑습니다.","body":"귀하의 등급이 ${BEFORE_GRADE}에서 ${AFTER_GRADE}로 변경되었습니다.","recipients":[{"address":"hongildong@naver_.com","name":"홍길동","type":"R","parameters":{"customer_name":"홍길동","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"철수","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

템플릿을 활용하여 작성

템플릿을 사용하여 이메일을 작성하는 요청 예시는 다음과 같습니다.

curl --location --request POST 'https://mail.apigw.gov-ntruss.com/api/v1/mails' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data-raw '{"templateSid" : 1,"recipients":[{"address":"hongildong@naver_.com","name":"홍길동","type":"R","parameters":{"customer_name":"홍길동","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"철수","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

응답

응답 형식을 설명합니다.

응답 바디

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

필드	타입	필수 여부	설명
`requestId`	String	-	각 요청을 구분하기 위한 이메일 발송 요청 ID 한 번에 여러 건의 이메일 발송을 요청할 경우, `requestId`는 여러 개의 `mailId`를 포함할 수 있음
`count`	Integer	-	이메일 발송 요청 건수

응답 상태 코드

Cloud Outbound Mailer API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Cloud Outbound Mailer 응답 상태 코드를 참조해 주십시오.

응답 예시

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

{
  "requestId":"20181203000000000201",
  "count":10000
}