Skip to main content

SMS Endpoints

The Tegasms SMS API provides endpoints for sending single messages, bulk campaigns, and checking your SMS balance. All endpoints require authentication via Bearer token.

Send single SMS

Send a single SMS message to one recipient.

Method: POST

URL: https://api.tegasms.co.tz/api/v1/send_sms/type/single

Headers

Authorization: Bearer your_api_token_here
Content-Type: application/json

Request body

{
  "from": "Tegasms",
  "recipient": "25578246004",
  "message": "Habari! Huu ni ukumbusho wa kulipia kifurushi chako cha familia ya Mwalimu ili uendelee kufurahia mfumo wetu, kufahamu asili ya ukoo wako na shughuli nyingine za kifamilia",
  "reference": "bulk_001"
}
FieldTypeDescription
fromstringSender ID (must be approved in your account)
recipientstringPhone number in international format (e.g., 25578246004)
messagestringSMS message content (max 160 characters per SMS)
referencestringOptional reference ID for tracking this message

Success response (200 OK)

{
  "status": "success",
  "message": "SMS sent successfully.",
  "sent": 1,
  "failed": 0,
  "failed_numbers": []
}

Error response (401/400)

{
  "status": "error",
  "message": "Unauthorized or non-existent Sender ID for the batch payload."
}

Example request

curl -X POST https://api.tegasms.co.tz/api/v1/send_sms/type/single \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Tegasms",
    "recipient": "25578246004",
    "message": "Habari! Huu ni ukumbusho wa kulipia kifurushi chako cha familia ya Mwalimu ili uendelee kufurahia mfumo wetu, kufahamu asili ya ukoo wako na shughuli nyingine za kifamilia",
    "reference": "bulk_001"
  }'

Send multiple SMS

Send SMS messages to multiple recipients in a single request.

Method: POST

URL: https://api.tegasms.co.tz/api/v1/send_sms/type/multiple

Headers

Authorization: Bearer your_api_token_here
Content-Type: application/json

Request body

{
  "messages": [
    {
      "from": "Tegasms",
      "recipient": "25578246004",
      "message": "Hello Maulid"
    },
    {
      "from": "Tegasms",
      "recipient": "255620350083",
      "message": "Hello Samile"
    }
  ],
  "reference": "bulk_001"
}
FieldTypeDescription
messagesarrayArray of message objects to send
messages[].fromstringSender ID for this message
messages[].recipientstringRecipient phone number in international format
messages[].messagestringSMS message content
referencestringOptional batch reference ID for tracking

Success response (200 OK)

{
  "status": "success",
  "message": "SMS messages dispatched successfully.",
  "count": 2
}

Example request

curl -X POST https://api.tegasms.co.tz/api/v1/send_sms/type/multiple \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "from": "Tegasms",
        "recipient": "25578246004",
        "message": "Hello Maulid"
      },
      {
        "from": "Tegasms",
        "recipient": "255620350083",
        "message": "Hello Samile"
      }
    ],
    "reference": "bulk_001"
  }'
tip

Use the multiple SMS endpoint for bulk campaigns. It is more efficient than sending individual requests for each recipient.

Check SMS balance

Check your current SMS credit balance.

Method: GET

URL: https://api.tegasms.co.tz/api/v1/sms/check_sms_balance

Headers

Authorization: Bearer your_api_token_here
Content-Type: application/json

Success response (200 OK)

{
  "sms_balance": 613
}

The sms_balance field shows the number of SMS credits remaining in your account.

Example request

curl -X GET https://api.tegasms.co.tz/api/v1/sms/check_sms_balance \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json"
note

Each SMS message costs 1 credit. Long messages (over 160 characters) may consume multiple credits depending on the message length.

Error handling

All endpoints return standard HTTP status codes:

StatusMeaning
200Request successful
400Bad request (invalid parameters)
401Unauthorized (invalid or missing API key)
429Rate limit exceeded
500Server error

When an error occurs, the response includes a status and message:

{
  "status": "error",
  "message": "Error description here"
}

Rate limiting

API requests are rate limited to prevent abuse:

  • Standard accounts: 100 requests per minute
  • High-volume accounts: Contact support for higher limits

If you exceed the rate limit, the API returns a 429 error. Wait before retrying your request.

Best practices

Validate phone numbers, Ensure phone numbers are in international format (e.g., 255XXXXXXXXX)

Check balance before sending, Use the check balance endpoint to verify you have sufficient credits

Use batch requests, Send multiple messages in one request instead of individual requests

Implement retry logic, Handle transient failures with exponential backoff

Store message references, Use the reference field to track messages in your system

See also

Docs by Docsio