Skip to content

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 ​

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

Content Type ​

application/json (JSON only)

Parameter Description ​

PropertyTypeRequiredDescription
bulkIdstringOptionalBatch ID. A UUID is generated when omitted
messagesarray of MessageRequiredMessages to send, at least 1

Message ​

PropertyTypeRequiredDescription
fromstringRequiredSender name. Must be approved for your account (case-insensitive). See Sender List
destinationsarray of DestinationRequiredRecipients, at least 1. At most 1,000 recipients in total across all messages of one request
textstringRequiredMessage text, at most 1,600 characters (counted after trimming leading/trailing whitespace). See Credit calculation
notifyUrlstringOptionalURL the system POSTs the delivery result (Delivery Report) to. See Delivery Report
notifyContentTypestringOptionalAccepted for backward compatibility; currently has no effect
sendAtstringOptionalSend time in RFC3339, e.g. 2026-04-10T09:00:00+07:00 — see the warning below
shorturlstringOptionalY = replace URLs in the text (http://, https://, ftp://) with short links. Any other value or omitted = no shortening
shorturlDomainstringOptionalShort-link domain. Must be a domain authorized for your account, otherwise the request is rejected (INVALID_DOMAIN)
callbackDatastringOptionalYour own reference data. Accepted, but currently not returned in the callback

Destination ​

PropertyTypeRequiredDescription
tostringRequiredThai 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
messageIdstringOptionalYour 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 ​

PropertyTypeDescription
bulkIdstringThe bulkId you sent, or the generated UUID
detailsarrayPer-recipient results, in request order
details[].messageIdstringThe messageId you sent, or the generated UUID
details[].mobilestringNormalized number (66XXXXXXXXX) — for an invalid number, the original value
details[].tostringSame as mobile
details[].fromstringSender name
details[].creditstringCredit per recipient (SMS parts) with 2 decimals, e.g. "1.00"
details[].shorturlstringY or N
details[].status.codestringStatus code, see below
details[].status.namestringPENDING or REJECTED
details[].status.descriptionstringStatus description

Per-recipient status ​

codenamedescriptionMeaning
101PENDINGPending -Message has been accepted by the systemQueued for sending
402REJECTEDInvalid number - phone number formatted incorrectlyInvalid number; not sent, not charged
403REJECTEDNumber is blacklistedNumber is on your account blacklist; not sent, not charged
SUPPRESSEDREJECTEDRecipient has opted out of non-OTP SMSRecipient opted out of non-OTP SMS; not sent, not charged
NO_CONSENTREJECTEDNo consent from recipient for this accountYour 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 ​

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 Example ​

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

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.

HTTPResponseCause
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.