kwtsms 0.2.0

Python client for the kwtSMS API (kwtsms.com)

kwtsms

Python client for the kwtSMS API — Kuwait SMS gateway.

Zero external dependencies. Python 3.8+.

Install

pip install kwtsms

Quick start

from kwtsms import KwtSMS

sms = KwtSMS.from_env()                              # reads .env or env vars
ok, balance, err = sms.verify()                      # test credentials
result = sms.send("96598765432", "Your OTP is: 123456")
result = sms.send("96598765432", "Hello", sender="MY-APP")  # override sender
result = sms.send(["96598765432", "[phone]"], "Hello!")  # multiple numbers

# Every error response includes an 'action' field with developer guidance
if result["result"] == "ERROR":
    print(result["code"])        # e.g. "ERR003"
    print(result["description"]) # human-readable error
    print(result["action"])      # what to do next

# Invalid numbers are reported per-number, not raised
result = sms.send(["96598765432", "abc", "[e-mail]"], "Hi")
# result["invalid"] → [{"input": "abc", "error": "..."}, ...]

report = sms.validate(["96598765432", "[phone]", "123"])
# report["ok"] → valid, report["er"] → format error, report["nr"] → no route
# report["rejected"] → pre-rejected with per-number error messages
balance = sms.balance()

Utility functions

from kwtsms import normalize_phone, validate_phone_input, clean_message

normalize_phone("[phone]")       # → "96598765432"
validate_phone_input("[e-mail]")  # → (False, "is an email address...", "")
validate_phone_input("[phone]")    # → (True, None, "96598765432")
clean_message("OTP: ١٢٣٤٥٦ 🎉")       # → "OTP: 123456 "

Configuration

Create a .env file (or set environment variables):

KWTSMS_USERNAME=your_api_user
KWTSMS_PASSWORD=your_api_pass
KWTSMS_SENDER_ID=YOUR-SENDERID   # use KWT-SMS for testing only
KWTSMS_TEST_MODE=1                # 1 = test (safe default), 0 = live
KWTSMS_LOG_FILE=kwtsms.log

Or run the setup wizard:

kwtsms setup

CLI

kwtsms setup                                  # first-time wizard
kwtsms verify
kwtsms balance
kwtsms send 96598765432 "Your OTP is: 123456"
kwtsms validate 96598765432 [phone]

Sender ID

KWT-SMS is a shared sender for testing only. Register a private sender ID on kwtsms.com before going live — use a Transactional sender ID for OTP messages to ensure delivery to DND numbers.

License

MIT