Skip to main content
POST
/
messages
curl --request POST \
  --url https://api.hixbe.com/sms/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Hixbe-Version: <hixbe-version>' \
  --data '
{
  "to": "8801712345678",
  "from": "HIXBE",
  "message": "Your OTP is 391202. Valid for 5 minutes. Do not share.",
  "route": "otp"
}
'
{
  "id": "msg_abc123xyz",
  "to": "8801712345678",
  "from": "HIXBE",
  "body": "Your OTP is 391202. Valid for 5 minutes. Do not share.",
  "status": "queued",
  "route": "otp",
  "segments": 1,
  "cost": 0.75,
  "scheduled_at": null,
  "sent_at": null,
  "delivered_at": null,
  "error_code": null,
  "created_at": "2026-01-15T10:30:00Z"
}

Authorizations

​
Authorization
string
header
required

Use your API key as a Bearer token. Format: Authorization: Bearer sk_live_xxxxx

Headers

​
Hixbe-Version
string
default:2026-01-01
required

API version in YYYY-MM-DD format. Using the latest version ensures access to newest features.

Pattern: ^\d{4}-\d{2}-\d{2}$
​
Idempotency-Key
string

Unique key for request idempotency. Prevents duplicate messages if you retry the same request within 24 hours.

Maximum string length: 255

Body

application/json
​
to
string
required

Recipient phone number in international format (no + or spaces)

Pattern: ^[1-9][0-9]{7,14}$
Example:

"8801712345678"

​
message
string
required

Message content (max 1000 characters)

Required string length: 1 - 1000
Example:

"Welcome to HIXBE! Your account has been activated successfully."

​
from
string

Sender ID (must be registered and approved). Defaults to account default sender.

Maximum string length: 11
Example:

"HIXBE"

​
schedule_at
string<date-time> | null

Schedule message for future delivery (ISO 8601 format, max 7 days ahead)

Example:

"2026-01-16T09:00:00Z"

​
route
enum<string>
default:transactional

Message route. OTP: <5s delivery, Transactional: <30s, Promotional: <2min

Available options:
otp,
transactional,
promotional
Example:

"transactional"

​
reference_id
string

Optional reference ID for your internal tracking

Maximum string length: 100
Example:

"order_12345"

​
callback_url
string<uri>

Optional webhook URL for this specific message (overrides account webhook)

Example:

"https://yourapp.com/webhook/order-12345"

Response

Message accepted and queued for delivery

SMS message object with delivery status and metadata

​
id
string
required

Unique message identifier

Example:

"msg_abc123xyz"

​
to
string
required

Recipient phone number in international format

Example:

"8801712345678"

​
from
string
required

Sender ID (alphanumeric or numeric)

Example:

"HIXBE"

​
body
string
required

Message content

Example:

"Your OTP is 391202. Valid for 5 minutes."

​
status
enum<string>
required

Current message status

Available options:
queued,
sent,
delivered,
failed,
expired
Example:

"delivered"

​
created_at
string<date-time>
required

Message creation timestamp

Example:

"2026-01-15T10:30:00Z"

​
route
enum<string>

Message route used for delivery

Available options:
otp,
transactional,
promotional
Example:

"transactional"

​
segments
integer

Number of SMS segments (1 segment = 160 chars)

Required range: x >= 1
Example:

1

​
cost
number

Message cost in account currency

Required range: x >= 0
Example:

0.5

​
scheduled_at
string<date-time> | null

Scheduled delivery time (ISO 8601 format)

Example:

"2026-01-15T14:30:00Z"

​
sent_at
string<date-time> | null

Timestamp when message was sent to carrier

Example:

"2026-01-15T10:30:05Z"

​
delivered_at
string<date-time> | null

Timestamp when message was delivered

Example:

"2026-01-15T10:30:15Z"

​
error_code
string | null

Error code if delivery failed

Example:

"number_unreachable"