MessageBird Logo
Mobile menu

This API is deprecated. Although we continue support for old APIs for existing clients, we strongly encourage new clients to use our newer and better REST API at no additional cost.



The APIs of MessageBird are easy to integrate into your software. We have examples for the programming languages PHP, Java and Python. Do you need information about other programming languages? Feel free to contact us so you can discuss this with our technical staff.

Offer text messages via HTTP-API

For many companies, this is the most popular method of joining our text message gateway. For our HTTP-API, we have examples or classes ready for PHP, Java and Python, among others. We also have code examples in ASP, C#, VB.NET, VBA, Perl and Ruby.

Learn more ⇢

Send SMS via our HTTP API works in just one line.

curl -X GET "https://api.messagebird.com/api/sms?username=[username]&password=[password]&
        destination=[destination(s)]&body=[message]&sender=[sender]"

Documentation

Click here to download the SMS HTTP-API documentation.

Pre-built libraries

Examples

<?php
// First download the PHP class from Github (https://github.com/mobiletulip/messagebird-sms-api-php/archive/master.zip)
require_once 'lib/class.MessageBird.php';

// Set the Messagebird username and password, and create an instance of the MessageBird class
$sms = new MessageBird( 'username', 'password' );

// Set the sender: could be a number (16 numbers) or letters (11 characters)
$sms->setSender ( 'YourSender' );

// Add the destination mobile number.
// This method can be called several times to add more than one recipient for the same message
$sms->addDestination ( '31600000000' );

// Set a reference, optional
$sms->setReference ( '123456789' );

// Set a schedule date-time, optional
// $sms->setTimestamp('2014-01-01 10:02');

// Replace non GSM-7 characters by appropriate valid GSM-7 characters
// $sms->setReplacechars(false);

// If you want a dlr notification of the message sent to another url than that you have set on the website, you can use this parameter. Don't forget to set a reference!
// $sms->setDlrUrl('http://www.example.com/dlr_url.php');

// The message will be sent as a voice message and the gateway_id will be overwritten to 8, which is the voice gateway. (Dutch only for the moment)
// $sms->setVoice(true);

// Set the quality of the route that you want to use send the message.
// $sms->setGateway('quality');

// If $test is TRUE, then the message is not actually sent or scheduled, and there will be no credits deducted.
// $sms->setTest(true);

// Send the message to the destination(s)
$sms->sendSms ( 'This is a test message' );

echo "\nResponse:";
echo "\n" . $sms->getResponseCode ();
echo "\n" . $sms->getResponseMessage ();
echo "\n";
// First download the Java class (https://github.com/mobiletulip/messagebird-sms-api-java/archive/master.zip)
import com.messagebird.MessageBirdApi;

public class Example {
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) throws Exception {
        MessageBirdApi smsApi = new MessageBirdApi();

        smsApi.authenticate("username", "password");        // authenticate with MessageBird SMS API

        smsApi.setSender("YourSender");                     // set the name or number where the message comes from
        smsApi.addDestination("31600000001");               // add number to destination list, this function can be called multiple times for more receivers
        smsApi.setReference("123456789");                   // your unique reference

        //smsApi.setTimestamp(2012, 2, 27, 11, 30);         // only use if you want to schedule message
        smsApi.send("This is a test message");              // send the message to the receiver(s)

        System.out.println(smsApi.getResponseCode());       // print out the response code
        System.out.println(smsApi.getResponseMessage());    // print out the response message
    }
}
# First download the Python class (https://github.com/mobiletulip/messagebird-sms-api-python/archive/master.zip)
# Import the MessageBird Library which will send the message to our server
from MessageBird import MessageBird

# Set the MessageBird username and password and create an instance of the SmsCity class
smsApi = MessageBird('username', 'password')

# Set the sender: could be a number (16 numbers) or letters (11 characters)
smsApi.setSender('YourSender')

# Add the destination mobile number.
# This method can be called several times to add have more than one recipient for the same message
smsApi.addDestination('31600000000')

# Set a reference
smsApi.setReference('123456789')

# Send the message to the destination(s)
smsApi.sendSms('This is a test message')

# When using in the console, it will show you what the response was from our server
print 'Response:'
print smsApi.getResponseCode()
print smsApi.getResponseMessage()
<%
  username = "your-username"
  password = Server.urlencode("your-api-password")

  body        = "This is a test message"
  body        = Server.urlencode(body) <%-- // encode special characters --%>
  sender      = "YourSender"
  destination = "31600000000" <%-- // more numbers can be added by seperating them with a comma (,) --%>

  test = 0 <%-- // If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted. --%>

  api_url     = "http://api.messagebird.com/api/sms"

  request_url = api_url & "?username=" & username & "&password=" & password & "&body=" & body &_
          "&sender=" & sender & "&destination=" & destination & "&test=" & test

  set xmlhttp = CreateObject("MSXML2.ServerXMLHTTP")
  xmlhttp.open "GET", url, false
  xmlhttp.send ""

  msg = xmlhttp.responseText
  response.write(msg)
  set xmlhttp = nothing
%>
void Page_Load(Object Src, EventArgs E) {
    api.Text = readHtmlPage("http://api.messagebird.com/api/sms");
}

private String readHtmlPage(string url)
{
    String username = "your-username";
    String password = "your-api-password";

    String body        = "This is a test message";
    String body        = body; /* encode special characters */
    String sender      = "YourSender";
    String destination = "31600000000"; /* more numbers can be added by seperating them with a comma (,)  */

    String test = 0; /* If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted */

    String result = "";
    String strGet = "username=" + HttpUtility.UrlEncode(username) + "&password=" + HttpUtility.UrlEncode(password) +
              "&body=" + HttpUtility.UrlEncode(body) + "&sender=" + HttpUtility.UrlEncode(sender) + "&destination=" + destination + "&test=" + test;

    StreamWriter myRequest = null;
    HttpWebRequest objRequest = (HttpWebRequest)WebRequest.Create(url);

    objRequest.Method = "POST";
    objRequest.ContentLength = Encoding.UTF8.GetByteCount(strGet);
    objRequest.ContentType = "application/x-www-form-urlencoded";
    try{
        myRequest = new StreamWriter(objRequest.GetRequestStream());
        myRequest.Write(strGet);
    }
    catch (\Exception e)
    {
        return e.Message;
    }
    finally {
        myRequest.Close();
    }

    HttpWebResponse objResponse = (HttpWebResponse)objRequest.GetResponse();
    using (StreamReader sr = new StreamReader(objResponse.GetResponseStream()) )
    {
        result = sr.ReadToEnd();
        // Close and clean up the StreamReader
        sr.Close();
    }
    return result;
}
Imports System.IO
Imports System.Web

Private Function Send(
    ByVal Body As String, _
    ByVal Sender As String, _
    ByVal Destination As String, _
    ByVal Test As String
) As String

    Const UserName As String = "your-username"
    Const Password As String = "your-api-password"

    Const ApiUrl As String = "http://api.messagebird.com/api/sms"

    Dim strPost As String

    strPost = "username=" + UserName _
       + "&password=" + System.Web.HttpUtility.UrlEncode(Password) _
       + "&body=" + System.Web.HttpUtility.UrlEncode(Body) _
       + "&sender=" + Sender _
       + "&destination=" + Destination _
       + "&test=" + Test

    Dim byteArray As Byte() = Encoding.UTF8.GetBytes(strPost)

    Dim request As WebRequest = WebRequest.Create(ApiUrl)
    request.Method            = "POST"
    request.ContentType       = "application/x-www-form-urlencoded"
    request.ContentLength     = byteArray.Length

    Dim dataStream As Stream = request.GetRequestStream()
    dataStream.Write(byteArray, 0, byteArray.Length)
    dataStream.Close()

    Dim response As WebResponse = request.GetResponse()
    dataStream = response.GetResponseStream()
    Dim reader As New StreamReader(dataStream)
    Dim responseFromServer As String = reader.ReadToEnd()

    reader.Close()
    dataStream.Close()
    response.Close()

    If responseFromServer.Length > 0 Then
        Return responseFromServer
    Else
        Return CType(response, HttpWebResponse).StatusDescription
    End If
End Function
#!/usr/bin/perl -T

use strict;
use LWP::UserAgent;
use HTTP::Request::Common;

my $username = "your-username";
my $password = "your-api-password";

my $body        = "This is a test message";
my $sender      = "YourSender";
my $destination = "31600000000"; # more numbers can be added by seperating them with a comma (,)

my $test = 0; # If $test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted

my $api_url = "http://api.messagebird.com/api/sms";
my $ua = LWP::UserAgent->new();

my $res = $ua->request
(
 POST $api_url,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username'    => $username,
                    'password'    => $password,
                    'body'        => $body,
                    'sender'      => $sender,
                    'destination' => $destination,
                    'test'        => $test,
                  ]
);

if ($res->is_error) {
    die "HTTP Error";
}
print "Response:\n\n" . $res->content . "\n\n";
require 'net/http'
require 'uri'

username = "your-username"
password = URI.escape("your-api-password")

body        = "This is a test message"
body        = URI.escape("body")
sender      = "YourSender"
destination = "31600000000" # more numbers can be added by seperating them with a comma (,)

test = 0 # If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted

api_url     = "http://api.messagebird.com/api/sms"

request_url = api_url + "?" + "username=" + username + "&password=" + password +
        "&body=" + body + "&sender=" + sender + "&destination=" + destination + "&test=" + test

url = URI.parse(request_url)
full_path = (url.query.blank?) ? url.path : "#{url.path}?#{url.query}"

the_request = Net::HTTP::Get.new(full_path)
the_response = Net::HTTP.start(url.host, url.port) {
    |http|
    http.request(the_request)
}

puts(the_response.body)
The GO library is created by an external author.

The library can be found at: https://github.com/Grovespaz/sms
The documentation can be found at http://godoc.org/github.com/Grovespaz/sms

Offer SMS through SMPP

You can also get connected to the MessageBird platform by using the SMPP-protocol (v3.3 and v3.4 are both supported). Please contact us if you would like us to set up a personalised SMPP account for you.

Learn more ⇢

Configuration

You should use the following settings to configure your SMPP client.

Server: smpp.messagebird.com
Port: 2775
System type: VMA

DCS (data coding scheme) & ESM

The DCS parameter defines in which charset/encoding the message (and alphanumeric originator) is encoded. It is important that the DCS is set up correctly for correct delivery of the message text.

The ESM parameter defines the type of communication: normal text, binary or concatenated (long).

DCSESMExplanation
00GSM 03.38 7-bit; text *
064/67GSM 03.38 7-bit; concatenated or binary *
10ISO-8859-1(5) 8-bit; text *
164/67ISO-8859-1(5) 8-bit; concatenated or binary *
30Windows 1252 8-bit; text
364/67Windows 1252 8-bit; concatenated or binary
80Unicode in UTF-16 (16-bit)
864/67Unicode in UTF-16 (16-bit); concatenated

Offer text messages via email (Email to SMS)

With the Email to SMS service, an email message can be converted directly into a text message and sent to the chosen mobile number. You can do this without any additional software, with any email program.

Learn more ⇢

Authentication for sending messages through our Email to SMS gateway is provided by your email address. First, add your email address on the Email to SMS settings page and configure it. After setting up your account, sending a text message is very easy:

- Send a message from the email address that you provided on the Email to SMS settings page
- Send to: 31612345678@sms.messagebird.com
- For the subject, you fill in the originator
- Type the message you want to send

Examples

Marking the beginning and end of the text message

If you do not want to send the total content of the email as a text message, but only a part of it, you can do that by marking the beginning and the end of the text message in the email with --begin and/or --end. You will find some examples below.

Usage of --begin and --end
Dear customer,
--begin This is the only part of the e-mail messages that is being sent. --end

Best regards,
MessageBird
Usage of only --begin
Dear customer,

Below you will find additional information about your order.
--begin This is the part of the email message that will actually be sent.
Usage of only --end
This is the part of the email message that will actually be sent.
--end
Best regards,
MessageBird

Sending to groups

It is also possible to send messages via Email to SMS to a whole group in one go. The name of the group you want to send the message to can only contain letters, numbers and characters (so no spaces or special characters).

Send to:   groupname@sms.messagebird.com
Send to:   name-of-a-group@sms.messagebird.com

Receive text messages at a private number

MessageBird also offers the possibility to receive text messages (Mobile Originated, MO). You can read these via our website or have them sent on to a URL of your choice.

Learn more ⇢

You can use your private number (the VMN), but you can of course also use one of our public numbers.

Download the documentation for receiving SMS.


<?php
    // Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on
    $receiver = $_POST["receiver"];
        
    // Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message
    $sender = $_POST["sender"];
        
    // The received message
    $message = $_POST["message"];
        
    // The time the message was received in our systems (in the timezone that you set in your account)
    $date = $_POST["date"];
        
    // The time in UTC (+00) the message was received in our systems
    $date_utc = $_POST["date_utc"];
        
    // The reference for the incoming message
    $reference = $_POST["reference"];

    // Check if it is a binary message
    if (isset($_POST['type']) and $_POST['type'] === 'binary' and isset($_POST['udh'])) {
        $udh = $_POST['udh'];
    }
<%
    <%-- // Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on --%>
    string receiver = Request.Params["receiver"] ?? string.Empty;

    <%-- // Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message --%>
    string sender = Request.Params["sender"] ?? string.Empty;

    <%-- // The received message --%>
    string message = Request.Params["message"] ?? string.Empty;

    <%-- // The time the message was received in our systems (in the timezone that you set in your account) --%>
    string date = Request.Params["date"] ?? string.Empty;

    <%-- // The time in UTC (+00) the message was received in our systems --%>
    string date_utc = Request.Params["date_utc"] ?? string.Empty;

    <%-- // The reference for the incoming message --%>
    string reference = Request.Params["reference"] ?? string.Empty;
%>
# Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on
receiver = params[:receiver]

# Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message
sender = params[:sender]

# The received message
message = params[:message]

# The time the message was received in our systems (in the timezone that you set in your account)
date = params[:date]

# The time in UTC (+00) the message was received in our systems
date_utc = params[:date_utc]

# The reference for the incoming message
reference = params[:reference]

Receiving SMS on your own keyword

Documentation for receiving SMS messages (MO) on your keyword or short code.

Learn more ⇢

Forward to URL

As soon a message connected to your keyword is received we can immediately redirect this to the URL provided by you. This is done via an HTTP request to your platform. We send the necessary details in GET or POST variables. You can set up the URL in your keyword settings.

Example of an URL provided by you:
http://www.yoursite.com/sms/incoming.php

Example of an URL request:
http://www.yoursite.com/sms/incoming.php?shortcode=1008&keyword=EXAMPLE&message=Example&originator=31612345678&operator=02F440&receive_datetime=20151029101021 &mid=9000123

More information about parameters below.

Expected response
Our system expects the answer to our HTTP request (the so called response) to be the word ‘OK’ (without quotes or HTML code). If your system doesn’t respond with an ‘OK’ our platform will keep on trying to send the request. Note: this check is case sensitive.

After this you can save the message in your database or get information from your database based on the message and reply through our SMS Gateway.

ParameterExplanation
shortcodeThe shortened number the message was sent to.
keywordThe keyword that was used.
messageThe complete message (including keyword) that was sent.
originatorThe phone number the message was sent from.
midMO message ID: this is required to be able to respond to incoming messages
subscriptionOnly for subscription services. If the message contains the word ON, OFF or OK after the keyword (or is the final word of the message) this is probably an opt-in or opt-out for a subscription service. As a reminder we include the parameter ‘subscription’ with the value ‘ON’, ‘OFF’ or ‘OK’. Note: if your offer a free subscription service an OK isn’t required.
receive_datetimeTime the operator received the message. Format: YYYYMMDDhhmmss.

Receive text message delivery reports

If you are using our HTTP-API services, you can also choose to receive delivery reports. In these reports, the status of the sent text message is shown.

Learn more ⇢

You can specify the URL that we should send delivery reports to on the account settings page. Is your server temporary non-responsive? We try again 10 more times in the following 24 hours.

Please note: we only send a DLR when the reference in the sent message is included.

Download the documentation for delivery reports (Chapter 6)

<?php
    // This msisdn/phonenumber of the receiver of the SMS message
    $gsm = $_GET['GSM'];

    // The status of the SMS message, possible values are: delivered, not delivered, buffered
    $status = $_GET['STATUS'];

    // The reference of the message that you provided upon sending the message
    $reference = $_GET['REFERENCE'];
<%
    <%-- // This msisdn/phonenumber of the receiver of the SMS message --%>
    string gsm = Request.Params["GSM"] ?? string.Empty;

    <%-- // The status of the SMS message, possible values are: delivered, not delivered, buffered --%>
    string status = Request.Params["STATUS"] ?? string.Empty;

    <%-- // The reference of the message that you provided upon sending the message --%>
    string reference = Request.Params["REFERENCE"] ?? string.Empty;
%>
# This msisdn/phonenumber of the receiver of the SMS message
gsm = params[:GSM]

# The status of the SMS message, possible values are: delivered, not delivered, buffered
status = params[:STATUS]

# The reference of the message that you provided upon sending the message
reference = params[:REFERENCE]

HLR-lookup (Network Query)

Using our API you can run a Network Query. This allows you to view to which operator a mobile number (MSISDN) belongs to in real time and see whether the number is active.

Learn more ⇢

A Network Query can be done on the mobile network. This allows you to view to which operator a mobile number (MSISDN) belongs to in real time. This service is also called a ‘Network Look-up Service’ or ‘HLR lookup’. For example: a Network Query can be useful to determine to which operator a ported number (Mobile Number Portability, MNP) belongs, to be able to use the most resourceful SMS routing method.

Requesting HLR

For a request, you send the following request (example):
https://api.messagebird.com/api/hlr/?username=[username]&password=[password]&recipients=[recipient]&reference=[reference]

Optionally provide your own reference, which will be used for reporting the result in your system. You can supply a URL on the API settings page where you would like the HLR results to be sent to. Rates for an HLR are 0.25 credits per number

Receiving the HLR result

Soon thereafter (a few seconds to a minute), you will receive a request containing the network information for the requested number at the URL you specified on the settings-page.

Feedback from HLR result:

http://www.your-domain.com/sms/hlr.php?reference=123456789&recipient=31612345678&status=60&network=204160

The status parameter you receive in the report corresponds to one of the following statuses:

  • 60 - request successful
  • 61 - request successful, MSISDN/recipient unavailable
  • 62 - request successful, MSISDN/recipient does not exist
  • 69 - request failed

The network parameter is the ‘mobile network code’ (MNC). A full list of mobile network codes can be found on this Wikipedia page.

Request credit balance

Using this API, you'll be able to pull up the status of your balance in real time.

Learn more ⇢

Our API uses HTTP-requests. When you send an HTTP-request to our server, you will be using POST- or GET-variables to send the values. Use the URL below for requesting your credit balance:

https://api.messagebird.com/api/credits/?username=[username]&password=[password]

Processing the response

This request returns the following result (example):

<response>
<item>
<credits>1300</credits>
</item>
</response>

The status codes during a faulty request are explained further in the SMS-API documentation.

Click here to download the SMS HTTP-API documentation.

Cookie Settings