createMailRequest
- 인쇄
- PDF
createMailRequest
- 인쇄
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
Email 발송을 요청합니다.
발송 작업은 비동기로 처리됩니다.
POST https://{endpoint}/mails
주의
- 한번에 최대 100,000명에게 메일을 발송할 수 있고, 일반 발송의 경우 30건씩 나누어서 발송합니다. (수신자 그룹 조합 발송 조건[recipientGroupFilter] 입력 시 100,000 초과하여 발송 가능)
- 참조 및 숨은 참조는 각각 최대 30명을 지정할 수 있습니다.
- 본문은 500KB를 초과할 수 없습니다.
- 기본 발송 한도는 월 1,000,000 건이며, 기본 발송 한도 이상의 발송이 필요한 경우 고객 지원을 통해 발송 한도 상향 요청을 할 수 있습니다.
- 발송 요청 한도는 이메일 수신인의 수에 따라 계산되며, 수신인 100명에 대한 발송 요청 시 100건의 발송 요청으로 간주합니다.
요청
요청 파라미터
| 파라미터명 | 필수 여부 | 타입 | 제약 사항 | 설명 |
|---|---|---|---|---|
| senderAddress | Conditional | String | templateSid가 전달되지 않으면 필수, 도메인에 naver.com, navercorp.com 등 사용불가 | - 발송자 Email 주소 임의의 도메인 주소 사용해도 되지만, 가능하면 발신자 소유의 도메인 Email 계정을 사용할 것 권고 DMARC가 적용된 'id@naver.com'와 같은 포털사이트의 웹메일 계정을 사용할 경우 DMARC 검사에 실패하게 되어 수신 측 정책에 따라 스팸 처리될 가능성이 높아짐 |
| senderName | No | String | Max:69 | 발송자 이름 |
| templateSid | No | Integer | 템플릿 ID | |
| title | Conditional | String | templateSid가 전달되지 않으면 필수, Min:0, Max:500 | Mail 제목 |
| body | Conditional | String | templateSid가 전달되지 않으면 필수, Max:500KB (광고메일일 경우 수신거부 메시지를 포함하여 계산됨) | Email 본문 |
| individual | No | Boolean | Default:true | - 개인별 발송 혹은 일반 발송 여부 * 개인별 발송 시 수신자목록(recipients)에 수신인(R)만 입력 가능하며 다수의 수신인 입력시 개인별로 나누어서 발송됨 * 개인별 발송 시 참조인(C), 숨은참조(B)는 사용 불가 |
| confirmAndSend | No | Boolean | 확인 후 발송 여부 | |
| advertising | No | Boolean | 광고메일여부 | |
| parameters | No | Object | - 치환 파라미터 (전체 수신자에게 적용) '치환 ID'를 key로, '치환 ID에 맵핑되는 값'을 value로 가지는 Map 형태의 Object | |
| referencesHeader | No | String | Max:100, 다음의 형태가 되어야 함 : <<unique_id@domain.com>> | 특정 메일을 모아서 보기 위해 네이버 메일에서 지원하는 기능 (해당 필드에 동일한 값을 입력한 메일들을 모아서 볼 수 있음) |
| reservationUtc | No | Long | - 예약 발송 일시 ( 1970년 1월 1일 00:00:00 협정 세계시(UTC) 부터의 경과 시간을 1/1000초로 환산한 정수 ) reservationDateTime 값보다 이 값이 우선 적용됨 | |
| reservationDateTime | No | String | 'yyyy-MM-dd HH:mm' UTC+09:00 | - 예약 발송 일시 reservationUtc 값 우선 |
| attachFileIds | No | List<String> | createFile API를 통해 업로드된 파일 ID | 첨부파일 ID 목록 |
| recipients | Conditional | List<RecipientForRequest> | recipientGroupFilter 값이 입력되지 않으면 필수 | 수신자목록 |
| recipientGroupFilter | No | RecipientGroupFilter | 수신자 그룹 조합 발송 조건 | |
| useBasicUnsubscribeMsg | No | Boolean | Default:true, basic unsubscribe message size: 약 900byte | 광고 메일일 경우 기본 수신 거부 문구 사용 여부 |
| unsubscribeMessage | Conditional | String | useBasicUnsubscribeMsg값이 False이면 필수, Max:body와 합산하여 500KB | - 사용자 정의 수신 거부 문구 수신 거부 문구는 기본적으로 body의 끝에 추가되며 본문의 원하는 위치에 #{UNSUBSCRIBE_MESSAGE}를 추가하면 해당 태그의 위치에 수신거부 문구가 들어가게 됨 |
응답
| HTTP 상태코드 | 설명 |
|---|---|
| 201 | 발송 요청 성공 |
| 400 | 인증 실패, 잘못된 요청 |
| 500 | 서버 오류 |
예시
요청 예시
curl -i -s -X POST \
-H "Content-Type:application/json" \
-H "x-ncp-apigw-timestamp:1521787414578" \
-H "x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy" \
-H "x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=" \
"https://mail.apigw.ntruss.com/api/v1/mails"\
-d '{"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 -i -s -X POST \
-H "Content-Type:application/json" \
-H "x-ncp-apigw-timestamp:1521787414578" \
-H "x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy" \
-H "x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=" \
"https://mail.apigw.ntruss.com/api/v1/mails"\
-d '{"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":"20181203000000000201",
"count":10000
}
속성
| 항목 | 필수 여부 | 타입 | 제약 사항 | 설명 |
|---|---|---|---|---|
| requestId | Yes | String | Email 발송 요청 ID (각 요청을 구분하는 ID, 한번에 여러건에 메일 발송을 요청할 경우 requestId가 여러개의 mailId를 포함할 수 있음 | |
| count | Yes | Integer | 메일 요청 건수 |
오류 코드
| HTTP Status Code | 리턴 코드 | 응답 메시지 |
|---|---|---|
| 400 | 77101 | 로그인 정보 오류 |
| 400 | 77102 | BAD_REQUEST |
| 400 | 77103 | 리소스가 존재하지 않음 |
| 403 | 77201 | 권한 없음 |
| 403 | 77202 | Email 상품 사용신청 하지 않음 |
| 405 | 77001 | METHOD_NOT_ALLOWED |
| 415 | 77002 | UNSUPPORTED_MEDIA_TYPE |
| 500 | 77301 | 기본 프로젝트가 존재하지 않음 |
| 500 | 77302 | 외부 시스템 API 연동 오류 |
| 500 | 77303 | 그외 INTERNAL_SERVER_ERROR |
이 문서가 도움이 되었습니까?