Send SMS batch

POST https://sms.8x8.com/api/v1/subaccounts/:subAccountId/messages/batch

Sending a POST request to this endpoint allows you to send SMS by batches (1 request for multiple SMS) with shared or personalized contents/properties.
Personalized content is ideal for sending marketing campaigns or any mass personalized announcement.
Shared content is easier to use for such cases as an announcement, message broadcasting, etc.
It only accepts messages with the same properties (source, text, encoding, scheduling time, and expiry time).
Using this endpoint, it is possible to send up to 10,000 SMS per request.

URL

The 8x8 SMS subaccountid to use is defined in the URL where you send your POST request as shown below:

https://sms.8x8.com/api/v1/subaccounts/{subAccountId}/messages/batch

You must replace {subAccountId} in the URL above with the subaccountid that you want to use.

Request

Path Parameters

subAccountId stringrequired

Possible values: >= 3 characters and <= 50 characters, Value must match regular expression ^[A-Za-z0-9\-._&]{3,50}$

You must replace {subAccountId} with the subaccountid that you want to use. By default this is generated once you signed up with a new account at https://connect.8x8.com.

Body

Request structure

To send many SMS using the 8x8 SMS API you need to submit a JSON-formatted request with the following elements:

Name	Type	Description	Required
messages	array	Array containing multiple SmsRequest objects (see Single doc)	Required, Exclusive
destinations	array	Array containing the list of destinations phone numbers to send an SMS to	Required, Exclusive
clientBatchId	string	Unique ID that you want to associate with the batch of SMS	Optional
template	object	Object applying common properties to the SmsRequest objects in messages	Optional
includeMessagesInResponse	boolean	Boolean defining if the API response should contain the SMS details	Optional

Use messages property to create a batch with personalized content or destinations field to send the same shared content to multiple phones.
Either messages or destinations should be provided in the request. If both properties are provided, the messages property takes precedence, and the destinations property is discarded.

About the template object

The many endpoint incorporates a new logic with the template object.
The purpose of this object is to let you specify the common properties of the SMS contained in the messages into a single object.
The best practice is to only incorporate the unique properties of each SMS in the SmsRequest objects contained in the messages array while specifying the common properties in the template object.
The template object is optional in the request.

The template object can take the following parameters:

Name	Type	Description	Required
text	string	SMS body (ie: text of the message)	Required
source	string	Alphanumeric or numeric string used as Sender ID for the SMS	Optional
encoding	string	Character set to use for this SMS - The possible values are `AUTO` - `GSM7` - `UCS2`	Optional
scheduled	timestamp	Pre-defined date and time for this SMS to be sent in the future	Optional
expiry	timestamp	Maximum date and time for this SMS to be sent at	Optional
dlrCallbackUrl	uri	Webhook URL where delivery status for the SMS will be posted (Overwrites your default account callback URL).	Optional

clientBatchIdstring

Client managed id for this batch of messages : your own unique reference

Possible values: <= 20 characters

messages object[]required

Possible values: >= 1, <= 10000

Array [

destinationstringrequired

MSISDN (destination mobile phone number). We accept both international and national formats (for national you have to specify country in the dedicated field).

Possible values: Value must match regular expression ^\+{0,1}[1-9]{1}[0-9]{6,14}$

countrystring

Optional country code of Destination number(ISO 3166-1 alpha-2), if you know it. It will help to convert number from national to international format

Possible values: <= 2 characters

sourcestring

Source number (SenderId) - "From:" field for the SMS

Possible values: <= 16 characters

clientMessageIdstring

Client managed id for the message : your own unique reference

Possible values: <= 350 characters

textstringrequired

Message body - the text of the message

encodingstring

Encoding for the text of the message

Possible values: [AUTO, GSM7, UCS2]

Default value: AUTO

scheduledstring<date-time>

Date and time when a schedule delivery of the message must happen

expirystring<date-time>

Date and time after which a message cannot be sent

dlrCallbackUrlstring<uri>

Webhook URL where delivery status for the SMS will be posted (Overwrites your default account callback URL).

clientIpstring

Fill this field to limit the number of SMS sent within a period of time based on IP address.
If the request is forwarded by one or multiple proxies, to enforce the rate limit to client IP correctly, you may want to look up the X-Forwarded-For header and retrieve the actual origin IP and assign it to this field.
You can refer to IP spoofing for more details.

trackstring

Indicate whether use the sent SMS for tracking conversion rate.
Use Outcome for tracking and None for no tracking.
If no value is provided, there's no tracking unless subaccount has been configured for tracking beforehand.
The conversion rate is measured by 8x8 to monitor your application QoS.
To complete the tracking, you will also need to use Feedback API to update the sent result.
You can read here to learn more about conversion rate tracking and SMS feedback.

Possible values: [None, Outcome]

Default value: null

]

destinationsstring[]

List of destination phone numbers

Possible values: >= 1, <= 10000

template object

sourcestring

Alphanumeric or numeric string used as Sender ID for the template

Possible values: <= 16 characters

textstring

Template message body

encodingstring

Encoding of the message text. In most cases just useAUTO. 8x8 SMS platform will automatically identify the required encoding.

Possible values: [AUTO, GSM7, UCS2]

Default value: AUTO

scheduledstring<date-time>

Date and time when a schedule delivery of the message must happen.

expirystring<date-time>

Date and time after which a message will be discarded if it is still in processing.

dlrCallbackUrlstring<uri>

Webhook URL where delivery status for the SMS will be posted (Overwrites your default account callback URL).

includeMessagesInResponseboolean

Determines whether the reponse should include individual details for each message sent

clientIpstring

The response returns two different IDs for the batch:
- batchId: the unique batch ID generated automatically by 8x8
- clientBatchId: the batch ID that you submitted in the request (if any)
It also returns a summary of the batch submission:
- acceptedCount: number of SMS accepted by the API
- rejectedCount: number of SMS rejected by the API
If the includeMessagesInResponse boolean has been set to True during the request, it also returns an array containing individual information for each SMS submitted to the API in the many request:
- umid: unique message ID automatically generated by 8x8
- clientMessageId: message ID that you submitted (if any)
- destination: destination phone number to which the SMS was sent to
- encoding: SMS encoding - GSM7 or UCS2
And then it returns a status object containing the following:
- status code: the status code can be either:
  - QUEUED: the SMS has been accepted by 8x8 SMS API and is queued for processing.
  - REJECTED: the SMS has been rejected by 8x8 SMS API and the reason is stated in the description field. It will not be processed.
- description: this field describes the status code and provides additional information explaining the status. It can take the following values:
  - SMS is accepted and queued for processing (QUEUED Status)
  - Text value is missing (REJECTED Status)
  - Invalid Text value. Reached max allowed limit (REJECTED Status)
  - Invalid Source value. Reached max allowed limit (REJECTED Status)
  - Expiry time already reached (REJECTED Status)
  - Invalid MSISDN format (not E.164 international number) (REJECTED Status)
  - Internal server error (REJECTED Status)

Schema

batchIdstring<uuid>required

Unique batch id (guid) generated by 8x8 SMS platform upon batch submission

clientBatchIdstring

Client managed id for this batch of messages : your own unique reference

acceptedCountintegerrequired

Amount of accepted messages

rejectedCountintegerrequired

Amount of rejected messages

messages object[]

List of processed messages (if flag includeMessagesInResponse=true)

Array [

umidstringrequired

Unique message id (guid) generated by 8x8 SMS platform upon message submission

destinationstringrequired

Mobile phone number (MSISDN) to which the SMS was sent

Possible values: Value must match regular expression ^\+?\d{7,15}$

status objectrequired

codestringrequired

Code for the SMS delivery status.

Possible values: [QUEUED, REJECTED]

descriptionstringrequired

Explanation for code.

encodingstringrequired

Detected message encoding. Useful when sending initial request with encoding=AUTO

Possible values: [AUTO, GSM7, UCS2]

clientMessageIdstring

Your custom identifier for the message

]

{
"batchId":"f1ea5276-a824-e711-8146-022a22cc1c71",
"clientBatchId":"SmsApi-Demo1",
"acceptedCount":3,
"rejectedCount":1,
"messages":[
{
"umid":"f2ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"SmsApi-Demo1/6500000001",
"destination":"6500000001",
"encoding":"GSM7",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
},
{
"umid":"f3ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"SmsApi-Demo1/6500000002",
"destination":"6500000002",
"encoding":"GSM7",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
},
{
"umid":"f3ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"SmsApi-Demo1/6500000003",
"destination":"6500000003",
"encoding":"GSM7",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
}
]
}

{
"batchId":"f1ea5276-a824-e711-8146-022a22cc1c71",
"clientBatchId":"Demo#1001",
"acceptedCount":3,
"rejectedCount":1,
"messages":[
{
"umid":"f2ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"Demo#1001/6598760001",
"destination":"6598760001",
"encoding":"GSM7",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
},
{
"umid":"f3ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"id_100001",
"destination":"659876002",
"encoding":"GSM7",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
},
{
"umid":"f3ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"id_100002",
"destination":"33509750003",
"encoding":"UCS2",
"status":{
"code":"QUEUED",
"description":"SMS is accepted and queued for processing"
}
},
{
"umid":"f3ea5276-a824-e711-8146-022a22cc1c71",
"clientMessageId":"id_100003",
"destination":"+1123456789",
"encoding":"GSM7",
"status":{
"code":"REJECTED",
"description":"Invalid MSISDN format (not E.164 international number)"
}
}
]
}

Bad request error response

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}

{
"code":1002,
"message":"Invalid MSISDN format (not E.164 international number)",
"errorId":"b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp":"2018-08-04T09:25:40.9235752+00:00"
}

Request was not authenticated response

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}

{
"code":1200,
"message":"Request was not authenticated properly",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2018-08-02T09:42:38.8988997+00:00"
}

Upgrade Required — client is using an unsupported TLS version

Response Headers

Upgrade

Example: TLS/1.3

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}

{
"code":1014,
"message":"TLS 1.3+ is required for Singapore-bound messages. Detected: TLSv1.2",
"errorId":"b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp":"2018-08-04T09:25:40.9235752+00:00"
}

Internal server error

Schema

codeintegerrequired

Error code

messagestring

Error description

errorIdstring<uuid>required

Unique id of error. You can use it as reference when sending enquiries to 8x8 support

timestampstring<date-time>required

Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}

{
"code":2000,
"message":"Internal server error",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2018-07-02T09:42:38.8988997+00:00"
}

Source: https://developer.8x8.com/connect/reference/send-many-sms · 8x8 CPaaS Developer Docs. Synced for support deflection.

Stephen - 8x8 Technical Support Level 2

June 26, 2026 06:41

0 Comments

Please sign in to leave a comment.

Send SMS batch

URL

Request

Path Parameters

Body

Request structure

About the template object

messages object[]required

template object

Schema

messages object[]

status objectrequired

Schema

Schema

Response Headers

Schema

Schema

0 Comments

Didn't find what you were looking for?