Cloud Outbound Mailer 개요

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

개요

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

공통 설정

Cloud Outbound Mailer API URL

### 요청 헤더<a name="요청헤더"></a>

|          헤더명         | 설명                            |
|------------------|------------------------------------------------|
|   x-ncp-apigw-timestamp  | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주<br /> ```x-ncp-apigw-timestamp:{Timestamp}``` |
|   x-ncp-iam-access-key   | NAVER Cloud Platform 포털에서 발급받은 Access Key ID 값<br/> ```x-ncp-iam-access-key:{Account Access Key}```                                                                                                        |
| x-ncp-apigw-signature-v2 | Access Key ID 값 과 Secret Key 로 암호화한 서명<br/> ```x-ncp-apigw-signature-v2:{API Gateway Signature}```                                                                                                           |
|   x-ncp-lang             | API 응답 값의 다국어 처리를 위한 값. (입력 값 예시: ko-KR, en-US, zh-CN, 기본 값:en-US)<br/> ```x-ncp-lang:{language code}```                                                                                  |

#### 인증 헤더<a name="인증헤더"></a>

Cloud Outbound Mailer API는 NAVER Cloud Platform API Gateway를 통하여 제공되며, API Gateway에 등록된 API를 사용하기 위해서는 2가지 인증키(Access Key ID, Secret Key)를 발급받아야 합니다

자세한 내용은 [NAVER CLOUD PLATFORM API 가이드](/docs/common-ncpapi)를 참고 부탁드립니다.

- 인증키 생성
  - N네이버 클라우드 플랫폼 콘솔의 우측 상단 **My Account** > **계정 및 보안 관리** > **보안 관리** > **접근 관리** > **API 인증키**메뉴에서 **신규 API 인증키 생성**을 클릭하여 Access Key ID, Secret Key를 생성합니다
  - 만약 Access Key ID, Secret Key가 있다면 해당 키를 사용합니다.


#### 요청 예시<a name="요청예시"></a>

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":"{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`로 사용합니다.


-  **샘플 코드**


```java
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.getEncoder().encodeToString(rawHmac);

  return encodeBase64String;

}

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

응답

공통 응답 형식을 설명합니다.

응답 상태 코드

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

오퍼레이션

이메일 발송

• createMailRequest
• getMail
• getMailList
• getMailRequestList
• getMailRequestStatus
• createFile
• getFile
• deleteFile

템플릿 관리

• createTemplate
• getTemplate
• getTemplateStructure
• updateTemplate
• deleteTemplate
• restoreTemplate
• createCategory
• deleteCategory

수신자 그룹 관리

• createAddressBook
• getAddressBook
• deleteAddressBook
• deleteAddress
• deleteRecipientGroup

발송 차단 및 수신 거부 관리

• getSendBlockList
• registerUnsubscribers
• deleteUnsubscribers