Cloud Outbound Mailer

참고

네이버 클라우드 플랫폼의 상품 사용 방법을 보다 상세하게 제공하고, 다양한 API의 활용을 돕기 위해 [설명서][API 참조서]를 구분하여 제공하고 있습니다.

Cloud Outbound Mailer API 참조서 바로가기 >>
Cloud Outbound Mailer 설명서 바로가기 >>

Cloud Outbound Mailer API 개요

Cloud Outbound Mailer API는 RESTful 형태로 제공됩니다. HTTP 방식의 GET/POST/DELETE 메서드 호출을 통해서 이루어집니다. API를 통해 주소록을 구성/관리하고 메일 발송을 요청하며 요청 결과를 확인하고 발송 이력을 조회할 수 있습니다.

공통설정

Cloud Outbound Mailer API URL

GET/POST/DELETE
https://mail.apigw.gov-ntruss.com/api/v1

요청 헤더

헤더 명 설명
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타내며
APIGW 서버와 시간차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주

x-ncp-apigw-timestamp:{Timestamp}
x-ncp-iam-access-key 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값
x-ncp-iam-access-key:{Account Access Key}
x-ncp-apigw-signature-v2 Access Key ID 값 과 Secret Key 로 암호화한 서명
x-ncp-apigw-signature-v2:{API Gateway Signature}
x-ncp-lang API 응답 값의 다국어 처리를 위한 값. (입력 값 예시: ko-KR, en-US, zh-CN, 기본 값:en-US)
x-ncp-lang:{language code}

인증 헤더

Cloud Outbound Mailer API는 네이버 클라우드 플랫폼 API Gateway를 통하여 제공되며, API Gateway에 등록된 API를 사용하기 위해서는 2가지 인증키(Access Key ID, Secret Key)를 발급받아야 합니다

자세한 내용은 NAVER CLOUD PLATFORM API 사용 가이드를 참고 부탁드립니다

  • 인증키 생성
    • 네이버 클라우드 플랫폼 포털의 마이페이지 > 계정관리 > 인증키 관리 메뉴에서 신규 API 인증키 생성을 클릭하여 Access Key ID, Secret Key를 생성합니다
    • 만약 Access Key ID, Secret Key가 있다면 해당 키를 사용합니다

요청 예시

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.gov-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}''
  • Signature 생성(개행 문자는 \n을 사용)

    • 요청에 맞게 StringToSign를 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다
    • 이 값을 x-ncp-apigw-signature-v2로 사용합니다
  • 샘플 코드

public String makeSignature() {
    String space = " ";  // 공백
    String newLine = "\n";  // 줄바꿈
    String method = "POST";  // HTTP 메소드
    String url = "/api/v1/mails";  // 도메인을 제외한 "/" 아래 전체 url (쿼리스트링 포함)
    String timestamp = "{timestamp}";  // 현재 타임스탬프 (epoch, millisecond)
    String accessKey = "{accessKey}";  // access key id (from portal or sub account)
    String secretKey = "{secretKey}";  // secret key (from portal or sub account)

    String message = new StringBuilder()
        .append(method)
        .append(space)
        .append(url)
        .append(newLine)
        .append(timestamp)
        .append(newLine)
        .append(accessKey)
        .toString();

    SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(signingKey);

    byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));
    String encodeBase64String = Base64.encodeBase64String(rawHmac);

  return encodeBase64String;

}

공통응답

HTTP 상태 코드로 리턴 되고, Body 정보로 전달 한다.

Http Status Code 리턴 코드 설명
200 - 일반적인 요청 성공
201 - 리소스 생성 성공에 대한 응답 코드
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

오퍼레이션

Email 발송

수신자 그룹 관리