Skip to main content

Mobitech Developers

Bulk SMS API

Getting started

Send SMS to Safaricom, Airtel, Telkom and other Kenyan networks from your own application with one HTTPS request. Bulk SMS costs KES 0.35 per SMS on all networks, with no set-up or monthly fees.

Base URLhttps://textapi.mobitechtechnologies.com
FormatJSON (UTF-8)
Authh_api_key header
  1. Create a Bulk SMS account (new accounts get 500 free SMS) and have your Sender ID approved, or use the default one assigned to you.
  2. Log in to the Bulk SMS portal and copy your API key from your company profile.
  3. Send your first SMS with the request below.
Your first SMS
curl -X POST "https://textapi.mobitechtechnologies.com/sms/sendsms" \
  -H "h_api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mobile": "254712345678",
  "message": "Hello from Mobitech!",
  "sender_name": "MOBITECH",
  "service_id": 0
}'

Authentication

Every request carries your API key in the h_api_key header. If your HTTP client can't send custom headers, put it in the JSON body as "h_api_key" instead.

Header
h_api_key: YOUR_API_KEY

Find the key in the Bulk SMS portal under your company profile:

Where to find the API key in the Mobitech Bulk SMS portal

Lock the key to your servers. In the same profile you can whitelist the IP addresses your requests come from (separate several with commas). Requests from other addresses are refused with code 1014.

Whitelisting API IP addresses in the Mobitech Bulk SMS portal

Send an SMS

POST https://textapi.mobitechtechnologies.com/sms/sendsms

Sends one message to one phone number. The response tells you the cost and your remaining credit straight away.

Body

mobile string required
Recipient in international format, e.g. 254712345678.
message string required
The text. Every 160 characters is charged as one SMS.
sender_name string required
Your approved Sender ID (or shortcode), e.g. MOBITECH.
service_id integer optional
0 for bulk SMS (default).
response_type string optional
json (default) or plain.
Request
curl -X POST "https://textapi.mobitechtechnologies.com/sms/sendsms" \
  -H "h_api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mobile": "254712345678",
  "message": "Hi Jane, your order #1024 has been dispatched.",
  "sender_name": "MOBITECH",
  "service_id": 0,
  "response_type": "json"
}'
Response
{
  "status_code": "1000",
  "status_desc": "Success",
  "message_id": "28451977",
  "mobile_number": "254712345678",
  "network_id": "1",
  "message_cost": "0.35",
  "credit_balance": "1499.65"
}

Keep message_id: it's what you use to fetch the delivery report. With "response_type": "plain" the response is status_code;status_desc;message_id, e.g. 1000;Success;28451977.

Send in bulk

POST https://textapi.mobitechtechnologies.com/sms/sendmultiple

Sends many messages in one request: each recipient can get a different text, and you can tag each one with your own client_ref to match results back to your records. Credit is checked once for the whole batch.

Body

sender_name string required
Your approved Sender ID.
messages array required
One object per recipient: mobile, message and an optional client_ref.
date_send string optional
Send later: YYYY-MM-DD HH:MM:SS, East Africa Time. See Schedule messages.
service_id integer optional
0 for bulk SMS (default).
Request
curl -X POST "https://textapi.mobitechtechnologies.com/sms/sendmultiple" \
  -H "h_api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sender_name": "MOBITECH",
  "service_id": 0,
  "messages": [
    {
      "mobile": "254712345678",
      "message": "Hi Jane, your balance is KES 1,200.",
      "client_ref": "cust-1001"
    },
    {
      "mobile": "254733000111",
      "message": "Hi Otieno, your balance is KES 450.",
      "client_ref": "cust-1002"
    }
  ]
}'
Response
{
  "status_code": 1000,
  "status_desc": "Success",
  "credit_balance": "1499.30",
  "schedule_details": [
    {
      "message_id": "28451978",
      "client_ref": "cust-1001",
      "mobile": "254712345678",
      "schedule_status": "1",
      "schedule_desc": "Success",
      "network_id": "1",
      "message_cost": "0.35"
    },
    {
      "message_id": "0",
      "client_ref": "cust-1002",
      "mobile": "254733000111",
      "schedule_status": "0",
      "schedule_desc": "Mobile number 254733000111 in DND.",
      "network_id": "2",
      "message_cost": "0"
    }
  ]
}

