SMS REST API

Use the SMS REST API for direct text delivery. SMS is text-only; use a WhatsApp API for media, documents, location, buttons, or lists.

Endpoint

POST https://karflows.com/api/sms/send

Headers

Authorization: Bearer kfsms_your_token
Content-Type: application/json

Send SMS

curl -X POST "https://karflows.com/api/sms/send" \
  -H "Authorization: Bearer kfsms_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255700000000",
    "sender": "DM BLUEWAVE",
    "text": "Your booking is confirmed for Friday at 6pm."
  }'

Parameters

Parameter	Type	Required	Description
`to`	string	Yes	Recipient phone number with country code
`sender`	string	No	Approved sender name owned by your account. Uses the account default when omitted
`text`	string	Yes	SMS body
`from`	string	No	Alias for `sender`
`message`	string	No	Alias for `text`

Phone numbers may include a leading +; KarFlows normalizes the value before sending.

Sender name rules

KarFlows rejects SMS requests when:

The sender name is not approved for the account.
The recipient’s mobile network is not approved for that sender.
Sender name belongs to another customer.
The account has no SMS balance.
The plan does not allow SMS.
SMS API is disabled by an administrator.

Sender names are matched without case or spacing differences, but KarFlows sends the exact approved value. For example, DMBLUEWAVE can resolve to the approved sender DM BLUEWAVE.

Check balance

GET https://karflows.com/api/sms/balance

curl "https://karflows.com/api/sms/balance" \
  -H "Authorization: Bearer kfsms_your_token"

The response includes available, used, and temporarily reserved SMS segments.

SMS logs

GET https://karflows.com/api/sms/logs?limit=50

curl "https://karflows.com/api/sms/logs?limit=50" \
  -H "Authorization: Bearer kfsms_your_token"

limit defaults to 50 and is capped at 200.

Success response

{
  "success": true,
  "message": "SMS submitted successfully",
  "data": {
    "reference": "sms_1778175300000_a1b2c3",
    "messageId": "17758372340",
    "accepted": true,
    "billingStatus": "charged",
    "deliveryStatus": "pending",
    "recipient": "255700000000",
    "sender": "DM BLUEWAVE",
    "segments": 1,
    "price": {
      "amount": 25,
      "currency": "TZS"
    }
  }
}

success: true means the delivery network accepted the SMS and returned a message ID. It does not confirm delivery to the handset.

Error response

{
  "success": false,
  "message": "Sender name is not approved"
}

Charging and refunds

KarFlows reserves the required SMS segments before submission.

Outcome	Balance behavior
Validation fails before submission	Not charged
Connection error or synchronous rejection	Automatically refunded
Accepted with a real message ID	Charged
Later delivery report says delivered	Remains charged
Later delivery report says rejected, undeliverable, or expired	Remains charged

An accepted message consumed the upstream SMS submission even when a later carrier or handset failure occurs. Do not automatically resend a 200 response; doing so can create duplicate messages and charges.

Final delivery

Use GET /api/sms/logs to inspect the current status:

sent: accepted, waiting for a final report.
delivered: confirmed delivered by the network.
failed: rejected synchronously or failed in a later delivery report.

Start Here

Messaging APIs

Operations

SDKs

Reference

Endpoint

Headers

Send SMS

Parameters

Sender name rules

Check balance

SMS logs

Success response

Error response

Charging and refunds

Final delivery

​Endpoint

​Headers

​Send SMS

​Parameters

​Sender name rules

​Check balance

​SMS logs

​Success response

​Error response

​Charging and refunds

​Final delivery

Endpoint

Headers

Send SMS

Parameters

Sender name rules

Check balance

SMS logs

Success response

Error response

Charging and refunds

Final delivery