Email API

createEmailMessage เลิกใช้งานแล้ว

สร้างข้อความอีเมล

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

พารามิเตอร์ของ Request body

ชื่อ	ประเภท	จำเป็น	คำอธิบาย
auth	`string`	ใช่	โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
application	`string`	ใช่	รหัสแอปพลิเคชัน Pushwoosh
notifications	`array`	ใช่	อาร์เรย์ JSON ที่มีรายละเอียดข้อความอีเมล ดูตาราง พารามิเตอร์ของ Notifications ด้านล่าง

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

ชื่อ	ประเภท	จำเป็น	คำอธิบาย
send_date	`string`	ใช่	กำหนดเวลาที่จะส่งอีเมล รูปแบบ: `YYYY-MM-DD HH:mm` หรือ `"now"`
preset	`string`	ใช่	รหัสพรีเซ็ตอีเมล คัดลอกจากแถบ URL ของ Email Content Editor ใน Pushwoosh Control Panel
subject	`string` หรือ `object`	ไม่	หัวเรื่องของอีเมล อีเมลจะอยู่ในภาษาของเนื้อหาเสมอ หาก `subject` ไม่มีภาษาที่ตรงกับ `content` หัวเรื่องจะว่างเปล่า
content	`string` หรือ `object`	ไม่	เนื้อหาของอีเมล สามารถเป็นสตริงสำหรับเนื้อหา HTML ธรรมดาหรืออ็อบเจกต์สำหรับเวอร์ชันที่แปลเป็นภาษาท้องถิ่น
attachments	`array`	ไม่	ไฟล์แนบของอีเมล สามารถแนบไฟล์ได้เพียงสองไฟล์เท่านั้น แต่ละไฟล์ต้องมีขนาดไม่เกิน 1MB (เข้ารหัสแบบ base64)
list_unsubscribe	`string`	ไม่	อนุญาตให้ตั้งค่า URL ที่กำหนดเองสำหรับเฮดเดอร์ “Link-Unsubscribe”
campaign	`string`	ไม่	รหัสแคมเปญ เพื่อเชื่อมโยงอีเมลกับแคมเปญที่เฉพาะเจาะจง
ignore_user_timezone	`boolean`	ไม่	หากเป็น `true` จะส่งอีเมลทันทีโดยไม่สนใจเขตเวลาของผู้ใช้
timezone	`string`	ไม่	ส่งอีเมลตามเขตเวลาของผู้ใช้ ตัวอย่าง: `"America/New_York"`
filter	`string`	ไม่	ส่งอีเมลไปยังผู้ใช้ที่ตรงกับ เงื่อนไขตัวกรองที่ระบุ
devices	`array`	ไม่	รายการที่อยู่อีเมล (สูงสุด 1000) เพื่อส่งอีเมลเป้าหมาย หากใช้ พารามิเตอร์นี้ ข้อความจะถูกส่งไปยังที่อยู่เหล่านี้เท่านั้น จะถูกละเว้นหากใช้ Application Group
use_auto_registration	`boolean`	ไม่	หากเป็น `true` จะลงทะเบียนอีเมลจากพารามิเตอร์ `devices` โดยอัตโนมัติ
users	`array`	ไม่	หากตั้งค่าไว้ ข้อความอีเมลจะถูกส่งไปยัง User ID ที่ระบุเท่านั้น (ลงทะเบียนผ่านการเรียก /registerEmail) ไม่เกิน 1000 User ID ในอาร์เรย์ หากระบุพารามิเตอร์ “devices” พารามิเตอร์ “users” จะถูกละเว้น
dynamic_content_placeholders	`object`	ไม่	ตัวยึดตำแหน่งสำหรับเนื้อหาแบบไดนามิกแทนค่าแท็กของอุปกรณ์
conditions	`array`	ไม่	เงื่อนไขการแบ่งกลุ่มโดยใช้แท็ก ตัวอย่าง: `[["Country", "EQ", "BR"]]`
from	`object`	ไม่	ระบุชื่อผู้ส่งและอีเมลที่กำหนดเอง เพื่อแทนที่ค่าเริ่มต้นในคุณสมบัติของแอปพลิเคชัน
reply-to	`object`	ไม่	ระบุอีเมลตอบกลับที่กำหนดเอง เพื่อแทนที่ค่าเริ่มต้นในคุณสมบัติของแอปพลิเคชัน
bcc	`array`	ไม่	BCC (Blind Carbon Copy): อาร์เรย์ของที่อยู่อีเมลที่ได้รับสำเนาของอีเมลโดยที่ผู้รับคนอื่นไม่เห็น
email_type	`string`	ไม่	ระบุประเภทของอีเมล: `"marketing"` หรือ `"transactional"` หากไม่ระบุ ข้อความจะถือว่าเป็นแบบ transactional และจะถูกส่งไปยังทุกคน รวมถึงกลุ่มควบคุมด้วย ข้อความการตลาดจะไม่ถูกส่งไปยังสมาชิก กลุ่มควบคุม
email_category	`string`	จำเป็นเมื่อ `email_type` เป็น `"marketing"`	ระบุชื่อหมวดหมู่หนึ่งที่กำหนดค่าไว้ใน ศูนย์การตั้งค่าการสมัครรับข้อมูล (เช่น Newsletter, Promotional, Product Updates)
transactionId	`string`	ไม่	ตัวระบุข้อความที่ไม่ซ้ำกันเพื่อป้องกันการส่งซ้ำในกรณีที่เกิดปัญหาเครือข่าย จัดเก็บไว้ที่ฝั่ง Pushwoosh เป็นเวลา 5 นาที
capping_days	`integer`	ไม่	จำนวนวัน (สูงสุด 30) ที่จะใช้การจำกัดความถี่ต่ออุปกรณ์ หมายเหตุ: ตรวจสอบให้แน่ใจว่าได้กำหนดค่า Global frequency capping ใน Control Panel แล้ว
capping_count	`integer`	ไม่	จำนวนอีเมลสูงสุดที่สามารถส่งจากแอปที่ระบุไปยังอุปกรณ์หนึ่งๆ ภายในระยะเวลา `capping_days` ในกรณีที่ข้อความที่สร้างขึ้นเกินขีดจำกัด `capping_count` สำหรับอุปกรณ์ ข้อความนั้นจะไม่ถูกส่งไปยังอุปกรณ์นั้น
capping_exclude	`boolean`	ไม่	หากตั้งค่าเป็น `true` อีเมลนี้จะไม่ถูกนับรวมในการจำกัดความถี่สำหรับอีเมลในอนาคต
capping_avoid	`boolean`	ไม่	หากตั้งค่าเป็น `true` การจำกัดความถี่จะไม่ถูกนำไปใช้กับอีเมลนี้โดยเฉพาะ
send_rate	`integer`	ไม่	จำกัดจำนวนข้อความที่สามารถส่งได้ต่อวินาทีสำหรับผู้ใช้ทั้งหมด ช่วยป้องกันการโอเวอร์โหลดของแบ็กเอนด์ระหว่างการส่งจำนวนมาก
send_rate_avoid	`boolean`	ไม่	หากตั้งค่าเป็น `true` ขีดจำกัดการควบคุมปริมาณจะไม่ถูกนำไปใช้กับอีเมลนี้โดยเฉพาะ

