createMailRequest

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

참고
  • 한 번에 최대 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
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<RecipientForRequest> Conditional 수신자 목록
  • recipientGroupFilter 값이 없으면 입력 필수
recipientGroupFilter RecipientGroupFilter Optional 수신자 그룹 조합 필터
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.fin-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

템플릿을 활용하여 작성

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

curl --location --request POST 'https://mail.apigw.fin-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}'
Curl

응답 형식을 설명합니다.

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

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

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

HTTP 상태 코드 코드 설명
201 - 요청 성공
400 - 인증 실패, 잘못된 요청
400 77101 로그인 정보 오류
400 77102 요청 오류
400 77103 요청한 리소스가 존재하지 않음
403 77201 요청한 리소스에 대한 권한이 없음
403 77202 이메일 서비스 사용을 신청하지 않은 사용자가 호출한 경우
405 77001 지원되지 않는 메서드 유형
415 77002 지원되지 않는 미디어 유형
500 - 서버 오류
500 77301 기본 프로젝트가 존재하지 않음
500 77302 외부 시스템 API 연동 오류
500 77303 그 외 내부 서버 오류

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

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