Send SMS POST
Sends an SMS to one or many recipients in a single request. The system queues the messages and replies immediately with a per-recipient status. Track the actual delivery result with SMS Log Info or a Delivery Report.
Authorization
API Key (Authentication) in the header Authorization: Bearer <API_KEY> (API keys start with smsk_).
Supports an optional Idempotency-Key header to make retries safe — see Idempotency.
HTTP Request
POST https://public-api.smsup-plus.com/sms/sendContent Type
application/json (JSON only)
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
bulkId | string | Optional | Batch ID. A UUID is generated when omitted |
messages | array of Message | Required | Messages to send, at least 1 |
Message
| Property | Type | Required | Description |
|---|---|---|---|
from | string | Required | Sender name. Must be approved for your account (case-insensitive). See Sender List |
destinations | array of Destination | Required | Recipients, at least 1. At most 1,000 recipients in total across all messages of one request |
text | string | Required | Message text, at most 1,600 characters (counted after trimming leading/trailing whitespace). See Credit calculation |
notifyUrl | string | Optional | URL the system POSTs the delivery result (Delivery Report) to. See Delivery Report |
notifyContentType | string | Optional | Accepted for backward compatibility; currently has no effect |
sendAt | string | Optional | Send time in RFC3339, e.g. 2026-04-10T09:00:00+07:00 — see the warning below |
shorturl | string | Optional | Y = replace URLs in the text (http://, https://, ftp://) with short links. Any other value or omitted = no shortening |
shorturlDomain | string | Optional | Short-link domain. Must be a domain authorized for your account, otherwise the request is rejected (INVALID_DOMAIN) |
callbackData | string | Optional | Your own reference data. Accepted, but currently not returned in the callback |
Destination
| Property | Type | Required | Description |
|---|---|---|---|
to | string | Required | Thai mobile number. Non-digits are stripped, a leading 0 becomes 66 (a 9-digit number gets 66 prepended). The result must be 11 digits starting with 66, e.g. 0812345678, +66 81-234-5678, 66812345678 |
messageId | string | Optional | Your reference for this recipient. A UUID is generated when omitted |
sendAt does not schedule yet
The system currently validates only the format of sendAt (a bad format returns 400), but the message is sent immediately, not at the given time. To schedule, call the API at the time you want the message sent.
Response Description
| Property | Type | Description |
|---|---|---|
bulkId | string | The bulkId you sent, or the generated UUID |
details | array | Per-recipient results, in request order |
details[].messageId | string | The messageId you sent, or the generated UUID |
details[].mobile | string | Normalized number (66XXXXXXXXX) — for an invalid number, the original value |
details[].to | string | Same as mobile |
details[].from | string | Sender name |
details[].credit | string | Credit per recipient (SMS parts) with 2 decimals, e.g. "1.00" |
details[].shorturl | string | Y or N |
details[].status.code | string | Status code, see below |
details[].status.name | string | PENDING or REJECTED |
details[].status.description | string | Status description |
Per-recipient status
code | name | description | Meaning |
|---|---|---|---|
101 | PENDING | Pending -Message has been accepted by the system | Queued for sending |
402 | REJECTED | Invalid number - phone number formatted incorrectly | Invalid number; not sent, not charged |
403 | REJECTED | Number is blacklisted | Number is on your account blacklist; not sent, not charged |
SUPPRESSED | REJECTED | Recipient has opted out of non-OTP SMS | Recipient opted out of non-OTP SMS; not sent, not charged |
NO_CONSENT | REJECTED | No consent from recipient for this account | Your account requires consent and the recipient has not given it; not sent, not charged |
Credit calculation
- Credit per recipient = number of SMS parts of
text(trimmed, cut at 1,600 characters) - Standard text (only
A-Z a-z 0-9, space, line breaks and the symbols\ | ! # $ % & / ( ) * ^ = ? » « @ £ § € { } . - ; ' " < > _ [ ] , +): ≤160 chars = 1, ≤306 = 2, otherwise ceil(length/153) - Unicode text (Thai or any character outside the set above): ≤70 chars = 1, ≤134 = 2, otherwise ceil(length/67)
- With
shorturl=Y, each URL is counted as the length of a short link (the system short-link domain + a 9-character code) instead of the original URL — check the real cost with Preview SMS - Prepaid accounts: the balance is checked before the request is accepted — it must cover (credit per recipient × number of valid recipients), otherwise you get 402 and nothing is sent. Postpaid accounts are not balance-checked
- Credit is deducted when the message is actually submitted to the mobile operator. Rejected recipients are not charged
Characters that force Unicode
: ~ ` and tab are not in the standard set, so English text containing a URL (https://...) is counted as Unicode (70 characters per part). Use Preview SMS to check the cost before sending.
Idempotency
Send Idempotency-Key: <unique value> (characters A-Z a-z 0-9 _ -, 1–128 long) to make retries safe.
- The first successful (HTTP 2xx) response is stored for 24 hours — a repeat request with the same key gets that response back with the header
Idempotent-Replayed: true, without sending SMS or deducting credit again - While the first request is still running, a repeat gets 409
- If the first request fails (non-2xx), the key is released and can be reused immediately
- Keys are scoped to your account and the body is not compared — use a new key for every new send
Request Example
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 Example
{
"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" }
}
]
}Possible Errors
Errors of this endpoint use the shape {"error":{"statusCode","description","message"}} (except Idempotency-Key and authentication errors). See Error Codes for the overview.
| HTTP | Response | Cause |
|---|---|---|
| 400 | {"error":{"statusCode":"400","description":"Invalid request body","message":"BAD_REQUEST"}} | Body is not valid JSON, or messages is missing/empty |
| 400 | {"error":{"statusCode":"400","description":"Destinations not found","message":"BAD_REQUEST"}} | A message has no destinations, or a destination has an empty to |
| 400 | {"error":{"statusCode":"400","description":"Text not found","message":"BAD_REQUEST"}} | text is empty |
| 400 | {"error":{"statusCode":"400","description":"sender not found","message":"BAD_REQUEST"}} | from is empty |
| 400 | {"error":{"statusCode":"400","description":"sendAt must be in RFC3339 format (e.g. 2026-04-10T09:00:00+07:00)","message":"BAD_REQUEST"}} | sendAt has a bad format |
| 400 | {"error":{"statusCode":"400","description":"Text too long: 1650 characters (max 1600)","message":"BAD_REQUEST"}} | Text longer than 1,600 characters |
| 400 | {"error":{"statusCode":"400","description":"Too many destinations: 1200 (max 1000 per request)","message":"BAD_REQUEST"}} | More than 1,000 recipients in one request |
| 400 | {"error":"invalid Idempotency-Key"} | Idempotency-Key has invalid characters or is longer than 128 |
| 402 | {"error":{"statusCode":"402","description":"insufficient credit: required 3.00, available 1.00","message":"INSUFFICIENT_CREDIT"}} | Prepaid account has insufficient credit |
| 403 | {"error":{"statusCode":"403","description":"account is inactive","message":"ACCOUNT_INACTIVE"}} | Account is inactive |
| 403 | {"error":{"statusCode":"403","description":"account is on credit hold","message":"ACCOUNT_HELD"}} | Account is on credit hold |
| 403 | {"error":{"statusCode":"403","description":"API sending is not enabled for this account","message":"SERVICE_NOT_ALLOWED"}} | API sending is not enabled for the account |
| 403 | {"error":{"statusCode":"101","description":"sender 'MyBrand' not authorized for this account","message":"INVALID_SENDER"}} | Sender name is not approved for the account |
| 403 | {"error":{"statusCode":"102","description":"shorten URL domain 'go.example.com' not authorized for this account","message":"INVALID_DOMAIN"}} | shorturlDomain is not authorized |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | A request with the same key is still running |
| 429 | {"error":{"statusCode":"429","description":"rate limit exceeded: max 50 requests per second per account","message":"TOO_MANY_REQUESTS"}} | Too many requests (per IP / account / API key) — wait as told by Retry-After |
| 500 | {"error":{"statusCode":"500","description":"Failed to enqueue SMS for delivery","message":"QUEUE_PUBLISH_FAILED"}} | The messages could not be queued; nothing was sent — safe to retry (use Idempotency-Key) |
| 500 | {"error":{"statusCode":"500","description":"Failed to validate send request","message":"INTERNAL_ERROR"}} | Temporary failure while checking the request |
Check order
Checks run in this order: body format → length/recipient count → account status → API permission → sender name → credit → short-link domain. If any check fails, no recipient is sent.
