Single SMS API Reference
Send a single SMS through ValueText's REST API and get the delivery status back right away. The same API family includes a Bulk SMS endpoint for sending a list of messages in one call. ValueText also builds custom APIs to fit specific customer needs.
Last updated 28 Nov 2025Send a single message
Endpoint: https://valuetext.io/valuetext/rest/message/single/rest
Method: GET
Parameters
| Parameter | Description | Required |
|---|---|---|
mobileNumber | Mobile number of the receiver. The country code is mandatory before the number, for example +91-xxxxxxxxx, +1-xxx-xxx-xxxx, or 1xxxxx. | Yes |
sms | The message content. Must be URL encoded and use the UTF-8 character set. | Yes |
senderId | Alphanumeric string or number that sets the FROM address of the message. | Yes |
clientId | Optional. Your own ID, up to 40 characters, echoed back in the response. | No |
Headers
ValueText authenticates single SMS requests with an API key and secret key, sent as headers:
apiKey: myApiKeysecretKey: mySecretKey
To find your account's API key and secret key: log in to valuetext.io, click your name, then click Settings.
Sample request
Important: the sms body of the message must be URL encoded and use the UTF-8 character set for the Single SMS API.
Sample response
The response fields and status codes match the Bulk SMS API's, covered in Response parameters and Response status codes below.
Send a bulk message
The Bulk SMS API sends a list of messages in a single call, built to deliver messages quickly. ValueText also offers custom APIs to fit specific integration needs.
Endpoint: https://valuetext.io/valuetext/rest/message/bulk/rest
Method: POST
Parameters
| Parameter | Description | Required |
|---|---|---|
mobileNumber | Mobile number of the receiver. The country code is mandatory before the number, for example +91-xxxxxxxxx, +1-xxx-xxx-xxxx, or 1xxxxx. | Yes |
sms | The message content, in UTF-8 character set. | Yes |
senderId | Alphanumeric string or number that sets the FROM address of the message. | Yes |
clientId | Optional. Your own ID, up to 40 characters, echoed back in the response. | No |
Headers
Set the content type based on the request you're sending:
content-type: application/json
Authentication parameters: ValueText authenticates bulk requests the same way, with an API key and secret key sent as headers:
apiKey: myApiKeysecretKey: mySecretKey
To find your account's API key and secret key: log in to valuetext.io, click your name, then click Settings.
Sample request (content-type: application/json)
deliveryModes accepts SMS, WHATSAPP, or WHATSAPP,SMS. The combined value tries WhatsApp first: if the customer isn't reachable on WhatsApp, or has no WhatsApp field, the message falls back to SMS.
Sample response
The response is always JSON:
Response parameters
| Parameter | Description |
|---|---|
sms | Content of the message. Must be URL encoded and use the UTF-8 character set. |
senderId | Alphanumeric string indicating the FROM address of the message. |
smsId | A unique ID generated for each message request. |
statusCode | Status code for the message. |
statusMsg | Status of the message, for example Sent, Delivered, Fail. |
statusDescription | Detailed description of the message's status. |
mobileNumber | Contact number the message was delivered to. |
clientId | The ID you set on the SMS request. |
messageCount | Body/text of the SMS. 160 characters equals 1 SMS count. |
messageCost | Cost per message sent. Example: a messageCount of 2 at 0.0012 each gives a messageCost of 0.0024 (2 x 0.0012). |
balance | Balance available to send messages, for all countries excluding India. |
Response status codes
Possible values for statusCode, status, and statusMsg on the response:
| statusCode | status | statusMsg |
|---|---|---|
| 7000 | Submitted | Accepted the message to send |
| 7001 | Queued | Placed your request |
| 7002 | Sent | Message sent and waiting for an operator response |
| 7003 | Delivered | Message delivered successfully |
| 7004 | Undelivered | Undelivered, unknown reasons |
| 7005 | Undelivered | Number barred or unsupported number |
| 7006 | Undelivered | Message content is invalid |
| 7007 | Unknown | Unknown status |
| 7008 | FAIL | Invalid parameters |
| 7009 | FAIL | Invalid sender ID, or sender ID activation pending |
| 7010 | FAIL | Invalid mobile number |
| 7011 | FAIL | Invalid message body or template |
| 7012 | FAIL | Exceeds the maximum limit of 650 characters |
| 7013 | FAIL | Unsupported country, or unable to identify the country code |
| 7014 | FAIL | Trial account can send messages only to registered, trusted numbers |
| 7015 | FAIL | Authentication failed |
| 7016 | FAIL | Internal process error |
| 7017 | FAIL | Insufficient funds |
| 7018 | FAIL | Throttled, exceeding limit |
| 7019 | FAIL | Opted-out mobile number |
| 7020 | FAIL | Do Not Disturb rules accounted |
| 7022 | FAIL | Unsupported sender ID for the receiving country |
| 7021 | Hold | Held by the user |
Set up a webhook
ValueText sends an HTTP POST request to your webhook to deliver updated status about each message. You can configure your webhook on the settings page after you log in.