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

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)
DKIM(DomainKeys Identified Mail)
Return-Path(Bounce Domain)

SPF(Sender Policy Framework)

SPF는 이메일 발송 서버의 신뢰성을 검증하는 DNS 레코드입니다. NHN 서버가 내 도메인을 대신해 메일을 보낼 수 있도록 허용하는 설정입니다.

DNS Type: TXT

예시:

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

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)

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

예시:

rp.example.com  CNAME  bounce.nhncloudservice.com

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

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

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

예시:

no-reply@yourdomain.com

4. 수신자 데이터 준비

핵클 웹훅으로 이메일을 보내려면 아래 사용자 속성이 수집되어 있어야 합니다.

email
name(선택)

잘못된 이메일 주소가 많으면 발송 제한이 걸릴 수 있습니다. 이메일 주소 형식 검증과 수집 정합성을 함께 관리하는 것을 권장합니다.

웹훅 설정하기

아래 순서대로 설정하면 이메일 발송 웹훅을 구성할 수 있습니다.

웹훅 캠페인 생성

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

그 다음 원하는 캠페인 이름을 입력해 생성합니다.

요청 정보 설정

URL 설정

NHN 이메일 발송 API 에 맞게 HTTP Method 와 URL 을 입력합니다.

Header 설정

Headers 탭에서 추가하기 버튼을 눌러 값을 입력합니다.

발송 대상 유저별로 토큰을 다르게 넣어야 한다면 개인화를 활용할 수 있습니다.

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

{...} 버튼으로 개인화 값을 넣을 수 있습니다.

저장된 사용자 속성이나 이벤트 속성을 활용해 유저별 토큰 값을 동적으로 주입할 수 있습니다.

Body 설정

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

직접 제목과 본문 작성

제목과 본문 안에도 개인화 값을 넣을 수 있습니다.

예를 들어 이름, 가입일, 상품명 같은 값을 사용자별로 다르게 넣을 수 있습니다.

{
  "senderAddress": "no-reply@yourservice.com",
  "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 통계용 필드입니다. 고정 문자열로 관리해도 됩니다.

NHN 템플릿 사용

NHN 템플릿 본문과 제목 안에서 ##user_name##, ##signup_date## 같은 치환 키를 정의한 뒤 templateParameter 와 매칭해 사용합니다.

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"
}