MessageBird’s SMS 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 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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bird-sms-messaging-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: MessageBird SMS SMS Messaging API
version: 1.0.0
description: 'MessageBird’s SMS 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 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.'
servers:
- url: https://rest.messagebird.com/messages
security:
- AccessKey: []
tags:
- name: SMS Messaging
description: 'MessageBird’s SMS 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 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.'
paths:
/messages:
post:
tags:
- SMS Messaging
summary: Send message
description: 'MessageBird''s Programmable SMS API enables you to programmatically send SMS messages from your web application.
First, you need to create a new message object. MessageBird returns the created message object with each request. A maximum of 50 recipients can be entered per request.'
requestBody:
content:
application/json:
schema:
type: object
required:
- originator
- body
- recipients
properties:
originator:
type: string
example: MessageBird
description: The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters.
body:
type: string
example: '+380999999999'
description: The body of the SMS message.
recipients:
type: array
items:
type: string
example: '["380999999999", "380999999999"]'
description: An array of recipients msisdns.
groupIds:
type: array
items:
type: string
description: An array of group id's. If provided recipients can be omitted.
type:
type: string
enum:
- sms
- binary
- flash
description: 'The type of message. Values can be: sms, binary, or flash.'
reference:
type: string
description: A client reference. Is required for a status report callback to be sent.
reportUrl:
type: string
example: https://example.ua/report-here
description: The status report URL to be used on a per-message basis. This value overrides the standard status report url configured on the customer account.
validity:
type: integer
example: 60
description: The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway:
type: integer
example: 11
description: The SMS route that is used to send the message.
typeDetails:
type: object
example: '{"udh":"050003340201"}'
description: A hashmap with extra information.
datacoding:
type: string
example: unicode
description: The datacoding used, defaults to plain (GSM 03.38 characters only), or it can be set to unicode (contains non-GSM 03.38 characters) or set to auto and we will set unicode or plain depending on the body content.
mclass:
type: integer
example: 1
description: Indicated the message type. 1 is a normal message, 0 is a flash message. (0-3 are valid values).
shortenUrls:
type: boolean
example: false
description: \*beta\* Shorten all the URLs present in the message body.
scheduledDatetime:
type: integer
example: '2022-05-20T12:50:28Z'
description: The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP), when you want to schedule a message in the future. Don't set this value when message needs to be send directly.
example:
recipients: '+380999999999'
originator: MessageBird
body: Lorem ipsum dolor sit amet.
type: binary
reference: test
reportUrl: https://example.com/callback
validity: 30
gateway: 11
typeDetails:
udh: '050003340201'
datacoding: unicode
mclass: 1
shortenUrls: true
scheduledDatetime: null
parameters:
- name: Content-Type
required: true
in: header
schema:
type: string
example: application/json
- name: Authorization
required: true
in: header
schema:
type: string
example: AccessKey wNmtVQTcLO4uf22uJxjvzwJ223
responses:
'201':
description: SMS successfully created
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:16:51 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '602'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
examples:
example-0:
summary: 201 Created
value:
id: f28bbe526fc14974b3e7e663a6139b53
href: https://rest.messagebird.com/messages/f28bbe526fc14974b3e7e663a6139b53
direction: mt
type: sms
originator: MessageBird
body: Lorem ipsum dolor sit amet.
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-07-01T16:16:51+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 0
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
status: sent
statusDatetime: '2022-07-01T16:16:51+00:00'
messagePartCount: 1
example-1:
summary: 201 Created (binary)
value:
id: 1217667de49b4847a7bfeca00ae9ffe3
href: https://rest.messagebird.com/messages/1217667de49b4847a7bfeca00ae9ffe3
direction: mt
type: binary
originator: MessageBird
body: Lorem ipsum dolor sit amet.
reference: test
validity: 30
gateway: 10
typeDetails:
udh: '050003340201'
datacoding: unicode
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-07-01T16:29:24+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 0
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
status: sent
statusDatetime: '2022-07-01T16:29:24+00:00'
messagePartCount: 1
'401':
description: Unauthorized
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 15:50:06 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '107'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Www-Authenticate:
schema:
type: string
example: Basic realm="REST API authentication"
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
example:
errors:
- code: 2
description: Request not allowed (incorrect access_key)
parameter: access_key
'422':
description: Unprocessable Entity
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:15:29 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '187'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
example:
errors:
- code: 9
description: 'no (correct) recipients found. Note: during your test period you can only send messages to your own number (+380999999999).'
parameter: recipient
get:
tags:
- SMS Messaging
summary: List messages
parameters:
- name: originator
in: query
schema:
type: string
description: Display messages by the specified originator.
example: ValTesting
- name: recipient
in: query
schema:
type: integer
description: Display messages for the specified recipient.
example: '380999999999'
- name: direction
in: query
schema:
type: string
description: Display either mt (sent) or mo (received) messages.
example: mt
- name: limit
in: query
schema:
type: integer
description: Limit the amount of messages listed.
example: '50'
- name: offset
in: query
schema:
type: integer
description: Skip first n results.
example: '0'
- name: searchterm
in: query
schema:
type: string
description: Display messages including the specified searchterm in recipient and originator
example: val
- name: type
in: query
schema:
type: string
description: Display messages of type sms, binary, or flash
example: sms
- name: contact_id
in: query
schema:
type: string
description: Display messages by contact_id. See Contacts API for more info.
example: 61afc0531573b08ddbe36e1c85602827
- name: status
in: query
schema:
type: string
description: Display messages with status scheduled, sent, buffered, delivered, expired, or delivery_failed.
example: buffered
- name: from
in: query
schema:
type: string
description: Display messages starting from the specified date in RFC3339 format (Y-m-d\TH:i:sP).
example: '2022-05-20T12:50:28Z'
- name: until
in: query
schema:
type: string
description: Display messages until the specified date in RFC3339 format (Y-m-d\TH:i:sP).
example: '2022-06-29T12:50:28Z'
responses:
'200':
description: OK
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:30:02 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Vary:
schema:
type: string
example: Accept-Encoding
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
Content-Encoding:
schema:
type: string
example: gzip
Transfer-Encoding:
schema:
type: string
example: chunked
content:
application/json:
schema:
type: object
examples:
example-0:
summary: 200 OK
value:
offset: 0
limit: 20
count: 9
totalCount: 9
links:
first: https://rest.messagebird.com/messages/?offset=0
previous: null
next: null
last: https://rest.messagebird.com/messages/?offset=0
items:
- id: cea5a8d4a82f4b7bb4a053296d5a9ba1
href: https://rest.messagebird.com/messages/cea5a8d4a82f4b7bb4a053296d5a9ba1
direction: mt
type: sms
originator: ValTesting
body: 'Current time: 2022-06-23 12:41:23.828134 +0300 EEST m=+0.001717501'
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-23T09:41:24+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-23T09:41:31+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 66
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 281f98b1732b4ee29f68f930b80b2f60
href: https://rest.messagebird.com/messages/281f98b1732b4ee29f68f930b80b2f60
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-23T06:54:41+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-23T06:54:47+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 78065add7b144d7cb6909576cbfc5b5e
href: https://rest.messagebird.com/messages/78065add7b144d7cb6909576cbfc5b5e
direction: mt
type: sms
originator: ValTesting
body: qwerty3
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T22:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T22:30:05+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: c81801d34d0b4c29bcf304de906feae1
href: https://rest.messagebird.com/messages/c81801d34d0b4c29bcf304de906feae1
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T14:04:22+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T14:04:29+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: e876126d16af4fdfb368c538f7a4d660
href: https://rest.messagebird.com/messages/e876126d16af4fdfb368c538f7a4d660
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T14:03:56+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T14:04:04+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: cfe8234a793f4f90833fe6d01731e6fa
href: https://rest.messagebird.com/messages/cfe8234a793f4f90833fe6d01731e6fa
direction: mt
type: sms
originator: ValTesting
body: qwerty2
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T01:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T01:30:14+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 0f484ecbf51942b5b7f4df62891ea247
href: https://rest.messagebird.com/messages/0f484ecbf51942b5b7f4df62891ea247
direction: mt
type: sms
originator: ValTesting
body: qwerty2
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T01:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T01:30:04+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 0aa1c53c34d34bda84cc4bc454d95028
href: https://rest.messagebird.com/messages/0aa1c53c34d34bda84cc4bc454d95028
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-21T16:03:00+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-21T16:03:07+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: cb96c6336c92482797554428a899a225
href: https://rest.messagebird.com/messages/cb96c6336c92482797554428a899a225
direction: mt
type: sms
originator: Test
body: This is a test message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-21T15:28:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-21T15:29:05+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 22
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '2
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bird/refs/heads/main/openapi/bird-sms-messaging-api-openapi.yml