Vobiz Messaging API - Messages

A message is one SMS, MMS or RCS message sent from, or received by, your Vobiz account. You use the Messages endpoints to send, to look up what you sent and received, and to check cost and RCS reachability before you send. Every recipient of a send gets its own message object, with its own id, status and conversation.

POST /messages sends real messages to real phones and is billed per segment to your account. Run it only with your own credentials, numbers you own, and recipients who have agreed to hear from you.

The message object

Field	Type	Description
`id`	string (UUID)	Unique identifier of the message.
`accountId`	string	Your Vobiz account ID, for example `MA_XXXXXXXX`.
`direction`	string	`out` for a message you sent, `in` for a message one of your numbers received.
`channel`	string	Channel actually used: `sms`, `mms` or `rcs`. It can differ from the one you requested after an MMS upgrade or an SMS fallback.
`from`	string	Sender: your number in E.164 format or your RCS sender’s `senderName` for outbound; the contact’s number for inbound.
`to`	string	Recipient: the contact’s number for outbound; your number for inbound.
`text`	string	Message body. An empty string when there is no text.
`mediaUrls`	array or `null`	HTTPS URLs of attached media.
`status`	string	Lifecycle status. See Message statuses.
`errorCode`	string	Error code for a failed message. Omitted when there is no error.
`errorMessage`	string	Human-readable failure reason. Omitted when there is no error.
`tag`	string	Your label from the send request. Omitted when none was set.
`conversationId`	string (UUID)	The conversation the message belongs to.
`scheduledAt`	string (ISO 8601)	The time you asked the message to be held until. Omitted when not scheduled.
`createdAt`	string (ISO 8601)	When the message was created.
`updatedAt`	string (ISO 8601)	When the message last changed.

GET /messages/{id} also returns statusHistory: every status the message passed through, oldest first, each with status, createdAt and any errorCode or errorMessage.

Endpoints

Method	Endpoint	What it does
`POST`	`/messages`	Send an SMS, MMS or RCS message to one or more recipients.
`GET`	`/messages`	List sent and received messages, with filters and pagination.
`GET`	`/messages/{id}`	Retrieve one message with its full status history.
`GET`	`/messages/cost-preview`	Price a message and count its segments without sending it.
`GET`	`/messages/rcs-reachability`	Check whether a number can receive RCS from your sender.

All paths are relative to https://api.vobiz.ai/api/v1/sms. Every request carries your X-Auth-ID and X-Auth-Token headers.

Message statuses

Status	Meaning
`scheduled`	The message has a future `scheduledAt` and is held until then.
`sent`	The message has been handed to the network.
`delivered`	The network confirmed delivery to the handset.
`failed`	The message could not be delivered. Read `errorCode` and `errorMessage`.
`received`	An inbound message one of your numbers received.
`unknown`	The network reported a status that maps to none of the others.

Follow status changes in real time with webhooks (callbacks) or the WebSocket, or poll Retrieve a message.

Sending to several recipients

to is an array. Each unique, non-empty number becomes a separate message, and the response body is the first recipient’s message. Set a tag on the request so you can find every message it created with GET /messages?tag=....

Response	When
`201`	Every recipient was accepted, including an idempotent replay and a successful SMS fallback.
`202`	At least one recipient was recorded and at least one errored. Check each recipient with `GET /messages`.
`422`	The recipient has opted out and nothing was recorded.
`502`	The send was rejected before a message was recorded. Retry with the same `idempotencyKey`.

Idempotency

Pass an idempotencyKey on every send you might retry. The key is scoped to your account. A retry with the same key returns the original message with 201 and sends nothing new. With several recipients, the key is applied per recipient, so a retry never sends twice to anyone.

Example

cURL

curl -X POST "https://api.vobiz.ai/api/v1/sms/messages" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155550100",
    "to": ["+14155550123"],
    "channel": "sms",
    "text": "Your verification code is 482913",
    "tag": "otp",
    "idempotencyKey": "otp-7f3a9c"
  }'

201 Created

{
  "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
  "accountId": "MA_XXXXXXXX",
  "direction": "out",
  "channel": "sms",
  "from": "+14155550100",
  "to": "+14155550123",
  "text": "Your verification code is 482913",
  "mediaUrls": null,
  "status": "sent",
  "tag": "otp",
  "conversationId": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
  "createdAt": "2026-10-18T09:15:02.123456Z",
  "updatedAt": "2026-10-18T09:15:02.123456Z"
}

Pagination

GET /messages returns {"messages": [...], "total": n, "limit": n, "offset": n}, newest first. limit ranges from 1 to 100 and defaults to 20. Increase offset by the page size until offset reaches total.

Getting Started

API Reference

Guides

Vobiz Messaging API - Messages

The message object

Endpoints

Message statuses

Sending to several recipients

Idempotency

Example

​The message object

​Endpoints

​Message statuses

​Sending to several recipients

​Idempotency

​Example

​Pagination

​Related

The message object

Endpoints

Message statuses

Sending to several recipients

Idempotency

Example

Pagination

Related