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

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

URL พื้นฐาน

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

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

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

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

Authorization: Api YOUR_API_TOKEN

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

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

การตอบสนองข้อผิดพลาด

สถานะ 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

เนื้อหาของคำขอ

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

แสดงรายการ

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

GET /api/email_templates

พารามิเตอร์ของคิวรี

พารามิเตอร์	Type	จำเป็น	คำอธิบาย
`application`	string	ใช่	โค้ดแอปพลิเคชันที่จะแสดงรายการเทมเพลต
`orderBy`	string	ไม่	`NAME` (ค่าเริ่มต้น), `CREATED`, หรือ `UPDATED`
`orderDirection`	string	ไม่	`ASC` (ค่าเริ่มต้น) หรือ `DESC`
`page`	integer	ไม่	ดัชนีหน้าแบบศูนย์
`perPage`	integer	ไม่	ขนาดของหน้า ค่าเริ่มต้นคือ `100` เมื่อละเว้นหรือเป็น `0` เอนด์พอยต์นี้ไม่ได้บังคับค่าสูงสุดที่ชัดเจน
`searchByName`	string	ไม่	การจับคู่สตริงย่อย (`like %value%`) กับชื่อของเทมเพลต หรือ โค้ดของมัน — การจับคู่ใดก็ได้ก็เพียงพอ
`searchByLabel`	string	ไม่	การจับคู่สตริงย่อยบนป้ายกำกับ (`like %label%`) หรือการจับคู่แบบตรงทั้งหมดเมื่อ `strictSearchByLabel` เป็น `true`
`strictSearchByLabel`	boolean	ไม่	ใช้การจับคู่แบบตรงทั้งหมดแทนสตริงย่อยสำหรับ `searchByLabel`
`searchByCategory`	array of strings	ไม่	ทำซ้ำพารามิเตอร์เพื่อกรองตามหมวดหมู่หลายรายการ, เช่น `?searchByCategory=lifecycle&searchByCategory=promo`

การตอบสนอง

ฟิลด์	Type	คำอธิบาย
`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}

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

พารามิเตอร์	Type	คำอธิบาย
`code`	string	โค้ดของเทมเพลต (โค้ดพรีเซ็ตอีเมลที่เชื่อมต่ออยู่)

พารามิเตอร์ของคิวรี

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

การตอบสนอง

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

อัปเดต

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

PUT /api/email_templates/{code}

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

พารามิเตอร์	Type	คำอธิบาย
`code`	string	โค้ดของเทมเพลตที่จะอัปเดต

เนื้อหาของคำขอ

พารามิเตอร์	Type	จำเป็น	คำอธิบาย
`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}

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

พารามิเตอร์	Type	คำอธิบาย
`code`	string	โค้ดของเทมเพลตที่จะลบ

การตอบสนอง

อ็อบเจกต์ว่างเปล่าเมื่อสำเร็จ: {}

โคลน

โคลนเทมเพลตอีเมล — เนื้อหาและพรีเซ็ต — ไปยังแอปพลิเคชันปลายทาง, และสามารถตั้งชื่อใหม่ได้

POST /api/email_templates:clone

เนื้อหาของคำขอ

พารามิเตอร์	Type	จำเป็น	คำอธิบาย
`emailPresetCode`	string	ใช่	`code` ของเทมเพลต (ที่ส่งคืนโดย `Create`, `Get`, `List`, หรือ `Update`) ที่จะโคลน ถูกตั้งชื่อว่า `emailPresetCode` ที่นี่เพราะเป็นโค้ดของพรีเซ็ตอีเมลที่เชื่อมต่ออยู่ — ดู ข้อตกลงทั่วไป
`application`	string	ใช่	โค้ดแอปพลิเคชันปลายทาง สามารถเป็นแอปพลิเคชันเดียวกัน, หรือแอปพลิเคชันอื่นที่เป็นของบัญชีเดียวกัน
`name`	string	ไม่	ชื่อสำหรับโคลน, 1–255 ตัวอักษร ค่าเริ่มต้นคือชื่อของเทมเพลตต้นฉบับ

ตัวอย่างคำขอ

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

การตอบสนอง

ฟิลด์	Type	คำอธิบาย
`email_preset_code`	string	`code` ของเทมเพลตใหม่ — ตัวระบุเดียวกับที่ `Get`/`Update`/`Delete` เรียกใช้ `code`

การอ้างอิงอ็อบเจกต์

ชื่อฟิลด์ด้านล่างตรงกับสิ่งที่ Get, List, Update, และ Create ส่งคืนจริงๆ — ชื่อฟิลด์ของ proto ในรูปแบบ snake_case (ดู ข้อตกลงทั่วไป) เมื่อคุณส่งโครงสร้างเดียวกันนี้กลับไปในเนื้อหาของคำขอ (Create, Update), รูปแบบ lowerCamelCase ที่ใช้ในตัวอย่างคำขอด้านบนก็ใช้ได้เช่นกัน; เซิร์ฟเวอร์ยอมรับทั้งสองรูปแบบในอินพุต

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

ฟิลด์	Type	คำอธิบาย
`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)	การประทับเวลาที่อัปเดตล่าสุด

อ็อบเจกต์เนื้อหาอีเมล

ฟิลด์	Type	คำอธิบาย
`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 ไม่ได้ส่งข้อมูลกลับมา) จะรับประกันว่ามีภาษาหนึ่งถูกแสดงเป็น default: หากคุณไม่ได้ส่งคีย์ default มาเอง ระบบจะเลื่อนระดับ en (หรือหากไม่มี, คีย์ภาษาแรกที่พบ) เป็น default โดยเปลี่ยนชื่อ — ภาษาอื่นๆ ที่คุณส่งมาจะยังคงเดิม subject ก็จะได้รับการปฏิบัติเช่นเดียวกัน ซึ่งแตกต่างจาก Clone ที่จะเก็บเฉพาะค่าภาษา default นั้นไว้และทิ้งส่วนที่เหลือไป

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

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

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

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

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

ที่เกี่ยวข้อง

Notify

การอ้างอิงเพย์โหลดอีเมล

การอ้างอิงพอยต์ Customer Journey