ตัวอย่าง Request

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

ตัวอย่าง Response

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

เงื่อนไขของ Tag

เงื่อนไขของแท็กแต่ละรายการเป็นอาร์เรย์เช่น [tagName, operator, operand] โดยที่

tagName: ชื่อของแท็ก
operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
operand: string | integer | array | date

คำอธิบาย Operand

EQ: ค่าแท็กเท่ากับ operand;
IN: ค่าแท็กตัดกับ operand (operand ต้องเป็นอาร์เรย์เสมอ);
NOTEQ: ค่าแท็กไม่เท่ากับ operand;
NOTIN: ค่าแท็กไม่ตัดกับ operand (operand ต้องเป็นอาร์เรย์เสมอ);
GTE: ค่าแท็กมากกว่าหรือเท่ากับ operand;
LTE: ค่าแท็กน้อยกว่าหรือเท่ากับ operand;
BETWEEN: ค่าแท็กมากกว่าหรือเท่ากับค่า operand ต่ำสุด แต่น้อยกว่าหรือเท่ากับค่า operand สูงสุด (operand ต้องเป็นอาร์เรย์เสมอ)

Tag ประเภท String

ตัวดำเนินการที่ถูกต้อง: EQ, IN, NOTEQ, NOTIN
Operands ที่ถูกต้อง:

