Metadata-Version: 2.4
Name: txtmsg-sdk
Version: 1.0.0
Summary: Official Python SDK for TXTMSG.lk SMS Gateway API v3 — Send bulk SMS, transactional SMS, campaigns, and manage contacts from Python
Author-email: "TXTMSG.lk" <support@txtmsg.lk>
License: MIT
Project-URL: Homepage, https://txtmsg.lk
Project-URL: Repository, https://github.com/txtmsglk/txtmsg-python-sdk
Project-URL: Documentation, https://documentation.txtmsg.lk
Keywords: txtmsg,sms,sms-gateway,sri-lanka,bulk-sms,sms-api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: async
Requires-Dist: httpx>=0.27.0; extra == "async"

# TXTMSG.lk Python SDK — Python SMS Gateway Integration for Sri Lanka

Official Python SDK for [TXTMSG.lk](https://txtmsg.lk) SMS Gateway API v3. Send bulk SMS, transactional SMS, campaigns, and manage contacts from any Python 3.9+ application. The reliable Python SMS client for Sri Lanka's leading SMS gateway.

## Features

- **Send SMS** — Deliver single or bulk messages to any country via REST API
- **Campaign Management** — Send SMS campaigns using contact lists
- **Contact Groups** — Create, update, and manage contact groups
- **Contacts** — Import and manage individual contacts within groups
- **Schedule Messages** — Set future delivery times for your SMS
- **Balance & Profile** — Check remaining SMS units and account details
- **DLT Support** — Send DLT-compliant messages with template IDs
- **httpx** — Modern HTTP client with sync and async support
- **Type Hints** — Full type annotations for IDE autocompletion

## Requirements

- Python 3.9+

## Installation

```bash
pip install txtmsg-sdk
```

## Quick Start

### Send an SMS

```python
from txtmsg import TxtmsgClient

client = TxtmsgClient(api_key="your-api-key-here")

response = client.send_sms(
    recipient="94771234567",
    sender_id="TXTMSG",
    message="Hello from TXTMSG.lk!",
)

print(response)
```

### Check Balance

```python
balance = client.view_balance()
print(balance["data"]["remaining_balance"])
```

### Send a Campaign

```python
client.send_campaign(
    contact_list_id="6415907d0d37a",
    sender_id="TXTMSG",
    message="Campaign message",
    schedule_time="2025-12-20 07:00",
)
```

## API Reference

### Client

```python
TxtmsgClient(api_key: str, base_url: str | None = None, http_client: httpx.Client | None = None)
```

### SMS Operations

| Method | Description |
|--------|-------------|
| `send_sms(recipient, sender_id, message, ...)` | Send SMS via POST |
| `send_campaign(contact_list_id, sender_id, message, ...)` | Send campaign to contact list(s) |
| `view_sms(uid)` | View details of a sent SMS |
| `view_all_messages()` | List all sent messages |
| `view_campaign(uid)` | View campaign details |

### Contact Groups

| Method | Description |
|--------|-------------|
| `view_all_contact_groups()` | Retrieve all contact groups |
| `create_contact_group(name)` | Create a new contact group |
| `view_contact_group(group_id)` | Get group details |
| `update_contact_group(group_id, name)` | Update a group |
| `delete_contact_group(group_id)` | Delete a group |

### Contacts

| Method | Description |
|--------|-------------|
| `create_contact(group_id, phone, ...)` | Add a contact to a group |
| `view_contact(group_id, uid)` | View contact details |
| `update_contact(group_id, uid, ...)` | Update a contact |
| `delete_contact(group_id, uid)` | Delete a contact |
| `view_all_contacts_in_group(group_id)` | List contacts in a group |

### Account

| Method | Description |
|--------|-------------|
| `view_balance()` | Check remaining SMS units |
| `view_profile()` | View account profile |

## Error Handling

```python
from txtmsg import TxtmsgClient, TxtmsgError

client = TxtmsgClient(api_key="your-key")

try:
    client.send_sms(recipient="94771234567", sender_id="TXTMSG", message="Hello")
except TxtmsgError as e:
    print(f"API Error [{e.status_code}]: {e}")
```

## About TXTMSG.lk

[TXTMSG.lk](https://txtmsg.lk) is a Sri Lankan SMS gateway provider offering reliable bulk SMS services, transactional SMS APIs, and messaging solutions for businesses. The API v3 provides RESTful endpoints for SMS delivery, contact management, and campaign automation with worldwide coverage.

## Documentation

- [API Documentation](https://documentation.txtmsg.lk)
- [Postman Collection](https://documenter.getpostman.com/view/21165322/2sB2qf9e5y)

## Support

- Email: support@txtmsg.lk
- Phone: +94 773 59 304 / +94 716 170 000

## License

MIT
