> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vobiz Messaging API - Messages

> Send SMS, MMS and RCS messages with the Vobiz Messaging API, list and retrieve them with their status history, preview the cost and check RCS reachability.

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.

<Warning>
  `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.
</Warning>

## 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](#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](/docs/sms/api/conversations) 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`](/docs/sms/api/messages/send-message) | Send an SMS, MMS or RCS message to one or more recipients. |
| `GET` | [`/messages`](/docs/sms/api/messages/list-messages) | List sent and received messages, with filters and pagination. |
| `GET` | [`/messages/{id}`](/docs/sms/api/messages/get-message) | Retrieve one message with its full status history. |
| `GET` | [`/messages/cost-preview`](/docs/sms/api/messages/cost-preview) | Price a message and count its segments without sending it. |
| `GET` | [`/messages/rcs-reachability`](/docs/sms/api/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)](/docs/sms/webhooks) or the [WebSocket](/docs/sms/websocket), or poll [Retrieve a message](/docs/sms/api/messages/get-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](/docs/sms/api/opt-outs) 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

```bash cURL theme={null}
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"
  }'
```

```json 201 Created theme={null}
{
  "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`.

## Related

* [Send SMS](/docs/sms/channels/sms)
* [Send MMS](/docs/sms/channels/mms)
* [Send RCS](/docs/sms/channels/rcs)
* [India DLT](/docs/sms/compliance/india-dlt)
* [Conversations](/docs/sms/conversations)
* [Webhooks](/docs/sms/webhooks)
* [Errors](/docs/sms/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.