EQ, NOTEQ: operand ต้องเป็นสตริง;
IN, NOTIN: operand ต้องเป็นอาร์เรย์ของสตริงเช่น ["value 1", "value 2", "value N"];

Tag ประเภท Integer

ตัวดำเนินการที่ถูกต้อง: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Operands ที่ถูกต้อง:

EQ, NOTEQ, GTE, LTE: operand ต้องเป็นจำนวนเต็ม;
IN, NOTIN: operand ต้องเป็นอาร์เรย์ของจำนวนเต็มเช่น [value 1, value 2, value N];
BETWEEN: operand ต้องเป็นอาร์เรย์ของจำนวนเต็มเช่น [min_value, max_value]

Tag ประเภท Date

ตัวดำเนินการที่ถูกต้อง: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Operands ที่ถูกต้อง:

"YYYY-MM-DD 00:00" (สตริง)
unix timestamp 1234567890 (จำนวนเต็ม)
"N days ago" (สตริง) สำหรับตัวดำเนินการ EQ, BETWEEN, GTE, LTE

Tag ประเภท Boolean

ตัวดำเนินการที่ถูกต้อง: EQ
Operands ที่ถูกต้อง: 0, 1, true, false

Tag ประเภท List

ตัวดำเนินการที่ถูกต้อง: IN
Operands ที่ถูกต้อง: operand ต้องเป็นอาร์เรย์ของสตริงเช่น ["value 1", "value 2", "value N"]

registerEmail

ลงทะเบียนที่อยู่อีเมลสำหรับแอป

POST https://api.pushwoosh.com/json/1.3/registerEmail

Request headers

ชื่อ	จำเป็น	ค่า	คำอธิบาย
Authorization	ใช่	Token `XXXX`	API Device Token เพื่อเข้าถึง Device API แทนที่ `XXXX` ด้วย Device API token ของคุณ

Request body

ชื่อ	ประเภท	คำอธิบาย
application*	string	รหัสแอปพลิเคชัน Pushwoosh
email*	string	ที่อยู่อีเมล
language	string	ภาษาท้องถิ่นของอุปกรณ์ ต้องเป็นรหัสสองตัวอักษรพิมพ์เล็กตามมาตรฐาน ISO-639-1
userId	string	User ID ที่จะเชื่อมโยงกับที่อยู่อีเมล
tz_offset	integer	ออฟเซ็ตเขตเวลาเป็นวินาที
tags	object	ค่าแท็กที่จะกำหนดให้กับอุปกรณ์ที่ลงทะเบียน

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

รหัส Response

API สาธารณะจะส่งคืนผลลัพธ์ใน status_code ใช้ตารางด้านล่างเพื่อตัดสินใจว่าควรลองเรียกซ้ำเมื่อล้มเหลวหรือไม่

`status_code`	ความหมาย	ลองใหม่?
`200`	สำเร็จ — ที่อยู่อีเมลถูกลงทะเบียนแล้ว	ไม่ — เสร็จแล้ว
`210`	ข้อผิดพลาดของอาร์กิวเมนต์/การตรวจสอบความถูกต้อง — คำขอถูกเข้าใจแต่ถูกปฏิเสธ (ที่อยู่ในบัญชีดำ, อีเมลที่ไม่ถูกต้องหรือใช้แล้วทิ้ง, แพลตฟอร์มที่ไม่ถูกต้องสำหรับแผนของบัญชี) ดู ข้อความแสดงข้อผิดพลาด 210 ด้านล่าง	ไม่ — คำขอเดียวกันจะคืนค่า `210` เดิม ให้บันทึกที่อยู่และข้ามไป
`400`	คำขอมีรูปแบบไม่ถูกต้อง — JSON ไม่ถูกต้องหรือฟิลด์ที่จำเป็นหายไป	ไม่ — แก้ไขคำขอ อย่าทำซ้ำ
`403`	ถูกห้าม — Device API token ไม่ถูกต้องหรือถูกจำกัด	ไม่ — แก้ไขการให้สิทธิ์
`500`	ข้อผิดพลาดภายในเซิร์ฟเวอร์ — ปัญหาโครงสร้างพื้นฐานชั่วคราวหรือหมดเวลา	ใช่, ด้วย exponential backoff — เป็นกรณีชั่วคราวเพียงกรณีเดียว

