Skip to main content
POST
Send a transactional SMS

Authorizations

Authorization
string
header
required

Your Robase API key. Starts with robe_. Include as Authorization: Bearer robe_...

Headers

Idempotency-Key
string

Opaque client-generated key. Replaying the same key within 24 hours returns the original response (with Idempotent-Replayed: true) instead of performing the action again. Recommended for every send so a network-level retry cannot double-charge. The same key with a different endpoint or body returns 422 idempotency_key_reused; a repeat while the first request is still running returns 409 request_in_progress. 5xx and 429 responses are not kept, so a retry with the same key runs again.

Maximum string length: 255

Body

application/json
phone_number
string
required

Phone number in E.164 format

Example:

"+2348012345678"

message
string
required

SMS message body. The limit is six SMS segments, not a character count: a carrier splits a long message into parts and bills each one, and how many characters fit in a part depends on the alphabet the message needs — 160 per part in GSM-7 (153 once it is split), but 70 (then 67) as soon as one character forces UCS-2. So the practical ceiling is 918 plain-Latin characters, or 402 in a script that needs UCS-2.

Example:

"Your order #12345 has been shipped."

metadata
object

Arbitrary key-value data attached to the message

Response

SMS created, charged, and queued for delivery

id
string<uuid>
required

SMS message ID

phone_number
string
required

Phone number the SMS was sent to

country_code
string
required

ISO 3166-1 alpha-2 country code

credit_cost
integer
required

Credits consumed: the country's rate multiplied by segments, since a carrier bills each part of a split message as its own send.

status
enum<string>
required

Initial status — always pending; transitions to sent/delivered/failed asynchronously, or to blocked if anti-spam screening stops it before dispatch (the credit is then refunded).

Available options:
pending
created_at
string<date-time>
required
segments
integer

How many SMS parts the message was split into, and therefore the multiple of the country's rate it was charged at.

Example:

1

encoding
enum<string>

The alphabet the message needed, which is what decided the part size: 160 characters per part in gsm7, 70 in ucs2. A single character outside the GSM alphabet moves the whole message to ucs2.

Available options:
gsm7,
ucs2
sanitized
boolean

Whether the body was rewritten before it was measured. With the workspace's sanitize_symbols setting on (the default), characters GSM-7 cannot carry are replaced with plain equivalents — ₦ becomes NGN, curly quotes straighten — and anything with no equivalent, such as an emoji, is removed. Letters are never removed, and the rewrite is dropped whenever it would not lower the part count. Turn the setting off to have bodies delivered exactly as sent.