Feltech SMS Gateway — API Reference

Authentication

All API requests must include your secret API key in the Authorization header as a Bearer token. You can generate API keys from your Dashboard → API Keys.

Required Header

Authorization: Bearer your_api_key

Keep your API keys secret. Never hardcode them into public repositories or expose them client-side. API keys start with .

Rate Limits

To ensure fair usage, the API enforces rate limits per IP address.

Endpoint Group	Limit
SMS & Sender ID (API Key routes)	60 requests / minute
Auth (login, register)	5 requests / minute

When you exceed the limit, the API returns 429 Too Many Requests. Use exponential back-off before retrying.

POST /api/v1/sms/send

Send an SMS

Sends an SMS message to a single recipient. Deducts 1 SMS credit per 160-character part. Phone numbers are auto-normalized to E.164 format for common Zambian formats. Optionally supply an Idempotency-Key header to safely retry without sending duplicates.

Body Parameters

Parameter	Description
to string, required	Recipient phone number. E.164 format recommended (e.g., `+260977000000`). Zambian local formats (`0977000000`) are auto-converted.
message string, required	The SMS content. Standard SMS is 160 characters. Longer messages are split into parts, each costing 1 credit (multi-part uses 153 chars/part).
sender_id string, optional	Approved Sender ID to display. Defaults to `FeltechSMS` if not provided.

Optional Headers

Header	Description
Idempotency-Key string, optional	A unique key per request. If a request with this key succeeded, the same response is returned without sending another SMS (cached 24 hrs).

curl -X POST https://api.feltechsms.com/api/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+260977000000",
    "message": "Hello from Feltech SMS!",
    "sender_id": "FeltechSMS"
  }'

const response = await fetch(
  'https://api.feltechsms.com/api/v1/sms/send',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+260977000000',
      message: 'Hello from Feltech SMS!',
      sender_id: 'FeltechSMS'
    })
  }
);
const data = await response.json();

$ch = curl_init('https://api.feltechsms.com/api/v1/sms/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'to'        => '+260977000000',
    'message'   => 'Hello from Feltech SMS!',
    'sender_id' => 'FeltechSMS'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);

Response (200 OK)

{
  "status": "success",
  "message_id": "msg_42"
}

Response (402 Insufficient Balance)

{
  "status": "error",
  "message": "Insufficient SMS balance.",
  "required": 1,
  "available": 0
}

POST /api/v1/sms/send-bulk

Send Bulk SMS

Sends the same SMS message to multiple recipients in one call. Up to 500 numbers per request. Credits deducted = message parts × number of recipients.

Body Parameters

Parameter	Description
to array of strings, required	Array of recipient phone numbers (min 1, max 500). E.164 format or supported Zambian local formats. e.g. `["+260977000000", "+260955111111"]`
message string, required	The SMS content sent to all recipients.
sender_id string, optional	Approved Sender ID. Defaults to `FeltechSMS`.

curl -X POST https://api.feltechsms.com/api/v1/sms/send-bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+260977000000", "+260955111111"],
    "message": "Special offer valid today only!",
    "sender_id": "FeltechSMS"
  }'

const response = await fetch(
  'https://api.feltechsms.com/api/v1/sms/send-bulk',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: ['+260977000000', '+260955111111'],
      message: 'Special offer valid today only!',
      sender_id: 'FeltechSMS'
    })
  }
);
const data = await response.json();

$ch = curl_init('https://api.feltechsms.com/api/v1/sms/send-bulk');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'to'        => ['+260977000000', '+260955111111'],
    'message'   => 'Special offer valid today only!',
    'sender_id' => 'FeltechSMS'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);

Response (200 OK)

{
  "status": "success",
  "batch_id": "batch_1743601234",
  "queued": 2,
  "log_ids": [101, 102]
}

GET /api/v1/sms/status/{message_id}

Check Message Status

Retrieves the delivery status of a previously sent SMS. The message_id is returned in the send response (e.g. msg_42). Possible delivery_status values: pending, sent, failed.

Path Parameters

Parameter	Description
message_id string, required	The `message_id` returned when the message was sent (format: `msg_{id}`).

curl -X GET \
  https://api.feltechsms.com/api/v1/sms/status/msg_42 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.feltechsms.com/api/v1/sms/status/msg_42',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();

$ch = curl_init(
  'https://api.feltechsms.com/api/v1/sms/status/msg_42'
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);
$response = curl_exec($ch);
curl_close($ch);

Response (200 OK)

{
  "status": "success",
  "data": {
    "message_id": "msg_42",
    "delivery_status": "sent",
    "Sent_at": "2026-04-02T12:00:00.000000Z"
  }
}

GET /api/sms/logs

SMS Logs

Returns a paginated list of all SMS messages sent by the authenticated API key's account. Results are ordered newest first (20 per page).

Query Parameters

Parameter	Description
search string, optional	Filter by recipient phone number or message content.
status string, optional	Filter by delivery status. Values: `Pending`, `Sent`, `Failed`.

curl -X GET \
  "https://api.feltechsms.com/api/sms/logs?status=Sent" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.feltechsms.com/api/sms/logs?status=Sent',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();

Response (200 OK)

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 42,
        "recipient": "+260977000000",
        "message": "Hello from Feltech SMS!",
        "sender_id": "FeltechSMS",
        "status": "Sent",
        "cost": 1,
        "sent_at": "2026-04-02T12:00:00.000000Z",
        "created_at": "2026-04-02T11:59:55.000000Z"
      }
    ],
    "per_page": 20,
    "total": 1
  }
}

POST /api/sender-ids

Request a Sender ID

Submits a new Sender ID request for review. Once approved by an admin, you can use it in your SMS requests. Sender ID names are limited to 11 characters (GSM standard). You cannot request a name you've already submitted.

Body Parameters

Parameter	Description
name string, required	The Sender ID text (max 11 characters). This is what recipients see as the sender.
use_case string, required	Describe how you intend to use this Sender ID (e.g. "Promotional offers for e-commerce store").

curl -X POST \
  https://api.feltechsms.com/api/sender-ids \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FeltechSMS",
    "use_case": "Promotional offers for e-commerce"
  }'

const response = await fetch(
  'https://api.feltechsms.com/api/sender-ids',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'FeltechSMS',
      use_case: 'Promotional offers for e-commerce'
    })
  }
);
const data = await response.json();

Response (201 Created)

{
  "id": 7,
  "user_id": 3,
  "name": "FeltechSMS",
  "use_case": "Promotional offers for e-commerce",
  "status": "Pending",
  "created_at": "2026-04-02T12:00:00.000000Z"
}

Response (409 Conflict — already requested)

{
  "message": "You have already requested this Sender ID."
}

Errors

The API uses standard HTTP status codes. All error responses include a JSON body with a message field and sometimes a status field.

Code	Meaning
200 OK	Request succeeded.
201 Created	Resource was created successfully.
401 Unauthorized	Missing or invalid `Authorization` header / API key.
402 Payment Required	Insufficient SMS balance. Top up your account to continue sending.
409 Conflict	The resource already exists (e.g. duplicate Sender ID request).
422 Unprocessable	Validation failed. Check the `errors` field for field-level details.
429 Too Many Requests	Rate limit exceeded. Wait before retrying.
500 / 502 / 503	Server error on our end. Please retry with exponential back-off.