Skip to content

ส่ง 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 ​

http
POST https://public-api.smsup-plus.com/sms/send

Content Type ​

application/json (รับเฉพาะ JSON)

Parameter Description ​

PropertyTypeRequiredDescription
bulkIdstringOptionalรหัสกลุ่มการส่ง ถ้าไม่ส่งมา ระบบสร้าง UUID ให้
messagesarray of MessageRequiredรายการข้อความ อย่างน้อย 1 รายการ

Message ​

PropertyTypeRequiredDescription
fromstringRequiredชื่อผู้ส่ง (Sender name) ต้องเป็นชื่อที่ได้รับอนุมัติให้บัญชีแล้ว (ไม่สนตัวพิมพ์เล็ก/ใหญ่) ดูรายชื่อได้จาก Sender List
destinationsarray of DestinationRequiredเบอร์ปลายทาง อย่างน้อย 1 รายการ รวมทุก message ในคำขอเดียวได้ไม่เกิน 1,000 เบอร์
textstringRequiredข้อความ ยาวได้ไม่เกิน 1,600 ตัวอักษร (นับหลังตัดช่องว่างหัว-ท้าย) ดู การคิดเครดิต
notifyUrlstringOptionalURL ที่ให้ระบบ POST ผลการส่ง (Delivery Report) กลับไป ดู Delivery Report
notifyContentTypestringOptionalรับค่าไว้เพื่อความเข้ากันได้กับระบบเดิม ปัจจุบันไม่มีผลต่อการทำงาน
sendAtstringOptionalเวลาส่งรูปแบบ RFC3339 เช่น 2026-04-10T09:00:00+07:00 — ดูคำเตือนด้านล่าง
shorturlstringOptionalY = แปลง URL ในข้อความ (http://, https://, ftp://) เป็นลิงก์สั้นอัตโนมัติ ค่าอื่นหรือไม่ส่ง = ไม่แปลง
shorturlDomainstringOptionalโดเมนลิงก์สั้น ต้องเป็นโดเมนที่ได้รับอนุญาตให้บัญชี มิฉะนั้นคำขอถูกปฏิเสธ (INVALID_DOMAIN)
callbackDatastringOptionalข้อมูลอ้างอิงของคุณ รับค่าไว้ได้ แต่ปัจจุบันยังไม่ถูกส่งกลับใน callback

Destination ​

PropertyTypeRequiredDescription
tostringRequiredเบอร์มือถือไทย ระบบตัดอักขระที่ไม่ใช่ตัวเลขออก แล้วแปลง 0 นำหน้าเป็น 66 (หรือเติม 66 ให้เลข 9 หลัก) ผลลัพธ์ต้องเป็นเลข 11 หลักขึ้นต้น 66 เช่น 0812345678, +66 81-234-5678, 66812345678
messageIdstringOptionalรหัสอ้างอิงของคุณสำหรับเบอร์นี้ ถ้าไม่ส่ง ระบบสร้าง UUID ให้

sendAt ยังไม่ตั้งเวลาส่ง

ปัจจุบันระบบตรวจเฉพาะ รูปแบบ ของ sendAt (ผิดรูปแบบจะได้ 400) แต่ข้อความจะถูก ส่งทันที ไม่รอเวลาที่กำหนด หากต้องการตั้งเวลา ให้เรียก API ตอนถึงเวลาที่ต้องการ

Response Description ​

PropertyTypeDescription
bulkIdstringbulkId ที่ส่งมา หรือ UUID ที่ระบบสร้าง
detailsarrayผลรายเบอร์ เรียงตามลำดับใน request
details[].messageIdstringmessageId ที่ส่งมา หรือ UUID ที่ระบบสร้าง
details[].mobilestringเบอร์หลังจัดรูปแบบ (66XXXXXXXXX) — ถ้าเบอร์ไม่ถูกต้องจะเป็นค่าเดิมที่ส่งมา
details[].tostringเหมือน mobile
details[].fromstringชื่อผู้ส่ง
details[].creditstringเครดิตต่อเบอร์ (จำนวน SMS part) ทศนิยม 2 ตำแหน่ง เช่น "1.00"
details[].shorturlstringY หรือ N
details[].status.codestringรหัสสถานะ ดูตารางด้านล่าง
details[].status.namestringPENDING หรือ REJECTED
details[].status.descriptionstringคำอธิบายสถานะ

สถานะรายเบอร์ ​

codenamedescriptionความหมาย
101PENDINGPending -Message has been accepted by the systemรับเข้าคิวแล้ว รอส่ง
402REJECTEDInvalid number - phone number formatted incorrectlyเบอร์ไม่ถูกต้อง ไม่ส่ง ไม่คิดเครดิต
403REJECTEDNumber is blacklistedเบอร์อยู่ใน Blacklist ของบัญชี ไม่ส่ง ไม่คิดเครดิต
SUPPRESSEDREJECTEDRecipient has opted out of non-OTP SMSผู้รับขอยกเลิกรับ SMS (ที่ไม่ใช่ OTP) ไม่ส่ง ไม่คิดเครดิต
NO_CONSENTREJECTEDNo 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 ​

bash
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"
      }
    ]
  }'
js
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 ​

json
{
  "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 และ การยืนยันตัวตน) ดูภาพรวมที่ รหัสข้อผิดพลาด

HTTPResponseสาเหตุ
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 → ชื่อผู้ส่ง → เครดิต → โดเมนลิงก์สั้น ถ้าข้อใดไม่ผ่าน จะไม่มีเบอร์ใดถูกส่ง