이메일 템플릿 API

이메일 템플릿 API는 애플리케이션의 이메일 프리셋 뒤에 있는 재사용 가능한 이메일 템플릿을 관리합니다. 이는 Control Panel의 이메일 편집기에서 빌드하는 것과 동일한 템플릿입니다. 각 템플릿은 로케일별 제목, 발신자 정보 및 편집기 콘텐츠를 저장하며, 연결된 이메일 프리셋의 코드로 식별됩니다. 해당 코드를 사용하여 Notify (이메일 페이로드 email_template) 또는 Customer Journey의 이메일 보내기 지점을 통해 템플릿을 보낼 수 있습니다.

기본 URL

https://rpc-api.svc-nue.pushwoosh.com

모든 엔드포인트는 HTTPS를 통해 제공됩니다. 요청 및 응답은 별도로 명시되지 않는 한 application/json을 사용합니다.

인증

모든 요청에는 서버 API 토큰과 함께 Authorization 헤더를 포함해야 합니다:

Authorization: Api YOUR_API_TOKEN

규칙

필드 이름 지정: 요청 본문 및 쿼리/경로 매개변수는 lowerCamelCase(예: previewSettings, searchByLabel, includeHtml)를 허용합니다. 서버는 두 가지 케이싱 모두를 언마샬링합니다. 응답은 항상 프로토 필드 이름을 사용하여 snake_case(per_page, email_template, sender_info, preview_settings 등)로 마샬링됩니다. 아래의 응답 예시와 객체 참조는 해당 케이싱을 사용합니다.
code: 모든 템플릿 응답은 내부 템플릿 ID가 아닌 연결된 이메일 프리셋의 코드를 전달합니다. 이 동일한 코드를 Get, Update, Delete 및 위의 메시징/Journey API에 전달하십시오.
채워지지 않은 필드: 응답은 비어 있거나 값이 0인 경우에도 모든 필드를 포함합니다.

오류 응답

HTTP 상태	의미
`400 Bad Request`	잘못된 인수 — 필수 필드가 누락되었거나 형식이 잘못되었거나, 전제 조건이 실패했습니다(예: Journey에서 아직 사용 중인 템플릿 삭제).
`401 Unauthorized`	`Authorization` 헤더가 누락되었거나 유효하지 않습니다.
`403 Forbidden`	애플리케이션 또는 프리셋이 호출자의 계정에 속하지 않습니다.
`404 Not Found`	템플릿, 프리셋 또는 애플리케이션을 찾을 수 없습니다.
`500 Internal Server Error`	예기치 않은 서버 측 오류입니다.

엔드포인트

메서드	경로	설명
`POST`	`/api/email_templates`	새 이메일 템플릿 생성
`GET`	`/api/email_templates`	애플리케이션의 이메일 템플릿 목록 조회
`GET`	`/api/email_templates/{code}`	단일 이메일 템플릿 가져오기
`PUT`	`/api/email_templates/{code}`	이메일 템플릿 업데이트
`DELETE`	`/api/email_templates/{code}`	이메일 템플릿 삭제
`POST`	`/api/email_templates:clone`	이메일 템플릿을 애플리케이션으로 복제

생성

애플리케이션에 새 이메일 템플릿(편집기 콘텐츠와 연결된 이메일 프리셋)을 생성하고 생성된 템플릿 코드를 반환합니다.

POST /api/email_templates

요청 본문

매개변수	유형	필수	설명
`application`	string	예	템플릿을 생성할 Pushwoosh 애플리케이션 코드입니다.
`name`	string	예	템플릿 이름, 1–255자입니다.
`content`	object	예	이메일 콘텐츠 객체입니다.
`label`	string	아니요	자유 텍스트 레이블, 최대 255자입니다.
`categories`	array of strings	아니요	템플릿에 태그를 지정할 카테고리 이름입니다.
`previewSettings`	object	아니요	임의의 편집기 미리보기 설정으로, 있는 그대로 저장되고 반환됩니다.
`system`	boolean	아니요	템플릿을 시스템 템플릿으로 표시합니다(예: 동기화된 블록 조각과 같은 내부 기능). 시스템 템플릿은 `List`에서 숨겨지지만(아래 참고 참조), 코드로 접근할 수 있습니다. 기본값은 `false`입니다.

요청 예시

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

응답

{ "email_template": { ... } }를 반환합니다. 생성된 이메일 템플릿 객체이지만, content는 포함하지 않습니다(이 엔드포인트는 이를 다시 반환하지 않습니다). 콘텐츠를 다시 읽어야 하는 경우 반환된 code로 Get을 호출하십시오.

애플리케이션의 이메일 템플릿 목록을 메타데이터만(콘텐츠 없음) 페이징, 정렬, 이름, 레이블 또는 카테고리별 필터링과 함께 조회합니다.

GET /api/email_templates

쿼리 매개변수

