Email API

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

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

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

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

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

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

ชื่อ	ประเภท	จำเป็น	คำอธิบาย
send_date	`string`	ใช่	กำหนดเวลาที่จะส่งอีเมล รูปแบบ: `YYYY-MM-DD HH:mm` หรือ `"now"`
preset	`string`	ใช่	Email preset code คัดลอกจากแถบ 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`	ไม่	Campaign code เพื่อเชื่อมโยงอีเมลกับแคมเปญที่เฉพาะเจาะจง
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`	ไม่	ตัวยึดตำแหน่งสำหรับเนื้อหาแบบไดนามิกแทนค่า Tag ของอุปกรณ์
conditions	`array`	ไม่	เงื่อนไขการแบ่งกลุ่มโดยใช้ Tag ตัวอย่าง: `[["Country", "EQ", "BR"]]`
from	`object`	ไม่	ระบุชื่อผู้ส่งและอีเมลที่กำหนดเอง โดยจะแทนที่ค่าเริ่มต้นในคุณสมบัติของแอปพลิเคชัน
reply-to	`object`	ไม่	ระบุอีเมลตอบกลับที่กำหนดเอง โดยจะแทนที่ค่าเริ่มต้นในคุณสมบัติของแอปพลิเคชัน
bcc	`array`	ไม่	BCC (Blind Carbon Copy): อาร์เรย์ของที่อยู่อีเมลที่จะได้รับสำเนาของอีเมลโดยที่ผู้รับคนอื่นไม่เห็น
email_type	`string`	ไม่	ระบุประเภทของอีเมล: `"marketing"` หรือ `"transactional"` หากไม่ระบุ ผู้ใช้ที่มี `PW_ControlGroup: true` จะไม่ได้รับข้อความ
email_category	`string`	จำเป็นเมื่อ `email_type` เป็น `"marketing"`	ระบุชื่อหมวดหมู่หนึ่งที่กำหนดค่าไว้ใน ศูนย์การตั้งค่าการสมัครรับข้อมูล (เช่น Newsletter, Promotional, Product Updates)
transactionId	`string`	ไม่	ตัวระบุข้อความที่ไม่ซ้ำกันเพื่อป้องกันการส่งซ้ำในกรณีที่เกิดปัญหาเครือข่าย จัดเก็บไว้ที่ฝั่ง Pushwoosh เป็นเวลา 5 นาที
capping_days	`integer`	ไม่	จำนวนวัน (สูงสุด 30) ที่จะใช้ frequency capping ต่ออุปกรณ์ หมายเหตุ: ตรวจสอบให้แน่ใจว่าได้กำหนดค่า Global frequency capping ใน Control Panel แล้ว
capping_count	`integer`	ไม่	จำนวนอีเมลสูงสุดที่สามารถส่งจากแอปที่เฉพาะเจาะจงไปยังอุปกรณ์หนึ่งๆ ภายในระยะเวลา `capping_days` ในกรณีที่ข้อความที่สร้างขึ้นเกินขีดจำกัด `capping_count` สำหรับอุปกรณ์ ข้อความนั้นจะไม่ถูกส่งไปยังอุปกรณ์นั้น
capping_exclude	`boolean`	ไม่	หากตั้งค่าเป็น `true` อีเมลนี้จะไม่ถูกนับรวมใน capping สำหรับอีเมลในอนาคต
capping_avoid	`boolean`	ไม่	หากตั้งค่าเป็น `true` capping จะไม่ถูกนำไปใช้กับอีเมลนี้โดยเฉพาะ
send_rate	`integer`	ไม่	จำกัดจำนวนข้อความที่สามารถส่งได้ต่อวินาทีสำหรับผู้ใช้ทั้งหมด ช่วยป้องกันการโอเวอร์โหลดของ backend ในระหว่างการส่งจำนวนมาก
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, users with PW_ControlGroup: true will not receive the message.
      "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

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

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

คำอธิบาย Operand

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

Tag ประเภท String

โอเปอเรเตอร์ที่ใช้ได้: EQ, IN, NOTEQ, NOTIN
Operand ที่ใช้ได้:

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

Tag ประเภท Integer

โอเปอเรเตอร์ที่ใช้ได้: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Operand ที่ใช้ได้:

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
Operand ที่ใช้ได้:

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

Tag ประเภท Boolean

โอเปอเรเตอร์ที่ใช้ได้: EQ
Operand ที่ใช้ได้: 0, 1, true, false

Tag ประเภท List

โอเปอเรเตอร์ที่ใช้ได้: IN
Operand ที่ใช้ได้: operand ต้องเป็นอาร์เรย์ของสตริงเช่น ["value 1", "value 2", "value N"]

registerEmail

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

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

ส่วนหัวของ Request

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

ส่วนเนื้อหาของ Request

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

{
  "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
    }
  }
}

โค้ดการตอบกลับ

Public 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 bounce) และจะไม่ถูกลงทะเบียนใหม่
`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

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

ส่วนเนื้อหาของ Request

ชื่อ	ประเภท	คำอธิบาย
application	string	Pushwoosh application code
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

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

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

ส่วนหัวของ Request

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

ส่วนเนื้อหาของ Request

ชื่อ	ประเภท	คำอธิบาย
application	string	Pushwoosh application code
email	string	ที่อยู่อีเมล
tags	object	อ็อบเจกต์ JSON ของ Tag ที่จะตั้งค่า ส่ง ‘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

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

ส่วนเนื้อหาของ Request

ชื่อ	ประเภท	คำอธิบาย
application*	string	Pushwoosh application code
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.
  }
}