ส่ง SMS POST
ใช้ส่ง SMS ไปยังเบอร์ปลายทางหนึ่งเบอร์หรือหลายเบอร์ในคำขอเดียว ระบบรับข้อความเข้าคิวแล้วตอบกลับทันทีพร้อมสถานะของแต่ละเบอร์ ผลการส่งจริงติดตามได้จาก SMS Log Info หรือ Delivery Report
Authorization
ใช้ API Key (การยืนยันตัวตน) ส่งใน header Authorization: Bearer <API_KEY> (API Key ขึ้นต้นด้วย smsk_)
รองรับ header Idempotency-Key (ไม่บังคับ) เพื่อกันการส่งซ้ำเมื่อ retry — ดูหัวข้อ Idempotency
HTTP Request
POST https://public-api.smsup-plus.com/sms/sendContent Type
application/json (รับเฉพาะ JSON)
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
bulkId | string | Optional | รหัสกลุ่มการส่ง ถ้าไม่ส่งมา ระบบสร้าง UUID ให้ |
messages | array of Message | Required | รายการข้อความ อย่างน้อย 1 รายการ |
Message
| Property | Type | Required | Description |
|---|---|---|---|
from | string | Required | ชื่อผู้ส่ง (Sender name) ต้องเป็นชื่อที่ได้รับอนุมัติให้บัญชีแล้ว (ไม่สนตัวพิมพ์เล็ก/ใหญ่) ดูรายชื่อได้จาก Sender List |
destinations | array of Destination | Required | เบอร์ปลายทาง อย่างน้อย 1 รายการ รวมทุก message ในคำขอเดียวได้ไม่เกิน 1,000 เบอร์ |
text | string | Required | ข้อความ ยาวได้ไม่เกิน 1,600 ตัวอักษร (นับหลังตัดช่องว่างหัว-ท้าย) ดู การคิดเครดิต |
notifyUrl | string | Optional | URL ที่ให้ระบบ POST ผลการส่ง (Delivery Report) กลับไป ดู Delivery Report |
notifyContentType | string | Optional | รับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผลต่อการทำงาน |
sendAt | string | Optional | เวลาส่งรูปแบบ RFC3339 เช่น 2026-04-10T09:00:00+07:00 — ดูคำเตือนด้านล่าง |
shorturl | string | Optional | Y = แปลง URL ในข้อความ (http://, https://, ftp://) เป็นลิงก์สั้นอัตโนมัติ ค่าอื่นหรือไม่ส่ง = ไม่แปลง |
shorturlDomain | string | Optional | โดเมนลิงก์สั้น ต้องเป็นโดเมนที่ได้รับอนุญาตให้บัญชี มิฉะนั้นคำขอถูกปฏิเสธ (INVALID_DOMAIN) |
callbackData | string | Optional | ข้อมูลอ้างอิงของคุณ รับค่าไว้ได้ แต่ปัจจุบันยังไม่ถูกส่งกลับใน callback |
Destination
| Property | Type | Required | Description |
|---|---|---|---|
to | string | Required | เบอร์มือถือไทย ระบบตัดอักขระที่ไม่ใช่ตัวเลขออก แล้วแปลง 0 นำหน้าเป็น 66 (หรือเติม 66 ให้เลข 9 หลัก) ผลลัพธ์ต้องเป็นเลข 11 หลักขึ้นต้น 66 เช่น 0812345678, +66 81-234-5678, 66812345678 |
messageId | string | Optional | รหัสอ้างอิงของคุณสำหรับเบอร์นี้ ถ้าไม่ส่ง ระบบสร้าง UUID ให้ |
sendAt ยังไม่ตั้งเวลาส่ง
ปัจจุบันระบบตรวจเฉพาะ รูปแบบ ของ sendAt (ผิดรูปแบบจะได้ 400) แต่ข้อความจะถูก ส่งทันที ไม่รอเวลาที่กำหนด หากต้องการตั้งเวลา ให้เรียก API ตอนถึงเวลาที่ต้องการ
Response Description
| Property | Type | Description |
|---|---|---|
bulkId | string | bulkId ที่ส่งมา หรือ UUID ที่ระบบสร้าง |
details | array | ผลรายเบอร์ เรียงตามลำดับใน request |
details[].messageId | string | messageId ที่ส่งมา หรือ UUID ที่ระบบสร้าง |
details[].mobile | string | เบอร์หลังจัดรูปแบบ (66XXXXXXXXX) — ถ้าเบอร์ไม่ถูกต้องจะเป็นค่าเดิมที่ส่งมา |
details[].to | string | เหมือน mobile |
details[].from | string | ชื่อผู้ส่ง |
details[].credit | string | เครดิตต่อเบอร์ (จำนวน SMS part) ทศนิยม 2 ตำแหน่ง เช่น "1.00" |
details[].shorturl | string | Y หรือ N |
details[].status.code | string | รหัสสถานะ ดูตารางด้านล่าง |
details[].status.name | string | PENDING หรือ REJECTED |
details[].status.description | string | คำอธิบายสถานะ |
สถานะรายเบอร์
code | name | description | ความหมาย |
|---|---|---|---|
101 | PENDING | Pending -Message has been accepted by the system | รับเข้าคิวแล้ว รอส่ง |
402 | REJECTED | Invalid number - phone number formatted incorrectly | เบอร์ไม่ถูกต้อง ไม่ส่ง ไม่คิดเครดิต |
403 | REJECTED | Number is blacklisted | เบอร์อยู่ใน Blacklist ของบัญชี ไม่ส่ง ไม่คิดเครดิต |
SUPPRESSED | REJECTED | Recipient has opted out of non-OTP SMS | ผู้รับขอยกเลิกรับ SMS (ที่ไม่ใช่ OTP) ไม่ส่ง ไม่คิดเครดิต |
NO_CONSENT | REJECTED | No consent from recipient for this account | บัญชีกำหนดให้ต้องมี consent แต่ผู้รับยังไม่ให้ consent ไม่ส่ง ไม่คิดเครดิต |
การคิดเครดิต
- เครดิตต่อเบอร์ = จำนวน SMS part ของ
text(ตัดช่องว่างหัว-ท้าย และตัดที่ 1,600 ตัวอักษร) - ข้อความ มาตรฐาน (มีเฉพาะ
A-Z a-z 0-9ช่องว่าง ขึ้นบรรทัด และสัญลักษณ์\ | ! # $ % & / ( ) * ^ = ? » « @ £ § € { } . - ; ' " < > _ [ ] , +): ≤160 ตัว = 1, ≤306 = 2, มากกว่านั้น = ปัดขึ้น(ความยาว/153) - ข้อความ Unicode (มีภาษาไทยหรืออักขระนอกชุดข้างบน): ≤70 ตัว = 1, ≤134 = 2, มากกว่านั้น = ปัดขึ้น(ความยาว/67)
- เมื่อ
shorturl=Yแต่ละ URL ถูกนับเป็นความยาวของลิงก์สั้น (โดเมนลิงก์สั้นของระบบ + รหัส 9 ตัว) แทนความยาว URL เดิม — เช็กยอดจริงด้วย Preview SMS - บัญชี เติมเงินล่วงหน้า (prepaid): ระบบตรวจยอดคงเหลือก่อนรับคำขอ — ต้องมีอย่างน้อย (เครดิตต่อเบอร์ × จำนวนเบอร์ที่ถูกต้อง) ไม่พอจะได้ 402 และไม่มีข้อความใดถูกส่ง บัญชี รายเดือน (postpaid) ไม่ถูกตรวจยอด
- เครดิตถูกหักจริงเมื่อระบบส่งข้อความออกไปยังผู้ให้บริการเครือข่าย เบอร์ที่ถูกปฏิเสธไม่ถูกหักเครดิต
อักขระที่ทำให้เป็น Unicode
: ~ ` และ tab ไม่อยู่ในชุดอักขระมาตรฐาน ข้อความภาษาอังกฤษที่มี URL (https://...) จึงถูกคิดแบบ Unicode (70 ตัวต่อ part) ใช้ Preview SMS เพื่อเช็กเครดิตก่อนส่ง
Idempotency
ส่ง header Idempotency-Key: <ค่าที่ไม่ซ้ำ> (ตัวอักษร A-Z a-z 0-9 _ - ยาว 1–128 ตัว) เพื่อให้การ retry ปลอดภัย
- คำขอแรกที่สำเร็จ (HTTP 2xx) ถูกเก็บไว้ 24 ชั่วโมง — คำขอซ้ำที่ใช้ key เดิมจะได้ response เดิมกลับไปพร้อม header
Idempotent-Replayed: trueโดยไม่ส่ง SMS และไม่หักเครดิตซ้ำ - ถ้าคำขอแรกยังทำงานอยู่ คำขอซ้ำจะได้ 409
- ถ้าคำขอแรกไม่สำเร็จ (ไม่ใช่ 2xx) key จะถูกปล่อยให้ใช้ซ้ำได้ทันที
- key แยกตามบัญชี และระบบ ไม่เทียบ body — ใช้ key ใหม่ทุกครั้งที่เป็นการส่งใหม่
ตัวอย่าง Request
curl -X POST 'https://public-api.smsup-plus.com/sms/send' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 7d1f6c2e-0b4a-4f1e-9a51-3c2b8e0d9f10' \
-d '{
"messages": [
{
"from": "MyBrand",
"destinations": [
{ "to": "0812345678" },
{ "to": "0898765432", "messageId": "order-1001" },
{ "to": "12345" }
],
"text": "Your order has been shipped",
"notifyUrl": "https://example.com/sms/dr"
}
]
}'const res = await fetch('https://public-api.smsup-plus.com/sms/send', {
method: 'POST',
headers: {
Authorization: 'Bearer <API_KEY>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
messages: [
{
from: 'MyBrand',
destinations: [
{ to: '0812345678' },
{ to: '0898765432', messageId: 'order-1001' },
{ to: '12345' },
],
text: 'Your order has been shipped',
notifyUrl: 'https://example.com/sms/dr',
},
],
}),
})
console.log(await res.json())ตัวอย่าง Response
{
"bulkId": "3b0f5c7e-8d2a-4c61-9e3f-1a2b3c4d5e6f",
"details": [
{
"messageId": "9c8e2f1a-4b7d-4e0a-8f6c-2d1e0b9a8c7d",
"mobile": "66812345678",
"to": "66812345678",
"from": "MyBrand",
"credit": "1.00",
"shorturl": "N",
"status": { "code": "101", "name": "PENDING", "description": "Pending -Message has been accepted by the system" }
},
{
"messageId": "order-1001",
"mobile": "66898765432",
"to": "66898765432",
"from": "MyBrand",
"credit": "1.00",
"shorturl": "N",
"status": { "code": "101", "name": "PENDING", "description": "Pending -Message has been accepted by the system" }
},
{
"messageId": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
"mobile": "12345",
"to": "12345",
"from": "MyBrand",
"credit": "1.00",
"shorturl": "N",
"status": { "code": "402", "name": "REJECTED", "description": "Invalid number - phone number formatted incorrectly" }
}
]
}Error ที่อาจเจอ
ข้อผิดพลาดของ endpoint นี้อยู่ในรูป {"error":{"statusCode","description","message"}} (ยกเว้นข้อผิดพลาดของ Idempotency-Key และ การยืนยันตัวตน) ดูภาพรวมที่ รหัสข้อผิดพลาด
| HTTP | Response | สาเหตุ |
|---|---|---|
| 400 | {"error":{"statusCode":"400","description":"Invalid request body","message":"BAD_REQUEST"}} | body ไม่ใช่ JSON ที่ถูกต้อง หรือไม่มี / มี messages ว่าง |
| 400 | {"error":{"statusCode":"400","description":"Destinations not found","message":"BAD_REQUEST"}} | message ไม่มี destinations หรือมีรายการที่ to ว่าง |
| 400 | {"error":{"statusCode":"400","description":"Text not found","message":"BAD_REQUEST"}} | text ว่าง |
| 400 | {"error":{"statusCode":"400","description":"sender not found","message":"BAD_REQUEST"}} | from ว่าง |
| 400 | {"error":{"statusCode":"400","description":"sendAt must be in RFC3339 format (e.g. 2026-04-10T09:00:00+07:00)","message":"BAD_REQUEST"}} | sendAt ผิดรูปแบบ |
| 400 | {"error":{"statusCode":"400","description":"Text too long: 1650 characters (max 1600)","message":"BAD_REQUEST"}} | ข้อความยาวเกิน 1,600 ตัวอักษร |
| 400 | {"error":{"statusCode":"400","description":"Too many destinations: 1200 (max 1000 per request)","message":"BAD_REQUEST"}} | เบอร์รวมทั้งคำขอเกิน 1,000 |
| 400 | {"error":"invalid Idempotency-Key"} | Idempotency-Key มีอักขระไม่อนุญาตหรือยาวเกิน 128 |
| 402 | {"error":{"statusCode":"402","description":"insufficient credit: required 3.00, available 1.00","message":"INSUFFICIENT_CREDIT"}} | บัญชี prepaid มีเครดิตไม่พอ |
| 403 | {"error":{"statusCode":"403","description":"account is inactive","message":"ACCOUNT_INACTIVE"}} | บัญชีถูกปิดใช้งาน |
| 403 | {"error":{"statusCode":"403","description":"account is on credit hold","message":"ACCOUNT_HELD"}} | บัญชีถูกระงับเครดิต |
| 403 | {"error":{"statusCode":"403","description":"API sending is not enabled for this account","message":"SERVICE_NOT_ALLOWED"}} | บัญชียังไม่เปิดสิทธิ์ส่ง SMS ผ่าน API |
| 403 | {"error":{"statusCode":"101","description":"sender 'MyBrand' not authorized for this account","message":"INVALID_SENDER"}} | ชื่อผู้ส่งยังไม่ได้รับอนุมัติให้บัญชี |
| 403 | {"error":{"statusCode":"102","description":"shorten URL domain 'go.example.com' not authorized for this account","message":"INVALID_DOMAIN"}} | shorturlDomain ไม่ได้รับอนุญาต |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | คำขอที่ใช้ key เดียวกันยังทำงานอยู่ |
| 429 | {"error":{"statusCode":"429","description":"rate limit exceeded: max 50 requests per second per account","message":"TOO_MANY_REQUESTS"}} | เรียกถี่เกินกำหนด (ต่อ IP / บัญชี / API Key) — รอตาม header Retry-After |
| 500 | {"error":{"statusCode":"500","description":"Failed to enqueue SMS for delivery","message":"QUEUE_PUBLISH_FAILED"}} | ระบบรับข้อความเข้าคิวไม่สำเร็จ ไม่มีข้อความถูกส่ง — retry ได้ (แนะนำใช้ Idempotency-Key) |
| 500 | {"error":{"statusCode":"500","description":"Failed to validate send request","message":"INTERNAL_ERROR"}} | ระบบตรวจสอบคำขอไม่สำเร็จชั่วคราว |
ตรวจลำดับ
ระบบตรวจตามลำดับ: รูปแบบ body → ความยาว/จำนวนเบอร์ → สถานะบัญชี → สิทธิ์ส่ง API → ชื่อผู้ส่ง → เครดิต → โดเมนลิงก์สั้น ถ้าข้อใดไม่ผ่าน จะไม่มีเบอร์ใดถูกส่ง