매개변수	유형	필수	설명
`application`	string	예	템플릿 목록을 조회할 애플리케이션 코드입니다.
`orderBy`	string	아니요	`NAME`(기본값), `CREATED` 또는 `UPDATED`입니다.
`orderDirection`	string	아니요	`ASC`(기본값) 또는 `DESC`입니다.
`page`	integer	아니요	0부터 시작하는 페이지 인덱스입니다.
`perPage`	integer	아니요	페이지 크기입니다. 생략하거나 `0`일 경우 기본값은 `100`입니다. 이 엔드포인트는 명시적인 최대값을 강제하지 않습니다.
`searchByName`	string	아니요	템플릿의 이름 또는 코드에 대한 부분 문자열 일치(`like %value%`)입니다. 둘 중 하나만 일치해도 충분합니다.
`searchByLabel`	string	아니요	레이블에 대한 부분 문자열 일치(`like %label%`) 또는 `strictSearchByLabel`이 `true`일 때 정확한 일치입니다.
`strictSearchByLabel`	boolean	아니요	`searchByLabel`에 대해 부분 문자열 대신 정확한 일치를 사용합니다.
`searchByCategory`	array of strings	아니요	여러 카테고리 중 하나로 필터링하려면 매개변수를 반복합니다(예: `?searchByCategory=lifecycle&searchByCategory=promo`).

응답

필드	유형	설명
`email_templates`	array of objects	현재 페이지의 이메일 템플릿 객체입니다. 모든 항목에서 `content`는 `null`입니다.
`page`	integer	반환된 페이지 인덱스입니다.
`per_page`	integer	이 응답에 사용된 페이지 크기입니다.
`total`	integer	모든 페이지에 걸쳐 필터와 일치하는 총 템플릿 수입니다.

응답 예시

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

가져오기

코드로 단일 이메일 템플릿을 반환하며, 발신자 정보, 로케일별 제목 및 전체 편집기 콘텐츠를 포함합니다.

GET /api/email_templates/{code}

경로 매개변수

매개변수	유형	설명
`code`	string	템플릿의 코드(연결된 이메일 프리셋 코드)입니다.

쿼리 매개변수

매개변수	유형	필수	설명
`includeHtml`	boolean	아니요	편집기 콘텐츠와 함께 렌더링된 `html`을 반환할지 여부입니다. 기본값은 `true`입니다. 이를 건너뛰려면 `false`로 설정하십시오. 일반적으로 페이로드의 절반 이상을 차지하며, 편집기 콘텐츠만으로도 템플릿을 설명할 수 있습니다.

응답

전체 이메일 템플릿 객체인 { "email_template": { ... } }를 반환합니다.

업데이트

코드로 기존 이메일 템플릿을 업데이트하며, 제공된 필드를 덮어씁니다.

PUT /api/email_templates/{code}

경로 매개변수

매개변수	유형	설명
`code`	string	업데이트할 템플릿의 코드입니다.

요청 본문

매개변수	유형	필수	설명
`name`	string	아니요	새 이름, 1–255자입니다. 현재 이름을 유지하려면 생략하십시오.
`content`	object	아니요	저장된 콘텐츠를 완전히 대체하는 새 이메일 콘텐츠 객체입니다. 콘텐츠를 변경하지 않으려면 생략하십시오.
`label`	string	아니요	새 레이블입니다. 항상 덮어쓰여집니다. 지우려면 생략하거나 `""`를 보내십시오.
`categories`	array of strings	아니요	새로운 전체 카테고리 이름 집합입니다. 카테고리를 변경하지 않으려면 생략하고, 지우려면 `[]`를 보내십시오.
`previewSettings`	object	아니요	새 미리보기 설정입니다. 변경하지 않으려면 생략하십시오.

요청 예시

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

응답

{ "email_template": { ... } }를 반환합니다. 업데이트된 이메일 템플릿 객체이며, 이 역시 content는 포함하지 않습니다. 콘텐츠를 다시 읽어야 하는 경우 Get을 호출하십시오.

삭제

코드로 이메일 템플릿과 연결된 프리셋을 삭제하고 저장된 콘텐츠를 제거합니다.

DELETE /api/email_templates/{code}

경로 매개변수

매개변수	유형	설명
`code`	string	삭제할 템플릿의 코드입니다.

응답

성공 시 빈 객체: {}.

복제

이메일 템플릿(콘텐츠와 프리셋)을 대상 애플리케이션으로 복제하며, 선택적으로 새 이름으로 복제할 수 있습니다.

POST /api/email_templates:clone

요청 본문

매개변수	유형	필수	설명
`emailPresetCode`	string	예	복제할 템플릿의 `code`(`Create`, `Get`, `List` 또는 `Update`에서 반환됨)입니다. 연결된 이메일 프리셋의 코드이므로 여기서는 `emailPresetCode`로 명명되었습니다. 규칙을 참조하십시오.
`application`	string	예	대상 애플리케이션 코드입니다. 동일한 애플리케이션이거나 동일한 계정이 소유한 다른 애플리케이션일 수 있습니다.
`name`	string	아니요	복제본의 이름, 1–255자입니다. 기본값은 원본 템플릿의 이름입니다.

요청 예시

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

응답

필드	유형	설명
`email_preset_code`	string	새 템플릿의 `code`입니다. `Get`/`Update`/`Delete`가 `code`라고 부르는 것과 동일한 식별자입니다.

