가이드 문서
Go to Docs (EN)핵클 홈페이지도입 문의
Start typing to search…

웹훅으로 이메일 보내기 (NHN클라우드)

Suggest Edit

업체에서 제공하는 API를 참고하여 웹훅 캠페인을 생성할 수 있습니다. 이번에는

NHN 이메일 발송 API 를 활용하여 이메일 발송 웹훅을 만드는 경우를 알아보도록 하겠습니다.


사전 준비

정상적인 이메일 대량 발송을 위해서, 사전 준비가 필요합니다. 대량 발송·스팸 차단 방어·도메인 신뢰도 확보를 위해 반드시 필요합니다.

구체적인 내용은 이메일 발송 서비스를 제공하는 업체마다 상이할 수 있습니다.


1. NHN Cloud Email 서비스 활성화

NHN 클라우드 가입 및 콘솔에서 Email 서비스 활성화가 필요합니다.

NHN 클라우드 콘솔에서 appKey, X-Secret-Key 를 확인해주세요.


2. 발신자 도메인 인증(Domain Authentication)

대량 발송 시 가장 중요한 단계입니다. 도메인 인증은 스팸 방지·전달률 향상·대량 발송 권한 확보에 필수적입니다.

❗️

2024년 2월 1일부터 Gmail 발신자 가이드라인이 변경되어 도메인 인증 및 SPF, DKIM, DMARC 인증을 하지 않을 경우 gmail.com, yahoo.com 도메인에 대한 발송이 요청이 거부될 수 있습니다.

NHN 클라우드 사용시 도메인 등록 후, 아래 DNS 값을 설정해야 합니다.


① SPF(Sender Policy Framework)

SPF는 이메일 발송자의 신뢰성을 검증하기 위한 메커니즘으로, 이메일 서버가 특정 도메인에서 발송된 메일이 실제로 허가된 서버에서 왔는지 확인합니다. 메일 발송 중 발신자의 DNS에 등록된 SPF 레코드를 확인하여 등록되지 않은 IP 주소에서 보낸 메일을 스팸 메일로 처리할 수 있습니다.

즉, NHN 서버가 사용자의 도메인 대신 메일을 보낼 수 있도록 인증하는 DNS 레코드라고 보시면 됩니다.

DNS Type: TXT

예시 :

v=spf1 include:mail.nhncloudservice.com ~all

② DKIM(DomainKeys Identified Mail)

DKIM(domainkeys identified mail)은 이메일 발신자가 이메일에 디지털 서명을 하여 발신자의 진위 여부를 확인하고 전송 중에 메시지가 변조되지 않았는지 확인할 수 있는 이메일 인증 방법입니다. DKIM을 통해 스팸 발송자 및 기타 악의적인 공격자가 이메일을 위조하는 것을 방지할 수 있습니다. 이메일 위변조를 방지하기 위한 공개키 기반 서명으로, NHN 콘솔에서 DKIM 공개키를 확인할 수 있습니다.

DNS Type: TXT

예시:

selector._domainkey.example.com  IN TXT  "v=DKIM1; k=rsa; p=공개키..."

③ Return-Path(Bounce Domain)

반송 메일(Bounce mail) 수신 경로 설정하는 것 또한 매우 중요합니다.

NHN 클라우드에서는 별도 Return-Path 도메인을 제공하며, 이를 CNAME 으로 설정해야합니다.

예시:

rp.example.com  CNAME  bounce.nhncloudservice.com

3. 발신자 메일 주소 등록(Verified Sender)

이메일을 발송할 도메인과 주소를 NHN 콘솔에서 등록해야합니다.

DKIM, SPF가 구성되어야 발신자 메일 주소가 정상적으로 검증됩니다.

예: [email protected]


4. 수신자 데이터 준비

핵클 웹훅으로 이메일 발송하기 위해서 핵클 사용자 속성로 다음 정보가 수집되어야합니다. 사용자 속성 API 가이드

email, name (선택)

대량 발송 시 잘못된 이메일 주소가 많으면 벤더 측에서 발송 제한이 걸릴 수 있으므로 정확한 이메일 주소가 수집되도록 정합성 검증이 필요합니다.


캠페인 설정

캠페인 생성

핵클 대시보드에서 웹훅 메뉴를 클릭한뒤, 생성하기 버튼을 클릭합니다.

URL 설정

먼저 NHN 메시지 발송 API 에 맞게 http method 와 URL 을 입력합니다.

Header 설정

Headers 탭에서 '추가하기' 버튼을 눌러 Key 와 Value 에 다음과 같이 세팅합니다.

