SMS API

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.

https://rest.messagebird.com/messages

POST /messages
GET /messages
GET /messages/{messageId}
DELETE /messages/{messageId}

curl -X GET https://rest.messagebird.com/balance \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

curl -X GET https://rest.messagebird.com/balance?access_key=test_gshuPaZoeEG6ovbc8M79w0QyM

The message object

This is an object representing an SMS message at MessageBird.com.

Attributes

Attribute	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
href	string	The URL of the created object.
direction	string	Tells you if the message is sent or received. mt: mobile terminated (sent to mobile) mo: mobile originated (received from mobile)
type	string	The type of message. Values can be: sms, binary, or flash
originator	string	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. You can set a default originator in your account or use inbox to use the Sticky VMN feature.
body	string	The body of the SMS message.
reference	string	A client reference.
reportUrl	string	The status report URL to be used on a per-message basis. reference is required for a status report webhook to be sent.
validity	integer	The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway	integer	The SMS route that is used to send the message.
typeDetails	hashmap	A hashmap with extra information. Further explanation in the table below.
datacoding	string	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. Note: Using unicode will limit the maximum number of characters to 70 instead of 160. If message character size exceeds the limit, messages will be concatenated, resulting in separately billed messages. See this article for more information.
mclass	integer	Indicated the message type. 1 is a normal message, 0 is a flash message. (0-3 are valid values)
scheduledDatetime	datetime	The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetime	datetime	The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
recipients	hashmap	The hashmap with recipient information. Further explanation in the table below.

Message Object Example (SMS)

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938",
  "direction":"mt",
  "type":"sms",
  "originator":"MessageBird",
  "body":"The message to be sent",
  "reference":"the-client-reference",
  "validity":null,
  "gateway":240,
  "typeDetails":{

  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2016-04-29T09:42:26+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":1,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusReason":"successfully delivered",
        "statusErrorCode":null,
        "statusDatetime":"2016-04-29T09:42:26+00:00",
        "recipientCountry":"Netherlands",
        "recipientCountryPrefix":31,
        "recipientOperator":"KPN",
        "mccmnc":"20408",
        "mcc":"204",
        "mnc":"08",
        "messageLength":22,
        "messagePartCount":1,
        "price":{
            "amount":0.075,
            "currency":"EUR"
        }
      }
    ]
  }
}

{
  "id":"98154fa03532c2c3fc7b341b46487018",
  "href":"https://rest.messagebird.com/messages/98154fa03532c2c3fc7b341b46487018",
  "direction":"mt",
  "type":"binary",
  "originator":"MessageBird",
  "body":"546865206d65737361676520746f2062652073656e74",
  "reference":null,
  "validity":null,
  "gateway":240,
  "typeDetails":{
    "udh":"050003340201"
  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2016-04-29T09:42:26+00:00",
  "recipients":{
    "totalCount":2,
    "totalSentCount":1,
    "totalDeliveredCount":1,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusReason":"successfully delivered",
        "statusErrorCode":null,
        "statusDatetime":"2016-04-29T09:42:26+00:00",
        "recipientCountry":"Netherlands",
        "recipientCountryPrefix":31,
        "recipientOperator":"KPN",
        "mccmnc":"20408",
        "mcc":"204",
        "mnc":"08",
        "messageLength":44,
        "messagePartCount":1,
        "price":{
            "amount":0.075,
            "currency":"EUR"
        }
      },
      {
        "recipient":31612345679,
        "status":"delivery_failed",
        "statusReason":"unknown subscriber",
        "statusErrorCode":1,
        "statusDatetime":"2016-04-29T09:42:26+00:00",
        "recipientCountry":"Netherlands",
        "recipientCountryPrefix":31,
        "recipientOperator":"",
        "mccmnc":null,
        "mcc":null,
        "mnc":null,
        "messageLength":44,
        "messagePartCount":1,
        "price":{
            "amount":null,
            "currency":null
        }
      }
    ]
  }
}

---

Send outbound SMS

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.

Send your first SMS message with this example request.

Sticky VMN

Sticky VMN's ensure that the same Sender phone number is selected each time a specific recipient receives an SMS from your web application.

