Messages
Send a message
Sends an SMS, MMS or RCS message from one of your numbers or RCS senders to one or more recipients.
POST
/
messages
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/messages \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"from": "+14155550100",
"to": [
"+14155550123"
],
"text": "Your verification code is 482913"
}
'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",
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from: '+14155550100',
to: ['+14155550123'],
text: 'Your verification code is 482913'
})
};
fetch('https://api.vobiz.ai/api/v1/sms/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"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"
}
Authorizations
Your Vobiz account Auth ID (MA_XXXXXXXX).
Your Vobiz account Auth Token.
Body
application/json
What to send, from which sender, to whom and on which channel, plus optional scheduling, idempotency, RCS and India DLT settings.
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"
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.
Minimum array length:
1Example:
["+14155550123"]
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.
Available options:
sms, mms, rcs 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"
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.
Maximum array length:
10Subject line of an MMS. Used only when the message is sent as MMS.
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"
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"
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.
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.
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.
Show child attributes
Show child attributes
India (TRAI DLT): the Principal Entity ID you registered on a TRAI DLT portal. Pass it on every message to Indian numbers.
India (TRAI DLT): the ID of the sender header you registered on a TRAI DLT portal. Pass it on every message to Indian numbers.
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.
Response
Sent or scheduled for every recipient. Body is the first recipient's message.
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.
Unique identifier of the message (UUID). Use it with GET /messages/{id} and to match status events.
Example:
"9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01"
Your Vobiz account ID (Auth ID), for example MA_XXXXXXXX.
Example:
"MA_XXXXXXXX"
out for a message you sent, in for a message one of your numbers received.
Available options:
out, in 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.
Available options:
sms, mms, rcs Sender. For outbound messages, your number in E.164 format or the senderName of your RCS sender; for inbound messages, the contact's number.
Example:
"+14155550100"
Recipient. For outbound messages, the contact's number in E.164 format; for inbound messages, your number.
Example:
"+14155550123"
Message body. An empty string when the message has no text, for example an MMS with media only.
Example:
"Your verification code is 482913"
HTTPS URLs of the media attached to the message. null or an empty array when there is no media.
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).
Available options:
scheduled, sent, delivered, failed, received, unknown Error code reported for a failed message. Omitted when there is no error.
Human-readable reason a message failed. Omitted when there is no error; quote it to support when you need help with a failure.
The label you set when sending, for filtering and reporting. Omitted when none was set.
UUID of the conversation the message belongs to. Use it with GET /conversations/{id}/messages to load the thread.
The time you asked the message to be held until (ISO 8601, UTC). Omitted for messages that were not scheduled.
When the message was created, as an RFC 3339 / ISO 8601 timestamp in UTC.
Example:
"2026-10-12T10:30:00Z"
When the message last changed, for example on a status update (ISO 8601, UTC).
Example:
"2026-10-12T10:30:00Z"
Was this page helpful?
⌘I
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/messages \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"from": "+14155550100",
"to": [
"+14155550123"
],
"text": "Your verification code is 482913"
}
'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",
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from: '+14155550100',
to: ['+14155550123'],
text: 'Your verification code is 482913'
})
};
fetch('https://api.vobiz.ai/api/v1/sms/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"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"
}