Each entry in schedule_details has schedule_status 1 (accepted) or 0 (not sent, with the reason in schedule_desc). You're only charged for accepted messages.

Schedule messages

Add date_send to a /sms/sendmultiple request to send at a later time. Use East Africa Time (UTC+3) in the format YYYY-MM-DD HH:MM:SS; a time in the past is rejected with 1009.

Scheduled request
curl -X POST "https://textapi.mobitechtechnologies.com/sms/sendmultiple" \
  -H "h_api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sender_name": "MOBITECH",
  "date_send": "2026-12-24 08:00:00",
  "messages": [
    {
      "mobile": "254712345678",
      "message": "Merry Christmas from all of us at Mobitech!",
      "client_ref": "xmas-1"
    }
  ]
}'

Delivery reports

GET https://textapi.mobitechtechnologies.com/sms/getdlr?message_id={id}

Returns the delivery status of one message, using the message_id from the send response. Send your key in the api_key header for this endpoint.

Request
curl "https://textapi.mobitechtechnologies.com/sms/getdlr?message_id=28451977" \
  -H "api_key: YOUR_API_KEY"
Response
{
  "status": "ok",
  "status_message": "record found",
  "data": {
    "message_id": "28451977",
    "mobile": "254712345678",
    "dlr_status": "1",
    "dlr_desc": "DeliveredToTerminal",
    "dlr_time": "2026-11-18 10:15:07",
    "tat": "4",
    "network_id": "1",
    "sms_cost": "0.35"
  }
}

dlr_status is one of the delivery statuses; tat is the time to deliver in seconds. Unknown ids return {"status": "failed", "status_message": "record not found"}.

Response codes

Every send response includes status_code and status_desc. Only 1000 means the message was accepted.

CodeMeaning
1000Success: message accepted for processing
1001Invalid sender name (shortcode / Sender ID)
1002Network not allowed
1003Invalid mobile number
1004Low bulk credits: top up your account
1005Internal system error: retry later
1006Invalid credentials (API key missing or wrong)
1009Data type not supported: send a JSON body
1010Request type not supported
1011Invalid user state or account suspended
1012Mobile number in DND (do-not-disturb) list
1013Invalid API key
1014IP not allowed: add it to your whitelist
1015Missing parameter
1016Monthly credit limit reached

Delivery statuses

The most common values of dlr_status in delivery reports:

dlr_statusMeaning
1DeliveredToTerminal: delivered to the phone
2MessageWaiting
3DeliveryImpossible
5DeliveredToNetwork
6DeliveryUncertain
7Insufficient_Balance
10UserInBlacklist
13NotSFCUser (not a Safaricom number)
15UserNotExist
16AbsentSubscriber (phone off or out of coverage)
17NOT_DELIVERED
18DELIVERED
19ForwardedToNetwork
21MessageRejected
22Queued
23InvalidMobile
25SenderName Blacklisted
27InvalidSourceAddress

Tips & limits

  • Use international format without +: 2547XXXXXXXX / 2541XXXXXXXX.
  • Every 160 characters of a message is charged as one SMS, so keep messages short to save credit.
  • On the promotional route, messages go out between 8 am and 7 pm; numbers on the DND list are skipped (1012).
  • Credit is deducted when a message is accepted and never expires. Check credit_balance in each response.
  • Retry only on 1005 (system error). Other codes need a fix to the request or account first.

Need help integrating? Email info@mobitechtechnologies.com or call (+254) 710 986455.

Frequently Asked Questions

How do I send SMS from my application in Kenya?

Send a POST request to https://textapi.mobitechtechnologies.com/sms/sendsms with your API key in the h_api_key header and a JSON body containing mobile, message and sender_name. A status_code of 1000 means the SMS was accepted.

How do I send bulk SMS with different messages to many people?

Use POST /sms/sendmultiple with a messages array. Each item has its own mobile, message and optional client_ref, and you can add date_send (YYYY-MM-DD HH:MM:SS, East Africa Time) to schedule the batch.

How do I check if an SMS was delivered?

Call GET /sms/getdlr?message_id=ID with your key in the api_key header. The response includes dlr_status and dlr_desc, for example 1 DeliveredToTerminal.

Where do I get a Mobitech Bulk SMS API key?

Sign up for a Bulk SMS account, log in to the Bulk SMS portal and copy the API key from your company profile. You can also whitelist the IP addresses allowed to use it.

Talk to us