API เทมเพลตอีเมล

Email Templates API จัดการเทมเพลตอีเมลที่ใช้ซ้ำได้ซึ่งอยู่เบื้องหลังพรีเซ็ตอีเมลของแอปพลิเคชัน — เป็นเทมเพลตเดียวกับที่คุณสร้างในตัวแก้ไขอีเมลของ Control Panel เทมเพลตแต่ละรายการจะจัดเก็บหัวเรื่อง ข้อมูลผู้ส่ง และเนื้อหาจากตัวแก้ไขสำหรับแต่ละภาษา และจะถูกระบุด้วยรหัสของพรีเซ็ตอีเมลที่เชื่อมต่ออยู่ ใช้รหัสนี้เพื่อส่งเทมเพลตผ่าน Notify (เพย์โหลดอีเมล email_template) หรือจุด Send email ใน Customer Journey

URL พื้นฐาน

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

Endpoints ทั้งหมดให้บริการผ่าน HTTPS คำขอและการตอบกลับใช้ application/json เว้นแต่จะระบุไว้เป็นอย่างอื่น

การรับรองความถูกต้อง

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ Server API token ของคุณ:

Authorization: Api YOUR_API_TOKEN

ข้อตกลงทั่วไป

การตั้งชื่อฟิลด์: เนื้อหาของคำขอและพารามิเตอร์ของ query/path ยอมรับ lowerCamelCase (ตัวอย่างเช่น previewSettings, searchByLabel, includeHtml) — เซิร์ฟเวอร์จะ unmarshal ไม่ว่าจะเป็น case ใดก็ตาม การตอบกลับจะถูก marshal โดยใช้ชื่อฟิลด์ของ proto เสมอ ในรูปแบบ snake_case (per_page, email_template, sender_info, preview_settings และอื่นๆ) ตัวอย่างการตอบกลับและ การอ้างอิงอ็อบเจกต์ ด้านล่างใช้ case ดังกล่าว
code: การตอบกลับของเทมเพลตทุกครั้งจะส่งคืนรหัสของพรีเซ็ตอีเมลที่เชื่อมต่ออยู่ ไม่ใช่ ID ภายในของเทมเพลต ส่งรหัสเดียวกันนี้ไปยัง Get, Update, Delete และไปยัง messaging/journey APIs ที่กล่าวถึงข้างต้น
ฟิลด์ที่ไม่ได้ระบุค่า: การตอบกลับจะรวมฟิลด์ทั้งหมด แม้ว่าจะว่างเปล่าหรือมีค่าเป็นศูนย์ก็ตาม

การตอบกลับข้อผิดพลาด

สถานะ HTTP	ความหมาย
`400 Bad Request`	อาร์กิวเมนต์ไม่ถูกต้อง — ฟิลด์ที่จำเป็นขาดหายไปหรือมีรูปแบบไม่ถูกต้อง หรือเงื่อนไขเบื้องต้นไม่สำเร็จ (ตัวอย่างเช่น การลบเทมเพลตที่ยังคงถูกใช้โดย Journey)
`401 Unauthorized`	เฮดเดอร์ `Authorization` ขาดหายไปหรือไม่ถูกต้อง
`403 Forbidden`	แอปพลิเคชันหรือพรีเซ็ตไม่ได้เป็นของบัญชีของผู้เรียก
`404 Not Found`	ไม่พบเทมเพลต, พรีเซ็ต หรือแอปพลิเคชัน
`500 Internal Server Error`	ความล้มเหลวที่ไม่คาดคิดฝั่งเซิร์ฟเวอร์

Endpoints

เมธอด	พาธ	คำอธิบาย
`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 (endpoint นี้ไม่ได้ส่งข้อมูลกลับมา) เรียกใช้ Get ด้วย code ที่ส่งคืนหากคุณต้องการอ่านเนื้อหากลับมา

แสดงรายการ

แสดงรายการเทมเพลตอีเมลของแอปพลิเคชัน — เฉพาะข้อมูลเมตา, ไม่มีเนื้อหา — พร้อมการแบ่งหน้า, การเรียงลำดับ และการกรองตามชื่อ, ป้ายกำกับ หรือหมวดหมู่

GET /api/email_templates

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`application`	string	ใช่	รหัสแอปพลิเคชันที่จะแสดงรายการเทมเพลต
`orderBy`	string	ไม่	`NAME` (ค่าเริ่มต้น), `CREATED` หรือ `UPDATED`
`orderDirection`	string	ไม่	`ASC` (ค่าเริ่มต้น) หรือ `DESC`
`page`	integer	ไม่	ดัชนีหน้าแบบศูนย์
`perPage`	integer	ไม่	ขนาดหน้า ค่าเริ่มต้นคือ `100` เมื่อไม่ได้ระบุหรือเป็น `0` endpoint นี้ไม่ได้บังคับค่าสูงสุดที่ชัดเจน
`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}

พารามิเตอร์ของ Path

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	รหัสของเทมเพลต (รหัสพรีเซ็ตอีเมลที่เชื่อมต่อ)

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`includeHtml`	boolean	ไม่	ระบุว่าจะส่งคืน `html` ที่เรนเดอร์แล้วพร้อมกับเนื้อหาจากตัวแก้ไขหรือไม่ ค่าเริ่มต้นคือ `true` ตั้งค่าเป็น `false` เพื่อข้าม — โดยทั่วไปแล้วมันมีขนาดมากกว่าครึ่งหนึ่งของเพย์โหลด และเนื้อหาจากตัวแก้ไขก็อธิบายเทมเพลตอยู่แล้ว

