createMailRequest
    • PDF

    createMailRequest

    • PDF

    기사 요약

    Email 발송을 요청합니다.

    발송 작업은 비동기로 처리됩니다.

    POST https://mail.apigw.fin-ntruss.com/api/v1/mails
    
    주의
    • 한번에 최대 100,000명에게 메일을 발송할 수 있고, 일반 발송의 경우 30건씩 나누어서 발송합니다. (수신자 그룹 조합 발송 조건[recipientGroupFilter] 입력 시 100,000 초과하여 발송 가능)
    • 참조 및 숨은 참조는 각각 최대 30명을 지정할 수 있습니다.
    • 본문은 500KB를 초과할 수 없습니다.
    • 기본 발송 한도는 월 1,000,000 건이며, 기본 발송 한도 이상의 발송이 필요한 경우 고객 지원을 통해 발송 한도 상향 요청을 할 수 있습니다.
    • 발송 요청 한도는 이메일 수신인의 수에 따라 계산되며, 수신인 100명에 대한 발송 요청 시 100건의 발송 요청으로 간주합니다.

    요청

    요청 파라미터

    파라미터 명필수 여부타입제약사항설명
    senderAddressConditionalStringtemplateSid 가 전달되지 않으면 필수, 도메인에 naver.com, navercorp.com, ncloud.com 등 사용불가
    • 발송자 Email 주소
      • 임의의 도메인 주소 사용 가능 (가능하면 발신자 소유의 도메인 Email 계정 사용 권고)
      • DMARC가 적용된 'id@naver.com'와 같은 포털사이트의 웹메일 계정을 사용할 경우 DMARC 검사에 실패하게 되어 수신 측 정책에 따라 스팸 처리될 가능성이 높아짐
    senderNameNoStringMax:69발송자 이름
    templateSidNoInteger템플릿 ID
    titleConditionalStringtemplateSid 가 전달되지 않으면 필수, Min:0, Max:500Mail 제목
    bodyConditionalStringtemplateSid 가 전달되지 않으면 필수, Max:500KB (광고메일일 경우 수신거부 메시지를 포함하여 계산됨)Email 본문
    individualNoBooleanDefault:false
    • 개인별 발송 혹은 일반 발송 여부
      • 개인별 발송 시 수신자목록(recipients)에 수신인(R)만 입력 가능하며 다수의 수신인 입력시 개인별로 나누어서 발송됨
      • 개인별 발송 시 참조인(C), 숨은참조(B)는 사용 불가
    confirmAndSendNoBoolean확인 후 발송 여부
    advertisingNoBoolean광고메일여부
    parametersNoObject
  • 치환 파라미터 (전체 수신자에게 적용)
  • '치환 ID' 를 key로, '치환 ID에 맵핑되는 값' 을 value 로 가지는 Map 형태의 Object
  • referencesHeaderNoStringMax:100, 다음의 형태가 되어야 함 : <<unique_id@domain.com>>특정 메일을 모아서 보기 위해 네이버 메일에서 지원하는 기능 (해당 필드에 동일한 값을 입력한 메일들을 모아서 볼 수 있음)
    reservationUtcNoLong
    • 예약 발송 일시
      • 1970년 1월 1일 00:00:00 협정 세계시(UTC) 부터의 경과 시간을 1/1000초로 환산한 정수
      • reservationDateTime 값보다 이 값이 우선 적용됨
    reservationDateTimeNoString'yyyy-MM-dd HH:mm' UTC+09:00예약 발송 일시 (reservationUtc 값이 우선)
    attachFileIdsNoList<String>createFile API 를 통해 업로드된 파일 ID첨부파일 ID 목록
    recipientsConditionalList<RecipientForRequest>recipientGroupFilter 값이 입력되지 않으면 필수수신자목록
    recipientGroupFilterNoRecipientGroupFilter수신자 그룹 조합 발송 조건
    useBasicUnsubscribeMsgNoBooleanDefault:true, basic unsubscribe message size: 약 900byte광고 메일일 경우 기본 수신 거부 문구 사용 여부
    unsubscribeMessageConditionalStringuseBasicUnsubscribeMsg값이 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.fin-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}'
    

    응답 예시

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

    속성

    항목필수 여부타입제약사항설명
    requestIdYesString
    • Email 발송 요청 ID (각 요청을 구분하는 ID)
      • 한번에 여러건에 메일 발송을 요청할 경우 requestId가 여러개의 mailId를 포함할 수 있음
    countYesInteger메일 요청 건수

    에러 코드

    HTTP Status Code리턴 코드응답 메시지
    40077101로그인 정보 오류
    40077102BAD_REQUEST
    40077103리소스가 존재하지 않음
    40377201권한 없음
    40377202Email 상품 사용신청 하지 않음
    40577001METHOD_NOT_ALLOWED
    41577002UNSUPPORTED_MEDIA_TYPE
    50077301기본 프로젝트가 존재하지 않음
    50077302외부 시스템 API 연동 오류
    50077303그외 INTERNAL_SERVER_ERROR

    이 문서가 도움이 되었습니까?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.