ข้อความแสดงข้อผิดพลาด 210

การตอบกลับ 210 จะมีเหตุผลเฉพาะใน status_message

`status_message`	ความหมาย
`this hwid (email) is blacklisted`	ที่อยู่อยู่ในรายการระงับหลังจากการตีกลับแบบถาวร (hard) และจะไม่ถูกลงทะเบียนใหม่
`hwid (email) is invalid` / `has invalid semantic`	ที่อยู่ไม่ผ่านการตรวจสอบความถูกต้อง
`hwid (email) is empty`	ไม่ได้ระบุที่อยู่
`hwid (email) has invalid count of parts`	มี `@` ขาดหรือเกิน
`hwid (email) has invalid local part`	ส่วนก่อน `@` ไม่ถูกต้อง
`hwid (email) has invalid domain part`	ส่วนโดเมนไม่ถูกต้อง
`hwid (email) has disposable domain`	ที่อยู่ใช้อีเมลโดเมนแบบใช้แล้วทิ้ง/ชั่วคราว (เช่น 10minutemail)
`hwid is not valid`	`hwid` เองมีรูปแบบไม่ถูกต้อง
`only email platform allowed for Email Only subscription`	บัญชีอยู่ในแผน Email Only และไม่สามารถลงทะเบียนอุปกรณ์ที่ไม่ใช่อีเมลได้

deleteEmail

ลบที่อยู่อีเมลออกจากฐานผู้ใช้ของคุณ

POST https://api.pushwoosh.com/json/1.3/deleteEmail

Request headers

ชื่อ	จำเป็น	ค่า	คำอธิบาย
Authorization	ใช่	Token `XXXX`	API Device Token เพื่อเข้าถึง Device API แทนที่ `XXXX` ด้วย Device API token ของคุณ

Request body

ชื่อ	ประเภท	คำอธิบาย
application	string	รหัสแอปพลิเคชัน Pushwoosh
email	string	ที่อยู่อีเมลที่ใช้ในคำขอ `/registerEmail`

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

setEmailTags

ตั้งค่าแท็กสำหรับที่อยู่อีเมล

POST https://api.pushwoosh.com/json/1.3/setEmailTags

Request headers

ชื่อ	จำเป็น	ค่า	คำอธิบาย
Authorization	ใช่	Token `XXXX`	API Device Token เพื่อเข้าถึง Device API แทนที่ `XXXX` ด้วย Device API token ของคุณ

Request body

ชื่อ	ประเภท	คำอธิบาย
application	string	รหัสแอปพลิเคชัน Pushwoosh
email	string	ที่อยู่อีเมล
tags	object	อ็อบเจกต์ JSON ของแท็กที่จะตั้งค่า ส่ง ‘null’ เพื่อลบค่า
userId	string	User ID ที่เชื่อมโยงกับที่อยู่อีเมล

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

{
  "request": {
    "email": "email@domain.com",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

registerEmailUser

เชื่อมโยง User ID ภายนอกกับที่อยู่อีเมลที่ระบุ

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

สามารถใช้ในการเรียก API /createEmailMessage (พารามิเตอร์ ‘users’)

Request headers

ชื่อ	จำเป็น	ค่า	คำอธิบาย
Authorization	ใช่	Token `XXXX`	API Device Token เพื่อเข้าถึง Device API แทนที่ `XXXX` ด้วย Device API token ของคุณ

Request body

ชื่อ	ประเภท	คำอธิบาย
application*	string	รหัสแอปพลิเคชัน Pushwoosh
email*	string	ที่อยู่อีเมล
userId*	string	User ID ที่จะเชื่อมโยงกับที่อยู่อีเมล
tz_offset	integer	ออฟเซ็ตเขตเวลาเป็นวินาที

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

{
  "status_code": 403,
  "status_message": "Forbidden."
}

{
  "request": {
    "application": "APPLICATION_CODE", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}