Sticky VMN's are only available in the US, Canada, Netherlands and United Kingdom. As there are no capacity limits in other countries, you won't need multiple VMNs. Learn more about specific country restrictions.

Whether you are using a pool of dedicated VMNs or MessageBird's shared VMN pool, it is best practice to ensure that your recipients always receive your SMS messages from the same VMN as a sender.

MessageBird's Sticky-VMN-as-a-Sender service makes this configuration possible. Simply use inbox as the originator when sending SMS messages to the MessageBird SMS API.

This will trigger our system to select a random VMN (dedicated or shared - depending on what’s available) for the first SMS message and ensure that the selected VMN be reused for all following SMS messages.

Required parameters

attribute	type	description
originator	string	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	string	The body of the SMS message.
recipients	array	An array of recipients msisdns.

Optional parameters

attribute	type	description
groupIds	array	An array of group id's. If provided recipients can be omitted.
type	string	The type of message. Values can be: sms, binary, or flash.
reference	string	A client reference. Is required for a status report callback to be sent
reportUrl	string	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	integer	The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway	integer	The SMS route that is used to send the message.
typeDetails	hashmap	A hashmap with extra information. Is only used when a binary message is sent.
datacoding	string	The datacoding used can be plain (GSM 03.38 characters only), unicode (contains non-GSM 03.38 characters) or auto, we will then set unicode or plain depending on the body content. Note: Using unicode will limit the maximum number of characters to 70 instead of 160. If message character size exceeds the limit, messages will be concatenated, resulting in separately billed messages. See this article for more information.
mclass	integer	Indicated the message type. 1 is a normal message, 0 is a flash message. (0-3 are valid values)
shortenUrls	boolean	beta Shorten all the URLs present in the message body.
scheduledDatetime	datetime	The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetime	datetime	The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)

Definition

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

Example Request

curl -X POST https://rest.messagebird.com/messages \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d "recipients=31612345678" \
  -d "originator=YourName" \
  -d "shortcode=1008" \
  -d "body=This is a test message"

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"
      }
    ]
  }
}

Handle a status report

Status reports are HTTP GET requests that are sent to your platform. The requests hold information about the status of a message that you have sent through our API. Status reports are only provided for SMS messages that have a reference defined when sending the message, and a status report URL is set: as reportUrl when sending the message, or configured in their account as status report url.

Attributes

Note: New attributes can be added to the status report HTTP callbacks. Consider this for the validation of received from MessageBird status reports. We will never remove attributes.

GET http://your-own.url/script?id=efa6405d518d4c0c88cce11f7db775fb&reference=the-customers-reference&recipient=31612345678&status=delivered&statusReason=successfully%20delivered&statusDatetime=2017-09-01T10:00:05+00:00&datacoding=plain&mccmnc=20409&messageLength=44&messagePartCount=1&ported=0&price[amount]=0.75&price[currency]=EUR

200 OK

Receive and handle inbound SMS

On a virtual mobile number (VMN)

Inbound SMS messages from a Virtual Mobile Number are received through a callback URL that can be configured manually by using the Forward to URL step in Flow Builder, or by contacting our support team. The message attributes are sent through a POST request by default but the method can be configured per VMN.

Attributes

GET http://your-own.url/script?id=e8077d803532c0b5937c639b60216938&recipient=31642500190&originator=31612345678&body=This+is+an+incoming+message&createdDatetime=2016-05-03T14%3A26%3A57%2B00%3A00

200 OK

On a shortcode

Inbound SMS messages from an end user to - a (sub)keyword at - a shortcode are received through a configured callback URL (configurable per keyword/shortcode). The message attributes are sent through a GET request by default but the method can be configured per keyword. Please contact our support team to set this up for you.

Attributes

GET http://your-own.url/script?mid=123456789&shortcode=1008&keyword=MESSAGEBIRD&originator=31612345678&operator=20401&message=This+is+an+incoming+message&receive_datetime=20160503142657

200 OK

GET https://rest.messagebird.com/messages/{messageId}

curl -X GET https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

