API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIContacts API (v2)Integrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

SMS Batch API

MessageBird’s SMS Batch API allows you to send and receive SMS messages to and from any country in the world through a REST API. Each message is identified by a unique random ID so that users can always check the status of a message using the given endpoint.

The SMS Batch API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

Compared to SMS API operating with a single message object, SMS Batch API allows to send different messages to multiple recipients within a single request.


API Endpoint

All URLs referenced in MessageBird's SMS API documentation have the base URL in the code snippet on the right side:

API Endpoint

https://rest.messagebird.com/messages/batches

Available HTTP methods

The MessageBird API uses HTTP verb to understand when you want to create ('POST') an array of message objects. When your web application cannot do a POST request, we provide the ability to set the method through the query parameter _method.

The Authorisation and specific parameters are required for a request. Check with additional information here.

Available HTTP methods

POST /messages/batches
There are other endpoints available to manage created message objects. See SMS API documentation for details.

Send outbound SMS

MessageBird's Programmable SMS API enables you to programmatically send SMS messages from your web application.

First, you need to create an array of new message objects. MessageBird returns the created message objects with each request. A maximum of 50 recipients can be entered per message object.

Every message object will be treated by API as an individual one, which allows to view and manage created messages separately. See SMS API documentation for details.

Send your first SMS messages with this example request.

Required parameters
attributetypedescriptionrequired
messagesarrayAn array of SMS messages object, the maximum size is 100 elements. See the structure and available parameters for a message object here.Yes

Definition

POST https://rest.messagebird.com/messages/batches

Example Request

curl -X POST https://rest.messagebird.com/messages/batches \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-H 'Content-Type: application/json' \
-d '
{
"messages": [
{
"recipients": ["31612345678"],
"originator": "YourName",
"body": "This is a test message"
},
{
"recipients": ["31612345678"],
"originator": "YourName",
"body": "This is another test message"
}
]
}'
Notification icon

Do note that values are not automatically urlencoded with the above example. Use --data-urlencode if you want to urlencode the values.

Example Response

[
{
"id":"e8077d803532c0b5937c639b60216938",
"href":"https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938",
"direction":"mt",
"type":"sms",
"originator":"YourName",
"body":"This is a test message",
"reference":null,
"validity":null,
"gateway":null,
"typeDetails":{},
"datacoding":"plain",
"mclass":1,
"scheduledDatetime":null,
"createdDatetime":"2016-05-03T14:26:57+00:00",
"recipients":{
"totalCount":1,
"totalSentCount":1,
"totalDeliveredCount":0,
"totalDeliveryFailedCount":0,
"items":[
{
"recipient":31612345678,
"status":"sent",
"statusDatetime":"2016-05-03T14:26:57+00:00"
}
]
}
},
{
"id":"f4486adbc0a44dc1b9cd558f7bbc0093",
"href":"https://rest.messagebird.com/messages/f4486adbc0a44dc1b9cd558f7bbc0093",
"direction":"mt",
"type":"sms",
"originator":"YourName",
"body":"This is another test message",
"reference":null,
"validity":null,
"gateway":null,
"typeDetails":{},
"datacoding":"plain",
"mclass":1,
"scheduledDatetime":null,
"createdDatetime":"2016-05-03T14:26:57+00:00",
"recipients":{
"totalCount":1,
"totalSentCount":1,
"totalDeliveredCount":0,
"totalDeliveryFailedCount":0,
"items":[
{
"recipient":31612345678,
"status":"sent",
"statusDatetime":"2016-05-03T14:26:57+00:00"
}
]
}
}
]

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings