DEVELOPER DOCUMENTATION

Integrate SMS into your application

Send messages, purchase SMS credits, and check your balance through the Beno SMS REST API.

Create a project and generate an API key in API Keys. Save the full key when it is generated.
Have an approved sender ID available to your organization and sufficient SMS credits before sending.
Set the following environment variables on your server, then try the balance request below.

Server environment

export BENO_SMS_BASE_URL="https://api-sms.benotz.com/api/developer/v1"
export BENO_SMS_API_KEY="YOUR_API_KEY"

Authentication

Every endpoint requires a bearer API key. Requests use the organization attached to that key; a portal login or organization ID is not required. Keep keys in server environment variables, away from browser code, source control, and logs. Rotating a key immediately deactivates the old key.

Request headers

Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json

The developer routes enforce a throttle of 60 requests per minute. Handle HTTP 429 and wait before retrying.

Send a single SMS

POST/sms/single

Send a message to one recipient using an approved sender available to your organization.

sender: Required string, up to 50 characters. Your approved sender name.
recipient: Required string. Tanzanian mobile number, e.g. 255712345678.
body: Required string, up to 5,000 characters.

Send a single SMS · cURL

curl -X POST "$BENO_SMS_BASE_URL/sms/single" \
  -H "Authorization: Bearer $BENO_SMS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "sender": "YOUR_SENDER",
  "recipient": "255712345678",
  "body": "Your order has shipped."
}'

Response · 202 Accepted

Send a single SMS · example response

{
  "success": true,
  "message": "SMS accepted for processing. Delivery and credit checks occur asynchronously.",
  "data": {
    "recipient_count": 1
  }
}

Acceptance is not delivery confirmation. Delivery and credit checks run asynchronously; review messages and delivery reports in your dashboard.

Send bulk SMS

POST/sms/bulk

Send the same message to up to 1,000 recipients per request. Duplicate normalized phone numbers are counted once.

sender: Required string, up to 50 characters. Your approved sender name.
recipients: Required array of 1–1,000 phone-number strings. Use 2556XXXXXXXX or 2557XXXXXXXX.
body: Required string, up to 5,000 characters.

Send bulk SMS · cURL

curl -X POST "$BENO_SMS_BASE_URL/sms/bulk" \
  -H "Authorization: Bearer $BENO_SMS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "sender": "YOUR_SENDER",
  "recipients": [
    "255712345678",
    "255612345678"
  ],
  "body": "Thank you for choosing us."
}'

Response · 202 Accepted

Send bulk SMS · example response

{
  "success": true,
  "message": "SMS accepted for processing. Delivery and credit checks occur asynchronously.",
  "data": {
    "recipient_count": 2
  }
}

Split larger recipient lists into batches of at most 1,000. Do not automatically repeat a send after a timeout: the original request may already have been accepted.

Check balance

GET/sms/balance

Read the available SMS credit balance for the organization associated with your API key. No request body is needed.

Check balance · cURL

curl -X GET "$BENO_SMS_BASE_URL/sms/balance" \
  -H "Authorization: Bearer $BENO_SMS_API_KEY" \
  -H "Accept: application/json"

Response · 200 OK

Check balance · example response

{
  "success": true,
  "message": "Success",
  "data": {
    "sms_balance": 1250
  }
}

The example balance is illustrative. The returned value reflects available SMS credits, not a cash balance.

Purchase SMS credits

POST/sms/purchase

Create an SMS bundle purchase for your organization. The server selects the active bundle whose unit range contains sms_units and applies its price.

sms_units: Required integer, at least 1 and within an active bundle's unit range.
phone_number: Required Tanzanian mobile-number string, e.g. 255712345678.
network: Optional: vodacom, airtel, yas, or halotel. When omitted, the server detects the mobile-money network from the phone number.

Purchase SMS credits · cURL

curl -X POST "$BENO_SMS_BASE_URL/sms/purchase" \
  -H "Authorization: Bearer $BENO_SMS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "sms_units": 1000,
  "phone_number": "255712345678"
}'

Response · 201 Created

The response data contains transaction_reference, status, amount, and currency. Save the reference and check payment history and balance in the dashboard. Creation alone does not confirm credit allocation. Do not automatically retry purchases after uncertain failures.

Errors & troubleshooting

401 Unauthorized: Check the bearer token. Missing, malformed, expired, revoked, or inactive-project keys are rejected.
403 Forbidden: Check that your organization and wallet are active.
422 Validation error: Read the response validation details. Check required fields, phone format, sender approval, bundle ID, and quantity.
429 Too many requests: Slow down requests and respect Retry-After when provided.
5xx / network failure: Review API logs and the dashboard before repeating sends or purchases, which may already have been processed.

Use API Logs to investigate requests and delivery reports to check message outcomes.