Bulk SMS API

Send SMS from your own system, check your balance and receive delivery reports. Every request is an HTTPS POST with a JSON body.

Before you start · Send SMS · Replies and errors · Check your balance · Delivery reports

Before you start

Register on this site. When we approve your account, we register your sender ID with the networks.
We then give you a client ID and a client secret. You also find them in your FastHub account, under API configurations.
Keep the client secret on your server only. Never put it in a mobile app or a web page.
Send the client secret exactly as we gave it to you. Do not hash or encode it.

Base address: https://bulksms.fasthub.co.tz. Every request needs the header Content-Type: application/json.

Send SMS

POST/api/sms/send

Request

{
  "auth": {
    "clientId": "123456",
    "clientSecret": "your-client-secret"
  },
  "messages": [
    {
      "text": "Your order 4581 is ready for collection.",
      "msisdn": "255712345678",
      "source": "MYSHOP",
      "reference": "9f3c2a7d5b8e4c1aa0d6e2f4b7c9d013"
    }
  ]
}

Field	Required	Description
`auth.clientId`	Yes	Your client ID. `client_id` is also accepted.
`auth.clientSecret`	Yes	Your client secret. `client_secret` is also accepted.
`messages`	Yes	One or more messages. Up to 50 in one request, unless we have agreed a different limit with you.
`text`	Yes	The message text. It cannot be empty.
`msisdn`	Yes	The recipient's number in international form, without `+`. Example: `255712345678`.
`source`	Yes	Your registered sender ID.
`reference`	For delivery reports	Your own identifier for this message, at least 20 characters. Use a different value for each message. Delivery reports carry it back to you. Without it, you do not receive a report for each message.
`coding`	No	`GSM7` for plain text or `UCS2` for other characters, such as emoji or Arabic script.
`flash`	No	`true` shows the message on the screen without saving it. The default is `false`.

Example with curl

curl -X POST https://bulksms.fasthub.co.tz/api/sms/send \
  -H "Content-Type: application/json" \
  -d '{"auth":{"clientId":"123456","clientSecret":"your-client-secret"},
       "messages":[{"text":"Hello from FastHub","msisdn":"255712345678","source":"MYSHOP",
                    "reference":"9f3c2a7d5b8e4c1aa0d6e2f4b7c9d013"}]}'

Replies and errors

Replies are JSON in this shape. status tells you whether we accepted the request.

{
  "status": true,
  "message": "Successfully submitted 1 message(s) to broker.",
  "data": null,
  "balance": 125000.0
}

An accepted request means the messages are in our queue. The delivery report tells you whether each message reached the phone.

HTTP code	`message`	What to do
200	Successfully submitted N message(s) to broker.	Nothing. Wait for the delivery reports.
400	Validation errors	A field is missing or wrong. `data` lists each problem.
400	Invalid credentials	Check the client ID and the client secret. Send the secret exactly as we gave it.
400	client N is disabled	Your API configuration is switched off. Contact us.
400	Status inactive	Your account is not active. Contact us.
400	List should contain not more than N messages	Split the messages into smaller requests.
500	Something went wrong!	We could not read the request. Check that the body is valid JSON, has an `auth` block, and uses only the fields on this page.
400	Something went wrong…	Try again later. If it continues, contact us.

Check your balance

POST/api/account/balance

{
  "auth": {
    "clientId": "123456",
    "clientSecret": "your-client-secret"
  }
}

The reply:

{
  "status": true,
  "message": "Account balance",
  "balance": 125000.0,
  "data": {
    "name": "My Shop Limited",
    "email": "[email protected]",
    "currency": "TZS"
  }
}

Wrong credentials return HTTP 400 with Invalid credentials used.

Delivery reports

We send the final status of each message to your system. Give us a callback address (an HTTPS address on your server), and ask us to switch callbacks on for your API configuration.

We send a POST with this body:

{
  "statuses": [
    {
      "status": "DELIVRD",
      "reference": "9f3c2a7d5b8e4c1aa0d6e2f4b7c9d013",
      "description": "Delivered",
      "msisdn": "255712345678"
    }
  ]
}

`status`	Meaning
`DELIVRD`	The phone received the message.
`UNDELIV`	We or the network could not deliver or route the message.
`EXPIRED`	The phone was unreachable until the message expired.
`REJECTD`	We or the network refused the message, for example a repeated message, empty text or a number that has opted out.
`DELETED`	The network deleted the message before delivery.
`UNKNOWN`	The network did not report a final state.
`ACCEPTD`	The network accepted the message on the phone's behalf.
`FAILED`	We could not send the message.

Reply within 5 seconds; we do not read the status code or the body of your reply. If we cannot reach your server, or it does not reply in time, we send the report again every 30 seconds, for up to 24 hours. Your server can therefore receive the same report more than once. Match each report to your message by its reference, and ignore a report you have already processed.

Accounts set up for our older API receive a different body, with one letter for each status: {"receipts": [{"status": "D", "msisdn": "255712345678", "reference_id": "…"}]}. One letter can stand for more than one status. Contact us to move to the format above.

Need help? Call 0800 712 354 or email [email protected].