{
  "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",
        "statusReason":"successfully delivered",
        "statusErrorCode":null,
        "statusDatetime":"2016-05-03T14:26:57+00:00",
        "recipientCountry":"Netherlands",
        "recipientCountryPrefix":31,
        "recipientOperator":"KPN",
        "mccmnc":"20408",
        "mcc":"204",
        "mnc":"08",
        "messageLength":22,
        "messagePartCount":1,
        "price":{
            "amount":0.75,
            "currency":"EUR"
        }
      }
    ]
  }
}

https://rest.messagebird.com/messages?status=scheduled

curl -X GET https://rest.messagebird.com/messages \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

{
    "offset": 0,
    "limit": 20,
    "count": 4,
    "totalCount": 4,
    "links": {
        "first": "https://rest.messagebird.com/messages/?offset=0",
        "previous": null,
        "next": null,
        "last": "https://rest.messagebird.com/messages/?offset=0"
    },
    "items": [
        {
            "id": "436d780b854749b4beca51623d9e2674",
            "href": "https://rest.messagebird.com/messages/436d780b854749b4beca51623d9e2674",
            "direction": "mt",
            "type": "sms",
            "originator": "YourName",
            "body": "This is a test message",
            "reference": null,
            "validity": null,
            "gateway": 10,
            "typeDetails": {},
            "datacoding": "plain",
            "mclass": 1,
            "scheduledDatetime": null,
            "createdDatetime": "2020-02-04T19:01:12+00:00",
            "recipients": {
                "totalCount": 1,
                "totalSentCount": 1,
                "totalDeliveredCount": 1,
                "totalDeliveryFailedCount": 0,
                "items": [
                    {
                        "recipient": 31612345678,
                        "originator": null,
                        "status": "delivered",
                        "statusReason": "successfully delivered",
                        "statusErrorCode": null,
                        "statusDatetime": "2020-02-04T19:01:12+00:00",
                        "recipientCountry": "Netherlands",
                        "recipientCountryPrefix": 31,
                        "recipientOperator": "KPN",
                        "mccmnc": "20408",
                        "mcc": "204",
                        "mnc": "08",
                        "messageLength": 22,
                        "messagePartCount": 1,
                        "price": {
                            "amount": 0.075,
                            "currency": "EUR"
                        }
                    }
                ]
            }
        }
    ]
}

Filters

Besides listing all SMS messages, the MessageBird SMS API also provides some filters that can be used as query parameters:

https://rest.messagebird.com/messages?status=scheduled

curl -X GET https://rest.messagebird.com/messages?status=scheduled \
     -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

{
  "offset":0,
  "limit":20,
  "count":1,
  "totalCount":1,
  "links":{
     "first":"https://rest.messagebird.com/messages/?offset=0&status=scheduled",
     "previous":null,
     "next":null,
     "last":"https://rest.messagebird.com/messages/?offset=0&status=scheduled"
  },
  "items":[
     {
        "id":"",
        "href":"https://rest.messagebird.com/messages/",
        "direction":"mt",
        "type":"sms",
        "originator":"Test",
        "body":"test mesage",
        "reference":null,
        "validity":null,
        "gateway":10,
        "typeDetails":{},
        "datacoding":"plain",
        "mclass":1,
        "scheduledDatetime":"2020-04-04T13:14:00+00:00",
        "createdDatetime":"2020-03-04T13:06:20+00:00",
        "recipients":{
           "totalCount":0,
           "totalSentCount":0,
           "totalDeliveredCount":0,
           "totalDeliveryFailedCount":0,
           "items":[]
        }
     }
  ]
}

SMS Statuses

MessageBird provides three levels of information describing the status of an SMS: Status, Status Reason, and Error Code. These levels are complementary and should be analyzed together to get the full picture of an SMS delivery.

Via HTTP

The Status, Status Reason and Error Code are reported back as respectively status, statusReason and statusErrorCode variables in the HTTP status report callback. The Error Code is only given when the data is available.

Via SMPP

When connected via SMPP, the Error Code is given back as value of the network_error_code TLV and in the err parameter in a DLR’s short_message value. It contains the code that references a specific error.

SMS Status Information Hierarchy

SMS Error Codes are grouped in Status Reasons, that in turn provide additional details to an SMS Status. To read more about the relationship between Statuses, Status Reasons, and Error Codes you can check our support article. The error codes descriptions can be found in the table below.

