Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

MessageBird's REST API for Java

This repository contains the open source Java client for MessageBird's REST API. Documentation can be found at:

Build Status Maven metadata URI


  • Sign up for a free MessageBird account
  • Create a new access key in the developers sections
  • An application written in Java
  • Installed version of maven


The easiest way to install the MessageBird package is either via github:

git clone
cd java-rest-api/api
mvn install

If you are using maven, please refer to the mvn repository and choose your desired package version.


We have put some self-explanatory examples in the examples directory, but here is a quick example on how to get started. Assuming the installation was successful, you can import the messagebird package like this:

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.objects.MessageResponse;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.List;

Then, create an instance of MessageBirdClient:

// Create a MessageBirdService
final MessageBirdService messageBirdService = new MessageBirdServiceImpl("test_gshuPaZoeEG6ovbc8M79w0QyM");
// Add the service to the client
final MessageBirdClient messageBirdClient = new MessageBirdClient(messageBirdService);

Now you can query the API for information or send a request. For example, if we want to request our balance information you'd do something like this:

    try {
        // Get Balance
        System.out.println("Retrieving your balance:");
        final Balance balance = messageBirdClient.getBalance();

        // Display balance

    } catch (UnauthorizedException unauthorized) {
        if (unauthorized.getErrors() != null) {
    } catch (GeneralException generalException) {
        if (generalException.getErrors() != null) {

This will give you something like:

Retrieving your balance:
Balance{payment='prepaid', type='credits', amount=97}

To try out the command line examples follow the above build instructions. When everything did build successful you can try out the API like this:

cd examples/target
java -cp examples-1.2.0-jar-with-dependencies.jar ExampleSendMessage test_gshuPaZoeEG6ovbc8M79w0QyM 31612345678 "This is a test message"

Please see the other examples for a complete overview of all the available API calls.

Running with unit tests

Running unit tests requires you to create a developer key. You can create one for free at, or when you have one already you can skip registration and go to to create or get your test access key. Once you have such key you can run the unit tests like this:

mvn test -Ptest -DmessageBirdAccessKey=[your access key] -DmessageBirdMSISDN=[your phone]

This will run all unit tests and verifies if everything is running as expected.

Note: If you use by accident use your live key it will send messages and will remove it from your account, please ensure you use your test key to run your unit tests to avoid loosing your credits.

Proxy support

If you server doesn't have a direct connection to the internet you can setup a proxy to for the MessageBird service to use.

    final Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("", 8080));
    final MessageBirdService messageBirdService = new MessageBirdServiceImpl("test_gshuPaZoeEG6ovbc8M79w0QyM");


Complete documentation, instructions, and examples are available at:


The MessageBird REST Client for Java is licensed under The BSD 2-Clause License. Copyright (c) 2015-2019, MessageBird