API Reference

API Token (recommended)

Generate tokens from Dashboard → API Tokens. Tokens start withmbs_. Pass the token as a Bearer token or as the X-API-Key header.

# Bearer token
curl -H "Authorization: Bearer mbs_your_token_here" \
     https://api.yourdomain.com/api/v1/messages

# X-API-Key header (alternative)
curl -H "X-API-Key: mbs_your_token_here" \
     https://api.yourdomain.com/api/v1/messages

Each token is scoped to specific resources (messages, contacts, campaigns, etc.). Requests to resources outside the token's scopes return 403 Forbidden.

Token scopes

Send a message

curl -X POST https://api.yourdomain.com/api/v1/messages \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+254712345678",
    "message": "Hello from Mobile Sasa!",
    "sender_id": "MYAPP"
  }'

{
  "success": true,
  "data": {
    "uuid": "msg-uuid",
    "to": "+254712345678",
    "message": "Hello from Mobile Sasa!",
    "sender_id": "TextBlast",
    "status": "queued",
    "parts": 1,
    "created_at": "2026-05-11T09:00:00Z"
  }
}

List messages

curl "https://api.yourdomain.com/api/v1/messages?page=1&page_size=20" \
  -H "Authorization: Bearer mbs_your_token_here"

Get a message

curl https://api.yourdomain.com/api/v1/messages/msg-uuid \
  -H "Authorization: Bearer mbs_your_token_here"

Resend a message

Retries a failed message. Returns the new message object.

curl -X POST https://api.yourdomain.com/api/v1/messages/msg-uuid/resend \
  -H "Authorization: Bearer mbs_your_token_here"

List contacts

curl "https://api.yourdomain.com/api/v1/contacts?search=John&page_size=50" \
  -H "Authorization: Bearer mbs_your_token_here"

Create a contact

curl -X POST https://api.yourdomain.com/api/v1/contacts \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+254712345678",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]"
  }'

Update a contact

Same fields as create. All fields are optional — only provided fields are updated.

Delete a contact

Bulk import contacts

Upload a CSV or XLSX file. The file must have a phone column. Optional columns: first_name,last_name,email. Returns an upload UUID for polling status.

curl -X POST https://api.yourdomain.com/api/v1/contacts/import \
  -H "Authorization: Bearer mbs_your_token_here" \
  -F "[email protected]"

# Poll import status
curl https://api.yourdomain.com/api/v1/contacts/uploads/{upload_uuid} \
  -H "Authorization: Bearer mbs_your_token_here"

List groups

curl https://api.yourdomain.com/api/v1/groups \
  -H "Authorization: Bearer mbs_your_token_here"

Create a group

curl -X POST https://api.yourdomain.com/api/v1/groups \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Customers", "description": "High-value customer segment" }'

Manage group contacts

# Add contact to group
curl -X POST https://api.yourdomain.com/api/v1/groups/group-uuid/contacts \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+254712345678" }'

# Remove contact from group
curl -X DELETE "https://api.yourdomain.com/api/v1/groups/group-uuid/contacts/%2B254712345678" \
  -H "Authorization: Bearer mbs_your_token_here"

Create a campaign

curl -X POST https://api.yourdomain.com/api/v1/campaigns \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May Promo",
    "message": "Get 20% off all orders this weekend! Use code: MAY20",
    "sender_id": "sender-uuid",
    "group_ids": ["group-uuid-1", "group-uuid-2"]
  }'

{
  "success": true,
  "data": {
    "uuid": "campaign-uuid",
    "name": "May Promo",
    "status": "draft",
    "recipient_count": 2847,
    "cost_units": 2847,
    "created_at": "2026-05-11T09:00:00Z"
  }
}

Send a campaign

Triggers dispatch. The campaign status moves to sending and thencompleted once all messages are queued. SMS units are reserved at this point.

curl -X POST https://api.yourdomain.com/api/v1/campaigns/campaign-uuid/send \
  -H "Authorization: Bearer mbs_your_token_here"

Campaign statuses

List surveys

curl https://api.yourdomain.com/api/v1/surveys \
  -H "Authorization: Bearer mbs_your_token_here"

Get a survey

Returns the survey definition including all questions and their answer options.

Get survey responses

List USSD codes

curl https://api.yourdomain.com/api/v1/ussd/codes \
  -H "Authorization: Bearer mbs_your_token_here"

List extensions

Returns extensions assigned to your team across all USSD codes.

List tokens

Returns all tokens for your team, including revoked and expired ones.

curl https://api.yourdomain.com/api/v1/tokens \
  -H "Authorization: Bearer mbs_your_token_here"

Create a token

curl -X POST https://api.yourdomain.com/api/v1/tokens \
  -H "Authorization: Bearer mbs_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zapier Integration",
    "scopes": ["messages", "contacts"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

{
  "success": true,
  "data": {
    "raw_token": "mbs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token": {
      "uuid": "token-uuid",
      "name": "Zapier Integration",
      "scopes": ["messages", "contacts"],
      "expires_at": "2027-01-01T00:00:00Z",
      "created_at": "2026-05-11T09:00:00Z"
    }
  }
}

Revoke a token

Immediately invalidates the token. Any in-flight requests using it will receive 401.

curl -X DELETE https://api.yourdomain.com/api/v1/tokens/token-uuid \
  -H "Authorization: Bearer mbs_your_token_here"

Binding

Use bind_transceiver to send and receive in a single session. The server supports both TRX and separate TX/RX binds.

bind_transceiver:
  system_id:      ACME2024
  password:       mbs_your_token_here
  system_type:    (leave empty)
  interface_ver:  0x34
  addr_ton:       0x01  (International)
  addr_npi:       0x01  (ISDN/E.164)
  address_range:  (leave empty)

Sending messages

Use submit_sm. The server returns amessage_id in the response — keep it for DLR correlation.

submit_sm:
  service_type:      (empty)
  source_addr_ton:   0x05  (Alphanumeric)
  source_addr_npi:   0x00
  source_addr:       TextBlast         # your approved sender ID
  dest_addr_ton:     0x01  (International)
  dest_addr_npi:     0x01  (ISDN)
  destination_addr:  254712345678      # no leading +
  esm_class:         0x00
  data_coding:       0x00  (GSM7)  or  0x08  (UCS-2 / Unicode)
  registered_delivery: 0x01            # request delivery receipt
  short_message:     Hello from Mobile Sasa!

Delivery receipts

Set registered_delivery = 0x01 to receive adeliver_sm DLR. Theshort_message body contains the delivery status string.

deliver_sm (DLR):
  short_message: id:MSG123 sub:001 dlvrd:001 submit date:2605110900 done date:2605110900 stat:DELIVRD err:000

# stat values:
#   DELIVRD — delivered to handset
#   UNDELIV — undeliverable (number does not exist or unreachable)
#   REJECTD — rejected by carrier
#   EXPIRED — message TTL expired

Unicode / long messages

For messages with non-GSM7 characters set data_coding = 0x08. Long messages (over 160 GSM7 or 70 UCS-2 characters) must be split into concatenated PDUs using UDH.

# Long message split example (3 parts)
submit_sm[1]:
  esm_class: 0x40  (UDH present)
  sar_msg_ref_num: 42   (same for all parts)
  sar_total_segments: 3
  sar_segment_seqnum: 1
  data_coding: 0x00
  short_message: <part 1 text, max 153 chars>

submit_sm[2]:
  sar_segment_seqnum: 2
  ...

Session limits