> ## 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. # Send a message > Sends an SMS, MMS or RCS message from one of your numbers or RCS senders to one or more recipients. ## OpenAPI ````yaml openapi-sms.yaml POST /messages openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /messages: post: tags: - Messages summary: Send a message description: >- Sends an SMS, MMS or RCS message from one of your numbers or RCS senders to one or more recipients. Each number in `to` becomes its own message, with its own `id`, status and conversation, and the response body is the first recipient's message. Every recipient is checked against your opt-out list first, and a send with a future `scheduledAt` is stored with status `scheduled`. - `201` when every recipient was accepted, including an idempotent replay and a successful SMS fallback. - `202` when at least one recipient was recorded and at least one errored. Find the other recipients with `GET /messages` filtered by `tag` or `to`. - `422` when the recipient has opted out and nothing was recorded. - `502` when the send was rejected before a message was recorded. Retry with the same `idempotencyKey`. Track delivery with `GET /messages/{id}`, your webhooks (callbacks) or the WebSocket. operationId: send-message requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageRequest' examples: sms: summary: SMS with idempotency key value: from: '+14155550100' to: - '+14155550123' channel: sms text: Your verification code is 482913 idempotencyKey: otp-482913-user-77 mms: summary: MMS with media value: from: '+14155550100' to: - '+14155550123' channel: mms title: Your invoice text: Here is your invoice. mediaUrls: - https://example.com/invoice.pdf rcs: summary: RCS with buttons and SMS fallback value: from: YOUR_RCS_SENDER_NAME to: - '+14155550123' channel: rcs text: Your appointment is confirmed for 3pm tomorrow. rcsSuggestions: - type: REPLY text: Reschedule postbackData: reschedule - type: DIAL_PHONE text: Call us postbackData: call phoneNumber: '+14155550100' failoverToSms: true idempotencyKey: appt-8812-confirm india: summary: SMS to India with DLT IDs value: from: '+919876543210' to: - '+919876500001' channel: sms text: Your OTP is 4821. dltEntityId: '1001234567890123456' dltHeaderId: '1001234567' dltTemplateId: '10012345678901234567' responses: '201': description: >- Sent or scheduled for every recipient. Body is the first recipient's message. content: application/json: schema: $ref: '#/components/schemas/Message' example: 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-12T10:30:00Z' updatedAt: '2026-10-12T10:30:00Z' '202': description: >- Several recipients and at least one failed. Body is the first recipient's message; check each recipient individually. content: application/json: schema: $ref: '#/components/schemas/Message' '400': description: Invalid body, bad `scheduledAt`, or an MMS validation error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: body: value: error: invalid request body mms: value: error: 'invalid mms: mediaUrls[0] must use https' '401': $ref: '#/components/responses/Unauthorized' '422': description: The recipient has opted out. Nothing was sent. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'recipient has opted out: +14155550123' '502': description: >- The network rejected the send and nothing was recorded. Retry with the same `idempotencyKey`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- routing failed: no provider available for channel=sms from=+14155550100 to=+14155550123 x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.messages.sendMessage({ from: "+14155550100", to: ["+14155550123"], channel: "sms", text: "Your verification code is 482913", idempotencyKey: "otp-482913-user-77" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.messages.send_message( from_="+14155550100", to=[ "+14155550123" ], channel="sms", text="Your verification code is 482913", idempotency_key="otp-482913-user-77", ) - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.SendMessageRequest{ From: "+14155550100", To: []string{ "+14155550123", }, Channel: sms.SendMessageRequestChannelSms.Ptr(), Text: vobiz.String( "Your verification code is 482913", ), IdempotencyKey: vobiz.String( "otp-482913-user-77", ), } c.Sms.Messages.SendMessage( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().messages().sendMessage( SendMessageRequest .builder() .from("+14155550100") .to( Arrays.asList("+14155550123") ) .channel(SendMessageRequestChannel.SMS) .text("Your verification code is 482913") .idempotencyKey("otp-482913-user-77") .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.messages.send_message( from: "+14155550100", to: ["+14155550123"], channel: "sms", text: "Your verification code is 482913", idempotency_key: "otp-482913-user-77" ) - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Messages.SendMessageAsync( new SendMessageRequest { From = "+14155550100", To = new List() { "+14155550123" }, Channel = SendMessageRequestChannel.Sms, Text = "Your verification code is 482913", IdempotencyKey = "otp-482913-user-77", } ); - lang: php label: PHP SDK source: > sms->messages->sendMessage( new SendMessageRequest([ 'from' => '+14155550100', 'to' => [ '+14155550123', ], 'channel' => SendMessageRequestChannel::Sms->value, 'text' => 'Your verification code is 482913', 'idempotencyKey' => 'otp-482913-user-77', ]), ); components: schemas: SendMessageRequest: type: object required: - from - to properties: from: type: string description: >- The sender. For `sms` and `mms`, one of your Vobiz numbers in E.164 format, for example `+14155550100`. For `rcs`, the `senderName` of your RCS sender (from `GET /senders`); with `failoverToSms`, the SMS copy is sent from a number on your account. example: '+14155550100' to: type: array description: >- One or more recipient numbers in E.164 format. Each one becomes a separate message with its own `id`; blank entries and duplicates are ignored. At least one recipient is required. minItems: 1 items: type: string example: - '+14155550123' channel: type: string enum: - sms - mms - rcs default: sms description: >- Channel to send on: `sms`, `mms` or `rcs`. Defaults to `sms`. An `sms` with `mediaUrls` to US or Canadian recipients is sent as MMS automatically. text: type: string description: >- Message body. Required for `sms` and `rcs`. A long SMS is split into segments and billed per segment (160 GSM-7 or 70 UCS-2 characters fit in one segment). For `mms`, provide `text`, `mediaUrls` or both, with `text` up to 5000 characters. example: Your verification code is 482913 mediaUrls: type: array description: >- Publicly reachable `https` URLs of media to attach. MMS accepts up to 10. RCS sends the first URL as a file. An SMS to recipients outside the US and Canada is sent as text only. maxItems: 10 items: type: string format: uri title: type: string description: Subject line of an MMS. Used only when the message is sent as MMS. tag: type: string description: >- Your own label, stored on every message the request creates. Filter `GET /messages` by it to find all recipients of one send or to group messages for reporting. example: otp idempotencyKey: type: string description: >- A unique string you choose, for example a UUID or your own order ID, scoped to your account. Retrying with the same key returns the original message instead of sending again. With several recipients the key is applied per recipient. example: otp-482913-user-77 scheduledAt: type: string format: date-time description: >- Time to hold the message until, as an RFC 3339 / ISO 8601 timestamp such as `2026-11-01T09:00:00Z`. A future time stores the message with status `scheduled`; a past time or now sends immediately. failoverToSms: type: boolean default: false description: >- Used only when `channel` is `rcs`. When `true` and the RCS send cannot go through, Vobiz sends the same `text` as SMS and the message's `channel` becomes `sms`. Defaults to `false`. rcsSuggestions: type: array description: >- Suggestion buttons (suggested replies and actions) to show under an RCS message. Used only when `channel` is `rcs`. See the RCS suggestion object for each `type`. items: $ref: '#/components/schemas/RCSSuggestion' dltEntityId: type: string description: >- India (TRAI DLT): the Principal Entity ID you registered on a TRAI DLT portal. Pass it on every message to Indian numbers. dltHeaderId: type: string description: >- India (TRAI DLT): the ID of the sender header you registered on a TRAI DLT portal. Pass it on every message to Indian numbers. dltTemplateId: type: string description: >- India (TRAI DLT): the ID of the content template you registered on a TRAI DLT portal. `text` must match that template with its variables filled in. description: >- What to send, from which sender, to whom and on which channel, plus optional scheduling, idempotency, RCS and India DLT settings. Message: type: object description: >- One message sent from or received by your account. Each recipient of a send gets its own message object with its own `id`, status and conversation. properties: id: type: string format: uuid example: 9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01 description: >- Unique identifier of the message (UUID). Use it with `GET /messages/{id}` and to match status events. accountId: type: string description: Your Vobiz account ID (Auth ID), for example `MA_XXXXXXXX`. example: MA_XXXXXXXX direction: type: string enum: - out - in description: >- `out` for a message you sent, `in` for a message one of your numbers received. channel: type: string enum: - sms - mms - rcs description: >- Channel the message actually used: `sms`, `mms` or `rcs`. It can differ from the one you requested, for example `mms` after an SMS with media to US or Canadian numbers, or `sms` after an RCS send fell back with `failoverToSms`. from: type: string example: '+14155550100' description: >- Sender. For outbound messages, your number in E.164 format or the `senderName` of your RCS sender; for inbound messages, the contact's number. to: type: string example: '+14155550123' description: >- Recipient. For outbound messages, the contact's number in E.164 format; for inbound messages, your number. text: type: string example: Your verification code is 482913 description: >- Message body. An empty string when the message has no text, for example an MMS with media only. mediaUrls: type: array nullable: true items: type: string format: uri description: >- HTTPS URLs of the media attached to the message. `null` or an empty array when there is no media. status: type: string enum: - scheduled - sent - delivered - failed - received - unknown description: >- Where the message is in its lifecycle: `scheduled` (held for `scheduledAt`), `sent` (handed to the network), `delivered` (delivery confirmed), `failed` (see `errorCode` and `errorMessage`), `received` (inbound) or `unknown` (the network reported a status that maps to none of the others). errorCode: type: string description: >- Error code reported for a failed message. Omitted when there is no error. errorMessage: type: string description: >- Human-readable reason a message failed. Omitted when there is no error; quote it to support when you need help with a failure. tag: type: string description: >- The label you set when sending, for filtering and reporting. Omitted when none was set. conversationId: type: string format: uuid description: >- UUID of the conversation the message belongs to. Use it with `GET /conversations/{id}/messages` to load the thread. scheduledAt: type: string format: date-time description: >- The time you asked the message to be held until (ISO 8601, UTC). Omitted for messages that were not scheduled. createdAt: type: string format: date-time example: '2026-10-12T10:30:00Z' description: >- When the message was created, as an RFC 3339 / ISO 8601 timestamp in UTC. updatedAt: type: string format: date-time example: '2026-10-12T10:30:00Z' description: >- When the message last changed, for example on a status update (ISO 8601, UTC). Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. RCSSuggestion: type: object description: >- One suggestion button on an RCS message: a suggested reply or an action the recipient can tap. Which optional fields apply depends on `type`. required: - type - text properties: type: type: string enum: - REPLY - OPEN_URL - DIAL_PHONE - SHOW_LOCATION - REQUEST_LOCATION description: >- What the button does: `REPLY` sends `text` back as a reply, `OPEN_URL` opens `url`, `DIAL_PHONE` calls `phoneNumber`, `SHOW_LOCATION` shows a map pin at `latitude`/`longitude`, and `REQUEST_LOCATION` asks the recipient to share their location. text: type: string description: >- Button label shown to the recipient. Keep it short so it fits on the button. example: Reschedule postbackData: type: string description: >- Your own string, returned to you with the inbound event when the recipient taps the button. Use it to tell which button was tapped. example: reschedule url: type: string format: uri description: HTTPS link to open. Used only when `type` is `OPEN_URL`. phoneNumber: type: string description: >- Phone number to dial, in E.164 format. Used only when `type` is `DIAL_PHONE`. example: '+14155550100' latitude: type: number description: >- Latitude of the map pin, in decimal degrees from `-90` to `90`. Used only when `type` is `SHOW_LOCATION`. longitude: type: number description: >- Longitude of the map pin, in decimal degrees from `-180` to `180`. Used only when `type` is `SHOW_LOCATION`. label: type: string description: >- Label shown on the map pin. Used only when `type` is `SHOW_LOCATION`. responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.