NHN에서 발급받은 X-Secret-Key와 accesstoken 을 발송 대상 유저별로 동적으로 추가하기 위해 개인화를 활용하였습니다.

Key : Authorization

Value: {{user_properties.authorization_type}} {{user_properties.access_token}}

📘

개인화 활용

{...} 를 눌러 개인화 메세지를 작성하는 것과 마찬가지로 이미 저장된 유저 및 이벤트 속성 을 활용해 위 예시와 같이 유저별 토큰 값 등을 동적으로 주입하는 등, 웹훅 메시지에 캠페인 설정 시에 활용할 수 있습니다.

Body 설정

웹훅 Body 탭을 JSON 모드로 두고, NHN “일반 메일 발송” Request Body 규격에 맞춰서 JSON을 작성합니다.


Email Delivery Body Sample - 제목/본문 직접 작성

📘

개인화 활용

{...} 를 눌러 개인화 메세지를 작성하는 것과 마찬가지로 이미 저장된 유저 및 이벤트 속성 을 활용해 아래 예시와 같이 유저별 전화번호 등을 동적으로 주입하는 등, 웹훅 메시지에 캠페인 설정 시에 활용할 수 있습니다.

{
  "senderAddress": "[email protected]",
  "senderName": "YourService",
  "title": "회원가입이 완료되었습니다",
  "body": "안녕하세요  {{user_properties["name"] | default: "회원"}}님,\n회원가입을 환영합니다!",
  "receiverList": [
    {
      "receiveMailAddr": "{{user_properties["email"] | default: ""}}",
      "receiveName": "{{user_properties["name"] | default: "회원"}}",
      "receiveType": "MRT0"
    }
  ],
  "userId": "hackle-webhook",
  "statsId": "hackle-email"
}

  • receiveType은 보통 수신자 본인에게 보내는 경우 MRT0로 고정합니다.
  • userId, statsId는 NHN 통계/구분용 필드이며, 고정 문자열로 관리해도 됩니다.


Email Delivery Body Sample - NHN 템플릿 사용

📘
  • NHN 템플릿 본문/제목 안에서 ##user_name##, ##signup_date## 같은 치환 키를 정의하고, 위 templateParameter의 key와 맞춰 사용합니다.
  • user_properties["signup_date"] 처럼 이벤트 속성을 활용하면 “가입일”, “구매 금액”, “상품명” 등의 맥락 있는 내용을 쉽게 넣을 수 있습니다.

NHN 콘솔에 미리 템플릿을 등록해 두었다면, 에디터를 이용해서 쉽게 내용을 작성하고, templateId와 templateParameter를 활용해 보다 깔끔하게 관리할 수 있습니다.

{
  "templateId": "WELCOME_TEMPLATE",
  "templateParameter": {
    "user_name": "{{ user_properties[\"name\"] | default: \"회원\" }}",
    "signup_date": "{{ user_properties[\"signup_date\"] | default: \"\" }}"
  },
  "receiverList": [
    {
      "receiveMailAddr": "{{ user_properties[\"email\"] | default: \"\" }}",
      "receiveName": "{{ user_properties[\"name\"] | default: \"\" }}",
      "receiveType": "MRT0"
    }
  ],
  "userId": "hackle-webhook",
  "statsId": "hackle-email-template"
}

  • receiveType은 보통 수신자 본인에게 보내는 경우 MRT0로 고정합니다.
  • userId, statsId는 NHN 통계/구분용 필드이며, 고정 문자열로 관리해도 됩니다.

대상 설정

웹훅 발송 대상이 될 코호트를 설정합니다.

🚧

receiveMailAddr가 비어 있으면 NHN API에서 오류가 날 수 있으므로, 웹훅 캠페인의 대상 조건에서 속성 기반으로 “이메일 속성"이 존재하는 유저만 필터링하는 것을 권장합니다.

요약

이제 웹훅을 캠페인 설정을 저장합니다. 아래와 같은 요약 정보를 확인할 수 있습니다.


발송 설정

이제 원하는 발송 조건을 설정할 수 있습니다. (스케쥴 기반, 이벤트 기반 등)

발송 설정 화면에서 예상 발송 대상에 대한 정보를 확인할 수 있습니다.

발송 유형 및 고객 피로도 관리를 세팅한 후 '시작하기'를 눌러 캠페인을 활성화 합니다.


완료

이메일 웹훅 캠페인 활성화가 완료되었습니다.

통계 부분을 확인하여 캠페인의 성과를 추적해보세요

Updated about 1 hour ago