> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTML로 이메일 디자인하기

> OneSignal의 HTML 에디터를 사용하여 완전히 사용자 지정된 브랜드 이메일을 보내세요 — 지원되는 HTML 규칙, 인라인 CSS, 다크 모드, 구독 취소 처리, 클라이언트 제한 사항.

## 개요

HTML 에디터를 사용하면 자체 HTML로 완전히 사용자 지정된 브랜드 이메일을 보낼 수 있습니다.

다음과 같은 경우 HTML 에디터를 사용해야 합니다:

* 레이아웃, 간격, 스타일링을 완전히 제어해야 하는 경우
* 이미 프로덕션 준비가 완료된 HTML 이메일 템플릿이 있는 경우
* 이메일 클라이언트 제한 사항 내에서 작업하는 것에 익숙한 경우

<Info>
  HTML 이메일은 웹 페이지와 다릅니다. 많은 HTML 및 CSS 기능이 이메일 클라이언트 간에 지원되지 않거나 일관되지 않게 렌더링됩니다.
</Info>

### 전제 조건

HTML 에디터를 사용하기 전에 다음을 확인하세요:

* 반응형 HTML 이메일 구축 경험이 있는지 확인
* 모든 이미지를 공개적으로 액세스 가능한 URL(사이트, CDN, S3 등)에서 호스팅

#### 예상 결과

설정 후 이메일은:

* 주요 클라이언트(Gmail, Outlook, Apple Mail)에서 일관되게 렌더링됨
* 링크 클릭을 올바르게 추적함
* 작동하는 구독 취소 메커니즘이 포함됨
* 스팸 및 전달 가능성 검사를 통과함

### 자체 템플릿 가져오기

이미 HTML 이메일 템플릿이 있는 경우 다음 방법 중 하나로 OneSignal에 추가할 수 있습니다:

1. [이메일 템플릿 전달](./email-template-forwarding) 사용
2. [Create Template API](/reference/create-template)를 사용하여 프로그래밍 방식으로 템플릿 생성
3. HTML을 HTML 에디터에 복사 및 붙여넣기

<Tip> 처음부터 HTML을 작성하는 것보다 검증된 템플릿으로 시작하는 것을 권장합니다. </Tip>

### Figma에서 디자인하고 OneSignal로 내보내기

이메일 디자인이 Figma에 있는 경우, HTML로 OneSignal에 가져오는 두 가지 방법이 있습니다:

* **[Email Love](https://emaillove.com/figma-plugin)**: 디자인을 프로덕션 준비가 완료된 HTML 이메일로 변환하고 OneSignal 템플릿에 직접 업로드하는 Figma 플러그인입니다. 플러그인의 내보내기 패널에 OneSignal App ID와 API 키를 입력하고 업로드를 클릭하세요.
* **[Figma MCP 서버](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server)**: MCP 서버를 통해 Figma를 AI 코딩 도구에 연결하세요. 이메일 디자인 프레임을 지정하고 HTML 이메일 코드를 생성하도록 요청한 다음 출력을 HTML 에디터에 붙여넣으세요.

<Warning>
  **렌더링 또는 전달 가능성 문제를 유발하는 일반적인 실수:**

  * **구독 취소 링크 누락** — 마케팅 이메일에 필수입니다. 없으면 받은 편지함 제공자가 스팸으로 표시할 가능성이 높아집니다.
  * **인라인 CSS 대신 `<style>` 블록 사용** — 대부분의 이메일 클라이언트가 `<style>` 태그를 제거합니다. 항상 스타일을 인라인으로 작성하세요.
  * **폴백 폰트 없음** — 사용자 지정 웹 폰트는 일부 클라이언트에서만 로드됩니다. 항상 시스템 폰트 폴백을 선언하세요.
  * **이미지 크기 초과** — 1 MB를 초과하는 이메일은 로드 속도가 느리고 차단될 수 있습니다. 개별 이미지는 200 KB 미만이어야 합니다.
  * **지원되지 않는 HTML** — JavaScript, `<iframe>`, 폼, 임베디드 미디어는 이메일 클라이언트에서 제거됩니다.
</Warning>

***

## HTML 에디터 사용

이메일 메시지를 만들 때 편집기 유형으로 **HTML 에디터**를 선택합니다.

1. 에디터에 HTML을 붙여넣거나 작성합니다.
2. **테스트 이메일 보내기**를 사용하여 클라이언트와 기기 간 렌더링을 미리 봅니다.
3. 예약하거나 보내기 전에 레이아웃 문제를 수정합니다.

<Frame caption="코드 입력 및 라이브 미리보기가 있는 HTML 에디터">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/966f520-html-editor-preheader.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=ceece56a7c1c52b3a51badea42685768" alt="HTML editor with code input and live preview" width="1300" height="1238" data-path="images/docs/966f520-html-editor-preheader.png" />
</Frame>

### 링크 및 추적

링크 추적은 HTML 이메일에서 기본적으로 활성화됩니다. 다중 링크 추적이 지원되며, 클릭은 메시지 보고서에 표시됩니다.

<Columns cols={2}>
  <Card title="링크" icon="link" href="./links#email">
    이메일의 링크 추적, 다중 링크 추적, 클릭 분석을 구성합니다.
  </Card>

  <Card title="딥 링킹" icon="arrow-up-right-from-square" href="./deep-linking">
    이메일 링크에서 앱의 특정 화면으로 수신자를 이동시킵니다.
  </Card>
</Columns>

#### 구독 취소 링크

모든 마케팅 이메일에는 구독 취소 링크가 포함되어야 합니다.

유효한 구독 취소 옵션이 없는 이메일은 다음 가능성이 높습니다:

* 스팸으로 표시됨
* 발신자 평판 손상
* 받은 편지함 제공자에 의해 차단됨

<Tabs>
  <Tab title="OneSignal의 기본 구독 취소 링크">
    HTML의 아무 곳에나(일반적으로 바닥글) 다음 자리 표시자를 포함하세요:

    ```html HTML theme={null}
    <a href="[unsubscribe_url]">구독 취소</a>
    ```

    클릭하면 이 링크는 OneSignal에서 수신자의 이메일 [구독](./subscriptions)을 취소합니다.
  </Tab>

  <Tab title="사용자 지정 구독 취소 페이지 사용(선택 사항)">
    자체 구독 취소 페이지에 링크할 수 있지만 다음을 수행해야 합니다:

    * 구독 취소 작업 캡처
    * 수신자의 이메일 구독 상태 업데이트

    자세한 내용은 [사용자 지정 구독 취소 페이지 만들기](./create-custom-unsubscribe-page)를 참조하세요.

    <Warning> 사용자 지정 구독 취소 URL을 사용하고 구독을 업데이트하지 않으면 사용자가 계속 이메일을 받게 됩니다. </Warning>
  </Tab>
</Tabs>

***

## HTML 이메일 모범 사례

### 항상 인라인 CSS 사용

대부분의 이메일 클라이언트는 `<style>` 블록과 외부 스타일시트를 제거합니다.

이 도구를 사용해 보세요: [Responsive Email CSS Inliner](https://htmlemail.io/inline/)

### 다크 모드 스타일링

많은 이메일 클라이언트는 다크 모드가 활성화된 경우 자동 색상 반전을 적용합니다. 이로 인해 버튼이 검은색 배경과 검은색 텍스트로 표시되거나 로고가 사라지는 등 예측할 수 없는 결과가 발생할 수 있습니다. 이러한 문제를 방지하려면 라이트 모드와 다크 모드 모두에서 이메일이 어떻게 보여야 하는지 명시적으로 정의하세요.

#### 이메일 클라이언트의 다크 모드 처리 방식

| 클라이언트                      | 동작                             | `prefers-color-scheme` CSS 준수 여부 |
| -------------------------- | ------------------------------ | -------------------------------- |
| **Apple Mail** (iOS/macOS) | 전체 색상 반전                       | 예                                |
| **Gmail** (iOS/Android 앱)  | 부분 반전 — 밝은 배경은 변경하지만 모든 색상은 아님 | 아니오                              |
| **Gmail** (웹)              | 다크 모드 렌더링 없음                   | 해당 없음                            |
| **Outlook** (Windows)      | Word 렌더링 엔진을 사용한 전체 반전         | 아니오 — 대부분의 CSS 재정의 무시            |
| **Outlook** (Mac/iOS)      | 부분 반전                          | 예                                |
| **Yahoo Mail**             | 부분 반전                          | 아니오                              |
| **Samsung Mail**           | 전체 반전                          | 아니오                              |

#### 모범 사례

* **인라인으로 기본 스타일을 정의하세요.** 기본값이나 투명도에 의존하는 대신 항상 요소에 직접 배경 및 텍스트 색상을 설정하세요.
* **다크 모드에 미디어 쿼리를 사용하세요.** `@media (prefers-color-scheme: dark)`를 지원하는 클라이언트(Apple Mail, Outlook Mac/iOS)는 다크 모드에 대한 스타일을 재정의할 수 있습니다.
* **`!important`를 신중하게 적용하세요.** 다크 모드 재정의에 `!important`를 추가하면 받은 편지함이 사용자 지정 스타일 위에 반전 규칙을 쌓는 것을 방지하는 데 도움이 됩니다.
* **테마 지원을 신호하세요.** 자동 반전을 줄이기 위해 HTML `<head>`에 다음 메타 태그를 포함하세요:

```html theme={null}
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
```

* **순수한 흰색과 순수한 검은색을 피하세요.** 오프화이트와 짙은 회색을 사용하면 전체 반전 클라이언트의 영향을 줄일 수 있습니다.
* **투명 PNG를 주의해서 사용하세요.** 투명 배경의 어두운 로고는 다크 배경에서 보이지 않게 됩니다. 밝은 윤곽선을 추가하거나 내장 배경이 있는 버전을 사용하세요.

<Note>
  드래그 앤 드롭 에디터를 사용하여 다크 모드 CSS를 추가하는 단계별 안내는 [드래그 앤 드롭으로 다크 모드 스타일링](./design-emails-with-drag-and-drop#dark-mode-styling-with-drag-and-drop)을 참조하세요.
</Note>

### 이메일용 권장 이미지 크기

<AccordionGroup>
  <Accordion title="종횡비">
    * 헤더/배너 이미지: `3:1` 또는 `4:1` (예: `600×200` 또는 `600×150`)
    * 히어로 이미지: `16:9` 또는 `2:1` (예: `600×338` 또는 `600×300`)
    * 정사각형 이미지: `1:1` (예: `300×300`) — 제품 그리드에 적합
    * 썸네일: `1:1` 또는 `4:3`
    * 최대 너비: `600–700px`가 표준 (대부분의 이메일 클라이언트)
    * 레티나 디스플레이를 위해 `2x`로 디자인 (예: `1200px` 너비, `600px`로 표시)
  </Accordion>

  <Accordion title="파일 크기">
    * 개별 이미지를 `100–200 KB` 미만으로 유지
    * 총 이메일 크기(이미지 포함)를 `1 MB` 미만으로 유지
    * 이미지가 작을수록 로드 시간이 빠르고 전달 가능성이 향상됨
  </Accordion>

  <Accordion title="파일 형식">
    * **JPG** — 사진에 가장 적합
    * **PNG** — 그래픽, 로고, 투명도가 있는 이미지에 가장 적합
    * **GIF** — 간단한 애니메이션용 (파일 크기를 작게 유지)
    * **WebP** — 이메일에서 아직 널리 지원되지 않음; 사용 금지
  </Accordion>

  <Accordion title="일반 팁">
    * 접근성을 위해, 이미지가 로드되지 않을 때를 위해 항상 alt 텍스트를 포함
    * 스타일링에 인라인 CSS 사용 (많은 클라이언트가 `<style>` 태그를 제거)
    * 배경 이미지 피하기 (일관되지 않은 클라이언트 지원)
    * 클라이언트 간 테스트 — Gmail, Outlook, Apple Mail 모두 다르게 렌더링
    * Outlook은 종종 이미지 치수를 무시하므로 HTML에서 `width`와 `height` 속성을 모두 설정
  </Accordion>
</AccordionGroup>

### 이미지에 alt 텍스트 추가

Alt 텍스트는 접근성을 향상시키고 이미지가 차단되거나 로드에 실패하더라도 정보가 전달되도록 합니다. 대부분의 주요 이메일 클라이언트는 alt 텍스트를 표시하고 스타일을 적용합니다:

| 이메일 클라이언트 | 이미지 차단? | Alt 텍스트 표시 | Alt 텍스트 스타일 적용 |
| --------- | ------- | ---------- | -------------- |
| AOL       | 예       | 예          | 예              |
| Gmail     | 예       | 예          | 예              |
| Yahoo     | 예       | 예          | 예              |
| Outlook   | 때때로     | 예          | 예              |

### 지원되는 HTML만 사용

이메일 클라이언트는 다음을 **지원하지 않습니다**:

* JavaScript
* `<iframe>`
* HTML 폼
* 임베디드 오디오 또는 비디오
* CSS 위치 지정 또는 레이어링 트릭

인터랙티브 또는 멀티미디어 콘텐츠에는 외부 페이지로의 링크를 사용하세요.

### 전송 전 확인

전송하기 전에 다음을 확인하세요:

* 모든 링크 작동 여부 (끊어진 링크는 전달 가능성을 저하시키고 스팸 필터를 유발할 수 있음)
* 구독 취소 링크가 올바르게 작동하는지 확인
* Gmail, Outlook, Apple Mail에서 테스트 이메일 렌더링 확인
* 다크 모드 렌더링이 적절한지 확인
* HTML에 접근성 및 유지 관리를 위한 의미론적 태그와 적절한 들여쓰기 사용 여부

<Check> 이메일이 주요 클라이언트에서 올바르게 렌더링되고 구독 취소가 작동하면 전송할 준비가 된 것입니다. </Check>

### 개인화

Liquid 템플릿을 사용하여 HTML에 이름, 태그, 폴백 값 등 구독자별 콘텐츠를 직접 삽입하세요. 예: `{{ first_name | default: "there" }}`

<Columns cols={2}>
  <Card title="메시지 개인화" icon="user-pen" href="./message-personalization">
    사용 가능한 개인화 변수와 사용 방법.
  </Card>

  <Card title="Liquid 구문 사용" icon="code" href="./using-liquid-syntax">
    조건문, 필터, 루프, 고급 Liquid 패턴.
  </Card>
</Columns>

***

## FAQ

### 기존 이메일 템플릿을 재사용할 수 있나요?

예. [이메일 템플릿 전달](./email-template-forwarding)을 통해 OneSignal에 전달하거나, [Create Template API](/reference/create-template)로 업로드하거나, HTML을 에디터에 직접 복사 및 붙여넣기 하세요.

### 사용자 지정 글꼴을 사용할 수 있나요?

예, 하지만 지원이 다양합니다. `@font-face`로 사용자 지정 글꼴을 선언하고 항상 시스템 글꼴 폴백을 포함하세요. Windows의 Outlook은 웹 글꼴을 완전히 무시하고 시스템 기본값으로 폴백합니다.

### 이메일이 다크 모드에서 다르게 보이는 이유는 무엇인가요?

각 이메일 클라이언트는 다크 모드를 다르게 적용합니다 — 일부는 색상을 완전히 반전시키고, 일부는 부분적으로 반전시키며, Gmail 웹은 다크 모드를 전혀 적용하지 않습니다. 자세한 내용은 위의 [클라이언트 동작 표](#이메일-클라이언트의-다크-모드-처리-방식)를 참조하세요. 명시적인 라이트 모드 및 다크 모드 스타일을 정의하여 렌더링을 제어하세요.

### 이메일에서 지원되지 않는 HTML 및 CSS 기능은 무엇인가요?

JavaScript, `<iframe>`, HTML 폼, 임베디드 오디오/비디오, CSS 위치 지정은 지원되지 않습니다. 모든 스타일링에 인라인 CSS를 사용하세요 — 대부분의 클라이언트가 `<style>` 블록과 외부 스타일시트를 제거합니다.

### 이메일에 "브라우저에서 보기" 링크를 추가할 수 있나요?

OneSignal은 이메일의 호스팅된 웹 버전을 생성하지 않습니다. "브라우저에서 보기" 환경을 제공하려면 자체 웹사이트에 이메일 콘텐츠를 호스팅하고 해당 호스팅된 페이지를 가리키는 표준 HTML 링크를 추가하세요.

### 최대 이메일 크기는 얼마인가요?

총 이메일 크기(HTML + 이미지)를 1 MB 미만으로 유지하세요. HTML이 102 KB를 초과하는 이메일은 Gmail에서 잘려, 접힌 아래의 콘텐츠가 "전체 메시지 보기" 링크 뒤에 숨겨집니다.

## 관련 페이지

<Columns cols={3}>
  <Card title="드래그 앤 드롭으로 이메일 디자인하기" icon="paintbrush" href="./design-emails-with-drag-and-drop">
    전체 HTML 작성 없이 이메일을 디자인할 수 있는 시각적 이메일 빌더.
  </Card>

  <Card title="이메일 개요" icon="envelope" href="./email-messaging">
    OneSignal로 이메일을 전송하는 엔드투엔드 가이드.
  </Card>

  <Card title="이메일 템플릿" icon="copy" href="./templates">
    캠페인 전반에서 이메일 디자인을 저장하고 재사용합니다.
  </Card>

  <Card title="구독 취소 링크" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    규정 준수를 위한 기본 또는 사용자 지정 구독 취소 링크 추가.
  </Card>

  <Card title="메시지 개인화" icon="user-pen" href="./message-personalization">
    태그, Liquid 구문, 동적 콘텐츠로 이메일을 개인화합니다.
  </Card>

  <Card title="이메일 템플릿 전달" icon="envelope-open-text" href="./email-template-forwarding">
    기존 HTML 이메일 템플릿을 OneSignal로 가져옵니다.
  </Card>
</Columns>