객체 참조

아래 필드 이름은 Get, List, Update, Create가 실제로 반환하는 것과 일치합니다. 즉, snake_case 프로토 필드 이름입니다(규칙 참조). 이 동일한 구조를 요청 본문(Create, Update)으로 다시 보낼 때, 위의 요청 예시에서 사용된 lowerCamelCase 형식도 작동합니다. 서버는 입력 시 두 가지 케이싱 모두를 허용합니다.

이메일 템플릿 객체

필드	유형	설명
`code`	string	연결된 이메일 프리셋의 코드입니다. API의 다른 모든 곳에서 이 템플릿을 식별합니다.
`name`	string	템플릿 이름입니다.
`label`	string	자유 텍스트 레이블입니다.
`categories`	array of strings	카테고리 이름입니다.
`content`	object	이메일 콘텐츠 객체입니다. `Get`에 의해서만 채워지며, `Create`, `List`, `Update` 응답에서는 `null`입니다.
`preview_settings`	object	임의의 편집기 미리보기 설정입니다.
`created`	string (RFC 3339)	생성 타임스탬프입니다.
`updated`	string (RFC 3339)	마지막 업데이트 타임스탬프입니다.

이메일 콘텐츠 객체

필드	유형	설명
`sender_info`	object	발신자 정보 객체 — `from` 및 `reply_to` 주소입니다.
`subject`	object (map)	로케일별 제목, 예: `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	편집기 콘텐츠입니다. 이 중 정확히 하나만 설정해야 합니다. 이는 어떤 편집기가 템플릿을 생성했는지(그리고 렌더링할 것인지) 선택합니다. 아래 편집기 종류를 참조하십시오.

편집기 종류

종류	필드	필수 하위 필드	설명
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	드래그 앤 드롭 블록 편집기(Unlayer)입니다. `editor_config`는 Unlayer 디자인 JSON입니다.
`pushwoosh`	`html`, `localization_data`	`localization_data`	Pushwoosh 자체의 HTML 기반 편집기입니다. 프로그래밍 방식/API 작성 템플릿에 권장됩니다.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Smart Cards 블록 편집기입니다. `content`는 해당 편집기별 JSON입니다.

모든 종류에서 html은 렌더링된 출력입니다. localization_data는 해당 편집기 자체의 로케일별 콘텐츠입니다. 로케일 코드(en, es, default, …)로 키가 지정된 객체이며, 각 값은 해당 로케일의 편집기 필드 사본입니다. 내부 구조는 편집기별로 다르며 이 API에는 불투명합니다. API는 이를 있는 그대로 저장하고 반환합니다. Create/Update 시 모든 종류에 대해 필수입니다(지역화할 내용이 없으면 {}를 보내십시오).

API가 content를 반환할 때마다(현재는 Get만 해당, Create 및 Update는 이를 다시 반환하지 않으므로), 하나의 로케일이 default로 노출되도록 보장합니다. default 키를 직접 보내지 않은 경우, en(또는 그것도 없으면 가장 먼저 오는 로케일 키)을 default로 승격시키고 이름을 바꿉니다. 보낸 다른 모든 로케일은 그대로 유지됩니다. subject도 동일하게 처리됩니다. 이는 Clone과는 다릅니다. Clone은 해당 기본 로케일 값만 유지하고 나머지는 삭제합니다.

이 이름 변경은 응답을 빌드할 때만 적용되지만, 쓰기 시에는 되돌려지지 않습니다. Get 응답을 그대로 가져와 Update로 바로 보내면, 승격된 키(예: en)는 이제 문자 그대로 default가 되며, Update는 보낸 내용을 정확히 저장합니다. 원래 en 키는 그 이후로 영구적으로 사라집니다. 원래 로케일 키를 유지해야 하는 경우, Update를 호출하기 전에 default를 다시 원래 키로 직접 변경하십시오.

html 또는 localization_data 값 내의 텍스트에는 동적 콘텐츠 태그(예: {name|string|there})가 포함될 수 있습니다. 이러한 태그는 이메일이 실제로 전송될 때 수신자의 장치 태그에 대해 확인됩니다. 이 API는 이를 확인하지 않으며, 입력한 텍스트를 그대로 저장하고 반환합니다.

발신자 정보 객체

필드	유형	설명
`from`	object	`{ "email": string, "name": string }` — 발신자 주소입니다.
`reply_to`	object	`{ "email": string, "name": string }` — 회신 주소입니다.

두 email 하위 필드는 비어 있지 않을 경우 유효한 이메일 주소여야 합니다.

이메일 템플릿 API

기본 URL

인증

규칙

오류 응답

엔드포인트

생성

요청 본문

요청 예시

응답

목록

쿼리 매개변수

응답

응답 예시

가져오기

경로 매개변수

쿼리 매개변수

응답

업데이트

경로 매개변수

요청 본문

요청 예시

응답

삭제

경로 매개변수

응답

복제

요청 본문

요청 예시

응답

객체 참조

이메일 템플릿 객체

이메일 콘텐츠 객체

편집기 종류

발신자 정보 객체

관련