การตอบกลับ

ส่งคืน { "email_template": { ... } }, อ็อบเจกต์เทมเพลตอีเมล ฉบับเต็ม

อัปเดต

อัปเดตเทมเพลตอีเมลที่มีอยู่ตามรหัส โดยเขียนทับฟิลด์ที่ให้มา

PUT /api/email_templates/{code}

พารามิเตอร์ของ Path

พารามิเตอร์	ประเภท	คำอธิบาย
`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}

พารามิเตอร์ของ Path

พารามิเตอร์	ประเภท	คำอธิบาย
`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 ส่งคืนจริงๆ — ชื่อฟิลด์ของ proto ในรูปแบบ snake_case (ดู ข้อตกลงทั่วไป) เมื่อคุณส่งโครงสร้างเดียวกันนี้กลับไปในเนื้อหาของคำขอ (Create, Update) รูปแบบ lowerCamelCase ที่ใช้ในตัวอย่างคำขอด้านบนก็ใช้ได้เช่นกัน; เซิร์ฟเวอร์ยอมรับ case ใดก็ได้สำหรับอินพุต

อ็อบเจกต์เทมเพลตอีเมล

ฟิลด์	ประเภท	คำอธิบาย
`code`	string	รหัสของพรีเซ็ตอีเมลที่เชื่อมต่อ ใช้ระบุเทมเพลตนี้ในที่อื่นๆ ทั้งหมดใน API
`name`	string	ชื่อเทมเพลต
`label`	string	ป้ายกำกับข้อความอิสระ
`categories`	array of strings	ชื่อหมวดหมู่
`content`	object	อ็อบเจกต์เนื้อหาอีเมล จะมีข้อมูลเมื่อเรียกใช้ `Get` เท่านั้น; จะเป็น `null` ในการตอบกลับของ `Create`, `List` และ `Update`
`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` คือ JSON การออกแบบของ Unlayer
`pushwoosh`	`html`, `localization_data`	`localization_data`	ตัวแก้ไขที่ใช้ HTML ของ Pushwoosh เอง แนะนำสำหรับเทมเพลตที่สร้างผ่านโปรแกรม/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 ไม่ได้ส่งข้อมูลกลับมา) จะรับประกันว่ามีหนึ่ง locale ที่ถูกเปิดเผยเป็น default: หากคุณไม่ได้ส่งคีย์ default มาด้วยตัวเอง ระบบจะโปรโมต en (หรือหากไม่มี en จะใช้คีย์ locale แรกที่พบ) เป็น default โดยทำการเปลี่ยนชื่อ — locale อื่นๆ ทั้งหมดที่คุณส่งมาจะยังคงอยู่เหมือนเดิม subject ก็จะได้รับการจัดการในลักษณะเดียวกัน ซึ่งแตกต่างจาก Clone ที่จะเก็บค่าของ locale ที่เป็นค่าเริ่มต้นไว้เพียงค่าเดียวและทิ้งส่วนที่เหลือไป

การเปลี่ยนชื่อนี้จะถูกนำไปใช้เมื่อสร้างการตอบกลับเท่านั้น — แต่จะไม่ถูกยกเลิกเมื่อทำการเขียนข้อมูล หากคุณนำการตอบกลับจาก Get มาใช้ตามที่เป็นอยู่และส่งไปยัง Update โดยตรง คีย์ที่ถูกโปรโมต (เช่น en) จะกลายเป็น default อย่างแท้จริง และ Update จะจัดเก็บข้อมูลตามที่คุณส่งมาทุกประการ: คีย์ en เดิมจะหายไปอย่างถาวร หากคุณต้องการเก็บคีย์ locale เดิมไว้ คุณต้องเปลี่ยนชื่อ default กลับไปเป็นคีย์เดิมด้วยตนเองก่อนที่จะเรียกใช้ Update

ข้อความภายใน html หรือค่า localization_data สามารถรวมแท็ก Dynamic Content ได้ เช่น {name|string|there} — แท็กเหล่านั้นจะถูกแก้ไขโดยใช้ Tags ของอุปกรณ์ผู้รับเมื่ออีเมลถูกส่งจริงๆ API นี้ไม่ได้แก้ไขแท็กเหล่านั้น; มันเพียงแค่จัดเก็บและส่งคืนข้อความใดๆ ที่คุณใส่ไว้

อ็อบเจกต์ข้อมูลผู้ส่ง

ฟิลด์	ประเภท	คำอธิบาย
`from`	object	`{ "email": string, "name": string }` — ที่อยู่ผู้ส่ง
`reply_to`	object	`{ "email": string, "name": string }` — ที่อยู่สำหรับตอบกลับ

ฟิลด์ย่อย email ทั้งสอง, เมื่อไม่ว่างเปล่า, ต้องเป็นที่อยู่อีเมลที่ถูกต้อง

เกี่ยวข้อง

Notify

Email payload reference

Customer Journey point reference