Metadata-Version: 2.4
Name: connectmedia-sms
Version: 1.0.0
Summary: Official Python client for the Connect Media SMS API: bulk SMS to Safaricom, Airtel and Telkom in Kenya and 190+ countries.
Author-email: Connect Media <info@connectmedia.co.ke>
License: MIT
Project-URL: Homepage, https://connectmedia.co.ke/
Project-URL: Documentation, https://connectmedia.co.ke/developers/
Project-URL: Pricing, https://connectmedia.co.ke/pricing/
Project-URL: Source, https://github.com/connectmedia-ke/connectmedia-python
Project-URL: Issues, https://github.com/connectmedia-ke/connectmedia-python/issues
Keywords: sms,bulk sms,kenya,safaricom,airtel,sms api,connect media
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Connect Media SMS for Python

Official Python client for the [Connect Media](https://connectmedia.co.ke/) SMS API. Send bulk and transactional SMS to Safaricom, Airtel and Telkom numbers in Kenya and to 190+ countries, check your balance, read sent history with delivery status and receive customer replies.

## Get an API key

1. Create a free account at [dashboard.connectmedia.co.ke](https://dashboard.connectmedia.co.ke/).
2. Generate a 64-character API key under **Profile, then API keys**.
3. Top up any amount and register a sender ID (see [sender ID registration in Kenya](https://connectmedia.co.ke/sender-id-registration-kenya/)).

## Install

```bash
pip install connectmedia-sms
```

## Usage

```python
from datetime import datetime
from connectmedia_sms import Client, ConnectMediaError

client = Client("YOUR_64_CHARACTER_API_KEY")

try:
    client.send("0712345678", "Your order has shipped.", sender="YourBrand")
    client.send(["0712345678", "0733000111"], "Fees are due on Friday.", sender="YourSchool",
                schedule_at=datetime(2026, 12, 1, 9, 0))
    print(client.balance())
    print(client.history(limit=10))
    print(client.inbox(limit=10))
except ConnectMediaError as e:
    print(e.code, e.message)
```

## Response codes

| Action | Success code |
|---|---|
| send | 201 |
| balance | 200 |
| history | 202 |
| inbox | 302 |

Any other code raises an error carrying the API's `code` and `message` (for example `100` invalid API key, `101` insufficient balance, `104` invalid recipients, `105` invalid message, `500` server error). Network failures use code `network`; a non-JSON reply uses `invalid_response`.

Numbers are normalised for you: `0712345678`, `+254 712 345 678` and `254712345678` all become `254712345678`. International numbers are passed through without punctuation.

## Tests

```bash
python -m unittest discover -s tests -t .
```

## Links

- Website: [connectmedia.co.ke](https://connectmedia.co.ke/)
- API documentation: [connectmedia.co.ke/developers](https://connectmedia.co.ke/developers/)
- Pricing (SMS from KES 1.0, no minimum top-up, credit never expires): [connectmedia.co.ke/pricing](https://connectmedia.co.ke/pricing/)
- Bulk SMS API for Kenya: [connectmedia.co.ke/bulk-sms-api-kenya](https://connectmedia.co.ke/bulk-sms-api-kenya/)
- Support: info@connectmedia.co.ke · +254 707 339 945

## License

MIT