• sent: The message has been sent, and it has left the MessageBird platform (this is a temporary status).
  • pending DLR: The message has been sent to a downstream mobile operator and provider and we are waiting for Delivery Report to be returned.
• delivered: The message has been delivered to the intended receiver.
  • successfully delivered
• buffered: The message has been queued pending to be delivered. This could be as part of a retry scheme for temporary unavailable (i.e. Unreachable) receiver.
  • pending DLR: The message has been sent to a downstream mobile operator and provider and we are waiting for Delivery Report to be returned.
• expired: The message couldn't be delivered before the expiration of its validity period. MessageBird has a retry policy designed to maximize the chance of successfully delivery, but retries will stop once the validity period you've set expires.
  • unavailable subscriber: The receiver wasn't available due a temporary issue (example it is out of coverage),the retry pattern couldn't complete a successfully delivered it before the expiration of the validity period.
  • DLR not received: The SMS was sent to a mobile operator or downstream provider however no DLR has been returned before the end of the message validity period. This usually indicate the receiving network has a longer retry pattern then the validity period or it is experiencing an issue processing DLR.
  • expired: The SMS was expired before we were able to send the message to a mobile operator or downstream provider.
• delivery_failed: The message couldn't be delivered and a negative DLR has been received. More detail can be found in the reason, or when present in the error code.
  • unknown subscriber: The receiver number is not associated with an active line.
    • 1: EC_UNKNOWN_SUBSCRIBER
    • 2: EC_UNKNOWN_BASE_STATION
    • 3: EC_UNKOWN_MSC
    • 5: EC_UNIDENTIFIED_SUBSCRIBER
    • 9: EC_ILLEGAL_SUBSCRIBER
  • insufficient balance: The cost of the SMS is higher than the remaining balance available on your account.
  • generic delivery failure: No detailed information has been received by the downstream supplier and no additional information is available about the reason of the failure.
  • unavailable subscriber: The receiver number the SMS is temporarily unavailable, the number is valid and shall be kept in your database however the retry.
    • 8: EC_ROAMING_NOT_ALLOWED
    • 10: EC_BEARERSERVICE_NOT_PROVISIONED
    • 11: EC_TELESERVICE_NOT_PROVISIONED
    • 12: EC_CALL_BARRED
    • 26: EC_SUBSEQUENT_HANDOVER_FAILURE
    • 31: EC_SUBSCRIBER_BUSY_FOR_MT_SMS
    • 27: EC_ABSENT_SUBSCRIBER
    • 28: EC_ABSENT_SUBSCRIBER_NO_PAGE
    • 29: EC_ABSENT_SUBSCRIBER_IMSI_DETACHED
    • 33: EC_MESSAGE_WAITING_LIST_FULL
  • received network error: the receiver's network is experiencing some issue, those are temporary preventing SMS delivery however the receiver number used is both valid and correct.
    • 7: EC_UNKNOWN_EQUIPMENT
    • 12: EC_ILLEGAL_EQUIPMENT
    • 21: EC_FACILITY_NOT_SUPPORTED
    • 30: EC_CONTROLLING_MSC_FAILURE
    • 34: EC_SYSTEM_FAILURE
    • 35: EC_DATA_MISSING
    • 36: EC_UNEXPECTED_DATA_VALUE
    • 39: EC_NO_ROAMING_NUMBER_AVAILABLE
    • 40: EC_MEMORY_CAPACITY_EXCEEDED
    • 71: EC_UNKNOWN_ALPHABET
  • opted out: The receiver revoked his/her consent to receive further SMS from the customer/originating number.
    • 103: EC_SUBSCRIBER_OPTEDOUT
  • carrier rejected: The receiver's carrier or mobile operator is blocking the SMS, this is most likely caused by the lack of a mandatory registration for the SMS originator or its content.
    • 104: EC_SENDER_UNREGISTERED
    • 105: EC_CONTENT_UNREGISTERED
  • capacity limit reached: The receiver's carrier or mobile operator is blocking the SMS due to limitation of SMS per second per day (e.g. as part of USA's campaign throttling regulation), or on the time of the day you are authorised to send SMS (e.g. as part of India's Do-Not-Disturb policy). Applicable for countries that require registered campaigns.
    • 106: EC_CAMPAIGN_VOLUME_EXCEEDED
    • 107: EC_CAMPAIGN_THROUGHPUT_EXCEEDED
• scheduled: The message is scheduled by the customer to be sent at a later time (API only).

Some Statuses, Reasons and Error Codes are related to country restrictions. You can find more information about countries restrictions at our help pages.

SMS Error Codes

SMPP

The SMPP documentation describes everything you need to know about the MessageBird SMPP server. Keep in mind that it's important for you to already have a basic understanding of the SMPP protocol and to know how to set up your own SMPP client software.

The SMPP servers

Server list

MessageBird has multiple SMPP servers for you to connect to. Each SMPP server offers the ability to connect to it via the regular (plaintext) method, a TLS v1.2, or better connection.

Here is an overview of the available servers:

Username and password

Your account manager at MessageBird will give you a username (system_id) and password. If you haven’t received them yet or you still need to make the request, simply send us an email to support@messagebird.com; we'll be happy to help you out.

Bindings and throughput

Whenever an SMPP account has been set up for you, you’ll receive the maximum amount of binds and throughput. In most cases, these values will be something like 3 binds and 50 messages per second.

It might be interesting to note that these values are enforced on a per-server basis. That means that given the above example, you can set up 9 binds in total with a throughput of 150 messages per second when you connect to all servers.

Keep in mind that for maintenance purposes we only guarantee either that one server is up at any given time, so we advise you to connect to all of them.

Bindings and relaying

MessageBird’s message relaying system is connection and server agnostic, so when you send an MT via a submit_sm PDU on connection A, you might receive the matching DLR in the form of a deliver_sm on connection B if both connections are bound with the same username.

This is even true for connections made to different servers, so this scenario is also possible if connection A is made to the smpp01 server and connection B to the smpp02 server.

Security

If you connect to either server via a TLS connection, make sure to select TCP port 2776. Also be aware that the servers only accept an SSLv3 handshake method, so the old (legacy) SSLv2 handshake won’t work, even though your crypto stick plans to negotiate to use TLS1.0 or better.

Supported PDUs

The MessageBird SMPP servers support the following list of PDU types:

bind PDU

An SMPP bind_receiver, bind_transceiver, or bind_transmitter PDU request has a fixed set of fields. Most fields are irrelevant to us; actually, we only read the system_id, password, and interface_version fields and the rest is ignored.

interface_version

The MessageBird SMPP server supports SMPP protocol version 3.3, 3.4, and 5.0. Keep in mind that if you set your SMPP client to talk version 3.3 you are missing out on some features, most notably TLV information in the deliver_sm PDUs you receive.

submit_sm PDU

You can use the submit_sm PDU to send us your MT messages. Like a bind request, the submit_sm PDU request also has a couple of fields that are unused by our platform and can safely be ignored.

data_coding

The values for the data_coding field are not solidly declared in the SMPP spec, so each SMPP server is more or less required to give its own definition. Below is a list of data codings that we accept as input. Keep in mind that only the values of 0, 2 and 8 are used as-is, other values will be converted to the most appropriate encoding out of 0, 2 and 8 to ensure acceptance of your messages by the operators.

deliver_sm PDU

MOs and DLRs will be sent to you via a deliver_sm PDU. The fields are exactly the same as a submit_sm PDU, but there will be differences in which fields you are free to ignore, and which you are not.

data_coding

The values here are the same as in section submit_sm.

tlvs

DLR messages which are sent to you as a deliver_sm may contain TLVs that you might be interested in. The following TLVs are supported as of the writing of this document:

TLVs marked with * are custom MessageBird SMPP tags.

short_message

id:xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx sub:001 dlvrd:NNN submit date:YYMMDDHHMMSS done date:YYMMDDHHMMSS stat:STATUS err:NNN text:

id:fecf8e26-eb1d-46e7-5bdf-e509c058f7b7 sub:001 dlvrd:001 submit date:141029064451 done date:141029064502 stat:DELIVRD err:000 text: