[PHP] PHP로 네이버 Cloud Outbound Mailer API 사용하기

1. Cloud Outbound Mailer?

 네이버 설명서에는 아래와 같이 설명해주고 있습니다.

Cloud Outbound Mailer 상품은 개인화 콘텐츠 메일을 빠르고 안정적으로 전송할 수 있는 서비스입니다. 알림, 정보, 마케팅 대량 메일을 UI를 통해서 쉽게 전송하거나 운영하고 있는 서비스에 연결해 전송할 수 있습니다. 또한 운영 중인 서비스에 Cloud Outbound Mailer를 연결하면 제공되는 API를 이용하여 메일을 전송할 수 있습니다.

 즉 대량 메일을 손쉽게 연동해 전송할 수 있는 API라고 볼 수 있습니다. 각 사이트에서 회원들에게 광고메일을 보내거나 공지사항 메일을 보낼 때 사용하면 손쉽게 보낼 수 있습니다. 

 

사용설명서 바로가기

 

 API 참조 문서에서는 샘플이 자바로 되어있기 때문에 PHP 버전을 따로 만들어 보았습니다. 시행착오도 있었고 정확하지는 않지만 현재 메일이 정상적으로 발송되고 있기에 공개를 해도 될 것으로 보였습니다. 해당 서비스를 신청하는 방법은 적지 않겠습니다.

 

API 문서 바로가기

 

 

2. PHP 를 이용해 메일 보내기

2-1. 공통인증 헤더 만들기

 공통인증 헤더에는 다음과 같은 내용이 포함되어야 합니다.

x-ncp-apigw-timestamp	1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-iam-access-key	네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값
x-ncp-apigw-signature-v2	Access Key ID 값 과 Secret Key 로 암호화한 서명

여기서 signature를 만드는 법을 해당 페이지서는 JAVA 소스로 설명을 해주고 있습니다. 여기서는 PHP로 변경한 소스를 추가하도록 하겠습니다.

 

<?php 

  $message = "POST";
  $message .= " ";
  $message .= "/api/v1/mails";
  $message .= "\n";
  $message .= $timestamp;
  $message .= "\n";
  $message .= $access_key;
    
  $signature = base64_encode(hash_hmac('sha256', $message, $secret_key, true));

API를 등록할 때 발급받은 Access Key와 Secret Key를 이용해합니다.  그리고 13자리 timestamp 값이 필요로 합니다. 13자리 timestamp를 구하는 방법은 저의 블로그에 등록되어있습니다. 

 

2019/11/28 - [평범한 개발 이야기/PHP] - [PHP] 13자리 timestamp 생성하기

 

 저렇게 만든 메시지를 HMAC_SHA256 암호화 방식으로 암호화 해준 다음 base64_encode 함수를 통해 인코딩을 해줍니다. hash_hmac 함수의 네 번째 매개 변수가 false 인 경우 php 함수의 출력은 소문자 16 진수입니다. 그러나 Java 버전은 대문자 16 진수를 생성합니다. 대소 문자의 차이점을 수정하거나 hash_hmac의 네 번째 매개 변수를 true로 변경하면 첫 번째 Java 버전과 일치하게 됩니다.

 

curl을 통해 보내기 때문에 공통 헤더를 아래와 같이 만들어 주면 됩니다.

<?php

$headers = array(
            "Content-Type: application/json;"
            , "x-ncp-apigw-timestamp: " . $timestamp . ""
            , "x-ncp-iam-access-key: " . $access_key . ""
            , "x-ncp-apigw-signature-v2: " . $signature . ""
        );

이렇게 헤더까지 완성이 되었습니다. 

 

2-2. 메일 내용 만들기

 메일 내용은 만들기가 참 쉽습니다. API문서에 필수 여부에 따라 해당 값을 넣어주기만 하면 되기 때문입니다. 저는 배열로 만들어 json형태로 컨버팅 해서 전송을 하였습니다.

<?php

  $mailContentsDataSet["senderAddress"] = "보내는 메일주소";
  $mailContentsDataSet["senderName"] = "보내는 이름";
  $mailContentsDataSet["title"] =  "제목";
  $mailContentsDataSet["body"] =  stripslashes(htmlspecialchars_decode("본문내용 HTML 형식")); 
  $mailContentsDataSet["recipients"][] = array(
      "address" => "받는사람 이메일", "name" => "받는사람 이름", "type" => "R"
  );
  $mailContentsDataSet["recipients"][] = array(
      "address" => "참조 이메일", "name" => "참조 이름", "type" => "C"
  );

 가장 간단하게 만든 메일 내용 만들기입니다. 굳이 클래스를 만들지 않고 모든 내용을 배열로 저장했습니다. 수신자 목록은 여러 명을 추가적으로 넣어서 한 번에 보낼 수도 있습니다. API 문서에서는 List<RecipientForRequest> 타입으로 되어있습니다. RecipientForRequest VO 클래스를 만들지 않았기 때문에 위 PHP 소스에는 같은 형태로 값을 넣어주고 있습니다. type의 값에 따라서 수신자 유형이 변경됩니다. ( R: 수신자, C:참조, B: 숨은 참조)

 

2-3. 메일 전송하기

 공통 헤더와 함께 메일 내용까지 만들었기 때문에 이제는 보내는 일만 남았습니다. 위 내용을 가지고 curl 이용해 전송하는 소스는 아래와 같습니다.

<?php

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://mail.apigw.ntruss.com/api/v1/mails");
  curl_setopt($ch, CURLOPT_HEADER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($mailContentsDataSet));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);

 메일 내용은 json_encode() 함수를 이용해 json 형태로 변경해줍니다. 이렇게 하면 기본적인 Cloud Outbound Mailer의 createMailRequest API를 이용해 메일을 전송할 수 있습니다.