Programmable SMS

MessageBird’s Programmable SMS API enables you to send and receive SMS messages to and from any country across the world through a simple REST API.

API Endpoint

All URLs referenced in MessageBid's Programmable SMS API reference have the following base URL:

API Endpoint

https://rest.messagebird.com/messages

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Available HTTP methods

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

Parameters

Parameter	Description
Authorization	When calling our API, send your access key with the authentication type set as AccessKey (Example: Authorization: AccessKey {accessKey}). Required.
Accept	Set to application/json. Required.

Authentication Example

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

GET Example

$ curl https://rest.messagebird.com/balance?access_key=test_gshuPaZoeEG6ovbc8M79w0QyM

If possible, please use the Authorization header.

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	hash	A hash with extra information. Further explanation in the table below.
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)
scheduledDatetime	datetime	The scheduled date and time of the message in RFC3339 format (Y-m-dTH:i:sP)
createdDatetime	datetime	The date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP)
recipients	hash	The hash 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":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2016-04-29T09:42:26+00:00"
      }
    ]
  }
}

The recipients array

Attribute	Type	Description
totalCount	integer	The total count of recipients.
totalSentCount	integer	The count of recipients that have the message pending (status sent, and buffered).
totalDeliveredCount	integer	The count of recipients where the message is delivered (status delivered).
totalDeliveryFailedCount	integer	The count of recipients where the delivery has failed (status delivery_failed).
items	array	An array of recipient hashes
items[].recipient	integer	The msisdn of the recipient
items[].status	string	The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed
items[].statusDatetime	datetime	The datum time of the last status in RFC3339 format (Y-m-dTH:i:sP)

The typeDetails array

Attribute	Type	Description
udh	string	The UDH to prepend to the message payload. This can be used for sending concatenated SMS. Often required to send binary messages.

Message Object Example (Binary)

{
  "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",
        "statusDatetime":"2016-04-29T09:42:26+00:00"
      },
      {
        "recipient":31612345679,
        "status":"delivered",
        "statusDatetime":"2016-04-29T09:42:26+00:00"
      }
    ]
  }
}

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.

Note: 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 here.

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.

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

Receive and handle inbound SMS

On a virtual mobile number (VMN)

Inbound SMS messages from a Virtual Mobile Number (VMN) are received through a configured callback URL (configurable per VMN). The message attributes are sent through a POST request by default but the method can be configured per VMN.

Attributes

Attribute	Type	Description
id	string	A unique random ID which is created on the MessageBird platform.
recipient	string	The recipient of the message (the VMN).
originator	string	The sender of the message.
body	string	The body of the SMS message.
createdDatetime	datetime	The date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP)

Example Request

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

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to deliver the message again (up to 10 times).

Example Response

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.

Attributes

Attribute	Type	Description
mid	integer	A unique random ID which is created on the MessageBird platform.
shortcode	string	The shortcode that received the message.
keyword	string	The keyword that matched the message.
originator	string	The sender of the message (end user).
operator	integer	The operator of the sender of the message (MCCMNC)
message	string	The body of the SMS message, including the (sub)keyword.
receive_datetime	string	The date and time when the message was received at shortcode in format: YmdHis

Example Request

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

Your platform should respond with a 200 OK HTTP header and a plain text OK as body. When our platform doesn't receive a OK response body, we will try to deliver the message again (up to 10 times).

Example Response

200 OK

View an SMS

You can use MessageBird's SMS API to retrieve information of an existing inbound or outbound SMS message.

You only need to supply the unique message id that was returned upon creation or receiving.

Required parameters

Parameter	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

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

Example Request

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

Response

This will return a message object if the request was successful.

If the request failed, an error object will be returned.

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

List message

To list all inbound and outbound SMS messages sent, you can do a GET request on the /messages endpoint.

Messages are identified by a unique random ID. You can use this ID to check the status of the SMS message through the provided endpoint.

Filters

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

Filters

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

Filter	Type	Description
originator	string	Display messages by the specified originator.
recipient	string	Display messages for the specified recipient.
direction	string	Display either mt (sent) or mo (received) messages.
limit	int	Limit the amount of messages listed.
offset	int	Skip first n results.
searchterm	string	Display messages including the specified searchterm.
type	string	Display messages of type sms, binary, or flash
contact_id	int	Display messages by contact_id. See Contacts API for more info.
status	string	Display messages with status scheduled, sent, buffered, delivered, expired, or delivery_failed.
from	datetime	Display messages starting from the specified date in RFC3339 format (Y-m-dTH:i:sP).
until	datetime	Display messages until the specified date in RFC3339 format (Y-m-dTH:i:sP).

