Check your MessageBird balance with Google Sheets (and get notified)

I've been using MessageBird as my SMS provider of choice since a few years now. Not long ago I got an email from MessageBird telling me that my account balance is to low to send any more of the messages that were already in the pipeline. That is not a big deal since adding credits to your MessageBird account is quick using Paypal and the messages to be sent are not lost - MessageBird keeps them stored and sends them once you have enough credits again. And although MessageBird notified me - I wish I had known this earlier.

Seems to be a good testing ground for my trusted Google Sheets & Apps Script platform. What I wanted to achieve is simple:

  • retrieve my MessageBird account balance over MessageBird's API
  • compare the balance with a configured threshold - it it's below that threshold I want to be notified
  • send me an email with the current account balance
  • make sure that this script is automatically run each day (or night)

MessageBird's balance API

The endpoint for retrieving your account balance is: https://rest.messagebird.com/balance

You have to submit your authentication credentials in the request header.

The response looks like this:

{
    "payment": "prepaid",
    "type": "euros",
    "amount": 93.98
}

I generally segment my scripts in several small(er) functions. This is the one for getting the account balance:

function getMessageBirdBalance() {

  var params = {
    'method' : 'get',
    'headers': {
      'Authorization': 'AccessKey yourMessageBirdApiAccessKey'
    }
  };
  var jsondata    = UrlFetchApp.fetch('https://rest.messagebird.com/balance', params);
  var jsonobjects = JSON.parse(jsondata.getContentText());

  return jsonobjects.amount;

}

The configuration

Recently I started to transfer my scripts' config values to objects outside of the functions. I'm not sure if this is the most elegant way to do this but it fulfills my needs for the time being. Objects on the root level of a script are immediately available in all functions of that script.

var config = {
  balanceThreshold: 20,
  messagebirdAuth: 'AccessKey yourMessageBirdApiAccessKey'
}

Now that I've put the MessageBird API key into the config I can replace the API in the API function with the config key:

function getMessageBirdBalance() {

  var params = {
    'method' : 'get',
    'headers': {
      'Authorization': config.messagebirdAuth
    }
  };
...

The email function

var mailData = {
  to: 'my.email@example.com',
  subject: '',
  body: ''
}

function sendMail(mailData) {

  MailApp.sendEmail(
    mailData.to,
    mailData.subject,
    '',
    {htmlBody: mailData.body}
  );

}

I set up an object (mailData) that defines the structure for the email fields. An instance of that object later gets injected into the sendMail function. The sendMail function makes use of Google's built-in MailApp service.

The main function

Putting it all together: the main function is the entry point to the script. It retrieves the account balance by calling the API function. It then checks whether or not the current balance is less than the configured balance threshold. If that's the case an email is sent.

When sending the email the pre-configured mailData object (see above) gets "reused": the main function overwrites the subject and body fields and hands that object over to the sendMail function.

function checkBalanceAndNotify() {
  var accountBalance = getMessageBirdBalance();
  if (parseFloat(accountBalance, 10) < parseFloat(config.balanceThreshold, 10)) {
    mailData.subject = Utilities.formatString("Your MessageBird account balance: %0.2f EUR", accountBalance);
    mailData.body = Utilities.formatString("Your MessageBird account balance: %d EUR", accountBalance);
    sendMail(mailData);
  }
}

Configuring the trigger

To make this script run every night you simply define a trigger inside that Google Apps Script project. I used a daily trigger that gets fired every night between 1am and 2am. The function that should run is the "main" function checkBalanceAndNotify.

That's all! Once a day the script retrieves my MessageBird account balance and reliably inform me once it's below my configured threshold.