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

{% hint style="info" %}
[NHN 이메일 발송 API](https://docs.nhncloud.com/ko/Notification/Email/ko/Overview/) 를 활용하여 이메일 발송 웹훅 캠페인을 만드는 방법을 소개합니다.
{% endhint %}

### 사전 준비

정상적인 대량 이메일 발송을 위해 사전 준비가 필요합니다.

이 단계는 발송 성공률과 도메인 신뢰도에 직접 영향을 줍니다.

#### 1. NHN Cloud Email 서비스 활성화

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

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

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

{% hint style="danger" %}
2024년 2월 1일부터 [Gmail 발신자 가이드라인](https://support.google.com/a/answer/81126?hl=ko\&visit_id=638991354205057328-2084985656\&rd=1#requirements-5k\&zippy=%2C%ED%95%98%EB%A3%A8%EC%97%90-%EA%B0%9C-%EC%9D%B4%EC%83%81%EC%9D%98-%EB%A9%94%EC%9D%BC%EC%9D%84-%EC%A0%84%EC%86%A1%ED%95%98%EA%B8%B0-%EC%9C%84%ED%95%9C-%EC%9A%94%EA%B5%AC%EC%82%AC%ED%95%AD)이 변경되었습니다.

도메인 인증 및 SPF, DKIM, DMARC 인증을 하지 않을 경우 gmail.com, yahoo.com 도메인에 대한 발송이 요청이 거부될 수 있습니다.
{% endhint %}

대량 발송 시 가장 중요한 단계입니다.

도메인 인증은 스팸 방지, 전달률 향상, 대량 발송 권한 확보에 필수입니다.\
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`(선택)

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

### 웹훅 설정하기

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

{% stepper %}
{% step %}
**웹훅 캠페인 생성**

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

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

{% step %}
**요청 정보 설정**

**URL 설정**

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

![](/files/H4IY50UK3Vm0UyLr7M9S)

**Header 설정**

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

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

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

![](/files/kfsGrwLY70wMtcqGf6KN)

{% hint style="info" %}
`{...}` 버튼으로 개인화 값을 넣을 수 있습니다.

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

{% step %}
**Body 설정**

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

![](/files/w9GsMddxkwEaY3rudJM6)

**직접 제목과 본문 작성**

{% hint style="info" %}
제목과 본문 안에도 개인화 값을 넣을 수 있습니다.

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

```json
{
  "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 템플릿 사용**

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

`user_properties["signup_date"]` 같은 속성을 활용하면 가입일, 구매 금액, 상품명 같은 정보를 쉽게 넣을 수 있습니다.
{% endhint %}

NHN 콘솔에 템플릿을 미리 등록해두었다면 `templateId` 와 `templateParameter` 로 더 깔끔하게 관리할 수 있습니다.

```json
{
  "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 통계용 필드입니다. 고정 문자열로 관리해도 됩니다.
  {% endstep %}

{% step %}
**대상 설정**

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

![](/files/xcbB18A3yLqc2ECMRzm0)

{% hint style="warning" %}
`receiveMailAddr` 가 비어 있으면 NHN API에서 오류가 날 수 있습니다.

웹훅 캠페인 대상 조건에서 이메일 속성이 있는 유저만 필터링하는 것을 권장합니다.
{% endhint %}
{% endstep %}

{% step %}
**발송 설정**

캠페인 설정을 저장하면 아래와 같은 요약 정보를 확인할 수 있습니다.

![](/files/fjlYHhlwCHMLC8I4uC4M)

이제 원하는 발송 조건을 설정합니다.

예를 들면 `스케줄 기반`, `이벤트 기반` 같은 방식입니다.

발송 설정 화면에서 예상 발송 대상도 함께 확인할 수 있습니다.

발송 유형과 고객 피로도 관리를 설정한 뒤 `시작하기` 를 눌러 캠페인을 활성화합니다.

![](/files/aW08kQZfyFo7nI11blnR)
{% endstep %}

{% step %}
**완료**

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

통계 화면에서 캠페인 성과를 추적해보세요.

![](/files/S2ixPL0mYAbOe8rYJDYu)
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hackle.io/crm-marketing/webhook-guide/use-cases/webhook-email-nhn.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.