List scheduled messages

You can also list all scheduled SMS messages using the endpoint on the right.

URI

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

Handle a status report

Status reports are requests that are sent to your platform through a GET request. 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 and accounts that have configured their status report url.

Example request

GET http://your-own.url/script?id=e8077d803532c0b5937c639b60216938&reference=YouReference123&recipient=31612345678&status=delivered&statusDatetime=2016-05-03T08%3A58%3A10%2B00%3A00

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.
reference	string	A client reference.
recipient	string	The recipient where this status report applies to.
status	string	The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, expired, and delivery_failed.
statusDatetime	datetime	The datum time of this status in RFC3339 format (Y-m-dTH:i:sP).
statusErrorCode	integer	Extra error code that describes the failure in more detail (optional, only given if available).

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to deliver the receipt again (up to 10 times).

Example response

200 OK

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 TLS1.0, or better connection.

Here is an overview of the available servers:

Hostname	Port	TLS port
smpp01.messagebird.com	2775	2776
smpp02.messagebird.com	2775	2776
smpp03.messagebird.com	2775	2776

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:

PDU name	command_id
bind_receiver	0x00000001
bind_transceiver	0x00000009
bind_transmitter	0x00000002
deliver_sm_resp	0x80000005
enquire_link	0x00000015
generic_nack	0x80000000
submit_sm	0x00000004
unbind	0x00000006
unbind_resp	0x80000006

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.

Field name	Description
system_id	The username
password	The password
system_type	IGNORED
interface_version	The SMPP protocol version you want to talk
addr_ton	IGNORED
addr_npi	IGNORED
address_range	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.


service_type	IGNORED
source_addr_ton	Type of number for source_addr
source_addr_npi	Numbering plan indicator for source_addr
source_addr	Address of message origin
dest_addr_ton	Type of number for destination_addr
dest_addr_npi	Numbering plan indicator for destination_addr
destination_addr	Address of message destination
esm_class	Message mode and type
protocol_id	IGNORED
priority_flag	IGNORED
schedule_delivery_time	IGNORED
validity_period	The validity period of this message
registered_delivery	The type if DLRs you want to receive
replace_if_present_flag	IGNORED
data_coding	The coding of the short_message field
sm_default_msg_id	IGNORED
sm_length	The length of short_message field
short_message	The contents of the MT

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.

Value	Encoding
0	GSM7
1	ASCII
2	8BIT
3	ISO-8859-15 West European languages (Latin-9)
6	ISO-8859-5 Latin/Cyrillic
7	ISO-8859-8 Latin/Hebrew
8	UTF-16BE (UCS2)

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.

Field	Name Description
service_type	IGNORED
source_addr_ton	Type of number for source_addr
source_addr_npi	Numbering plan indicator for source_addr
source_addr	Address of message origin
dest_addr_ton	Type of number for destination_addr
dest_addr_npi	Numbering plan indicator for destination_addr
destination_addr	Address of message destination
esm_class	Message mode and type
protocol_id	IGNORED
priority_flag	IGNORED
schedule_delivery_time	IGNORED
validity_period	The validity period of this message
registered_delivery	IGNORED
replace_if_present_flag	IGNORED
data_coding	The coding of the short_message field
sm_default_msg_id	IGNORED
sm_length	The length of short_message field
short_message	The contents of the MT

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:

Name	Tag ID	Description
receipted_message_id	0x001E	The message_id referencing the same message_id that was returned in the submit_sm_resp of the MT (SMPP v5.0 spec: 4.8.4.47)
message_state	0x0427	The final message state for a delivery receipt (SMPP v5.0 spec: 4.7.15 and 4.8.4.37)
network_error_code	0x0423	The actual network error code (SMPP v5.0 spec: 4.8.4.42)
network_mccmnc *	0x1560	Operator MCCMNC of recipient MSISDN of related SMS; given when available.

TLVs marked with * are custom MessageBird SMPP tags.

short_message

In the case of MO messages, the short_message field will contain the contents of the message that was sent. In the case of DLR messages, it will contain report information in the following format:

The id parameter references the message_id that was returned in the submit_sm_resp of your submit_sm and it has the same value as the receipted_message_id TLV.

The state parameter references the message_state TLV, although the message_state contains a number pointing to a state where the state parameter in the short_message is described by a word.

The err parameter references error codes in section 3.3.4 and is the same as the network_error_code TLV.

Examples

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:

Was this page helpful?

Yes

cURL

PHP

Node

Java

Ruby

Python

Cookie Settings