Metadata-Version: 2.4
Name: pysmscenter
Version: 0.1.3
Summary: Unofficial Python SDK for smscenter.gr REST API
Author: Alex Dotis
License: MIT License
        
        Copyright (c) 2026 alexdotis
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/alexdotis/PySMSCenter
Project-URL: Repository, https://github.com/alexdotis/PySMSCenter
Project-URL: Issues, https://github.com/alexdotis/PySMSCenter/issues
Keywords: sms,smscenter,sms-api,bulk-sms,2fa,hlr,sdk,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32
Requires-Dist: email-validator>=2.3
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: pytest-mock>=3.15; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: vcrpy>=8; extra == "dev"
Dynamic: license-file

# PySMSCenter

A typed Python SDK for integrating with the SMSCenter REST API.

[![PyPI](https://img.shields.io/pypi/v/pysmscenter)](https://pypi.org/project/pysmscenter/)
![Python](https://img.shields.io/badge/python-3.12%2B-blue)
[![CI](https://github.com/alexdotis/PySMSCenter/actions/workflows/ci.yaml/badge.svg)](https://github.com/alexdotis/PySMSCenter/actions)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-production--ready-success)

> **Unofficial** Python SDK for smscenter.gr - not affiliated with or endorsed by SMSCenter.

PySMSCenter is a modern, fully-typed Python SDK for integrating with the SMSCenter REST API.
It provides a structured and well-tested interface for sending SMS messages, managing contacts and groups, performing HLR lookups, handling bulk campaigns, and implementing two-factor authentication (2FA) workflows.

📘 Official API Documentation: https://smscenter.gr/api/docs/en

## ✨ Features

- 📱 Send Single SMS
- 📤 Send Bulk SMS
- 📊 Check Account Balance
- 📖 SMS History (Single & Grouped)
- 📬 Delivery Status Tracking
- 👤 Contact Management
- 👥 Group Management
- 🔐 Two-Factor Authentication (2FA)
- 🔎 HLR Lookup
- 👥 Sub-account Management
- 🔁 Automatic Retry Support
- ⚠️ Domain-Specific Exceptions
- 🧪 Fully Tested
- 🐍 Python 3.12+

---

## Planned Features

- **Viber Management**

## 🔧 Requirements

- Python 3.12+

## 📦 Installation

```bash
pip install pysmscenter
```

### Development installation

```bash
git clone https://github.com/alexdotis/PySMSCenter.git
cd PySMSCenter
pip install -e ".[dev]"
```

## ⚡ Quick Example

```python
from pysmscenter import SMSClient

with SMSClient("your_api_key") as client:
    client.sms.send(
        to="306912345678",
        text="Hello from PySMSCenter!",
        sender="MyApp"
    )
```

---

## 🔐 Authentication

You need an API key from:

https://smscenter.gr/api/docs/en

### Using API Key

```python
from pysmscenter import SMSClient

client = SMSClient("your_api_key")
```

### Using Username & Password

```python
from pysmscenter import SMSClient

client = SMSClient.from_credentials("username", "password")
```

---

## 🚀 Basic Usage

### Context Manager (Recommended)

```python
from pysmscenter import SMSClient

with SMSClient("your_api_key") as client:
    balance = client.balance.check()
    print(balance.get("balance"))
```

---

## 📱 SMS

### Send Single SMS

```python
client.sms.send(
    to="306912345678",
    text="Hello World",
    sender="MyApp"
)
```

### Send Bulk SMS

```python
numbers = ["306912345678", "306912345679"]

client.sms.bulk(
    to=numbers,
    text="Bulk message",
    sender="MyApp"
)
```

### Cancel Scheduled SMS

```python
client.sms.cancel("sms_id_here")
```

## 📊 Account & Status

### Check Balance

```python
client.balance.check()
```

### Check Delivery Status

```python
client.status.sms("sms_id_here")
```

### Get Recent Status Reports

```python
client.status.get()
```

---

## 📖 History

### Single SMS History

```python
client.history.single_list()
```

### Grouped SMS History

```python
client.history.group_list()
```

---

## 👤 Contacts

### List Contacts

```python
client.contact.list()
```

### Add Contact

```python
client.contact.add(
    mobile="306912345678",
    name="John",
    surname="Doe",
)
```

### Update Contact

```python
client.contact.update(
    contact_id="12345",
    name="Updated Name"
)
```

### Delete Contact

```python
client.contact.delete("12345")
```

---

## 👥 Groups

### Create Group

```python
client.group.add("Customers")
```

### Add Contact to Group

```python
client.group.add_contact(
    group_id="123",
    contact_id="456"
)
```

### Remove Contact from Group

```python
client.group.delete_contact(
    group_id="123",
    contact_id="456"
)
```

---

## 🔎 Mobile & HLR

### Validate Mobile Number

```python
client.mobile.check("306912345678")
```

### HLR Lookup

```python
client.hlr.lookup("306912345678")
```

---

## 🔐 Two Factor Authentication

### Send 2FA Code

```python
response = client.two_factor.send(
    to="306912345678",
    text="Your verification code is %%code%%"
)
```

### Verify 2FA Code

```python
client.two_factor.check(
    auth_id="auth_id_from_send",
    code="1234"
)
```

---

## 👥 Sub-Accounts

### Create Sub-Account

```python
client.user.add(
    email="subaccount@example.com",
    password="securepassword"
)
```

### Top-up Sub-Account

```python
client.user.topup(
    user_id="12345",
    sms="10",
    cost="5"
)
```

---

## ⚠️ Error Handling

All API errors raise domain-specific exceptions:

```python
from pysmscenter.exceptions import SMSExceptionError

try:
    client.sms.send(...)
except SMSExceptionError as exc:
    print("Error code:", exc.code)
    print("Message:", exc.message)
```

Credential issues raise:

```python
from pysmscenter.exceptions import CredentialError
```

---

## 🧪 Testing

Run the test suite:

```bash
pytest
```

## 📄 License

MIT License

---

## 🤝 Contributing

Contributions are welcome.  
Please open an issue or submit a pull request.

## Keywords

Python SMS SDK, SMS API client, Bulk SMS Python, SMS Gateway integration, SMSCenter API wrapper, SMS REST client, Two Factor Authentication API, HLR Lookup API, Python messaging library
