PySMSCenter

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

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

pip install pysmscenter

Development installation

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

⚡ Quick Example

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

from pysmscenter import SMSClient

client = SMSClient("your_api_key")

Using Username & Password

from pysmscenter import SMSClient

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

---

🚀 Basic Usage

Context Manager (Recommended)

from pysmscenter import SMSClient

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

---

📱 SMS

Send Single SMS

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

Send Bulk SMS

numbers = ["306912345678", "306912345679"]

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

Cancel Scheduled SMS

client.sms.cancel("sms_id_here")

📊 Account & Status

Check Balance

client.balance.check()

Check Delivery Status

client.status.sms("sms_id_here")

Get Recent Status Reports

client.status.get()

---

📖 History

Single SMS History

client.history.single_list()

Grouped SMS History

client.history.group_list()

---

👤 Contacts

List Contacts

client.contact.list()

Add Contact

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

Update Contact

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

Delete Contact

client.contact.delete("12345")

---

👥 Groups

Create Group

client.group.add("Customers")

Add Contact to Group

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

Remove Contact from Group

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

---

🔎 Mobile & HLR

Validate Mobile Number

client.mobile.check("306912345678")

HLR Lookup

client.hlr.lookup("306912345678")

---

🔐 Two Factor Authentication

Send 2FA Code

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

Verify 2FA Code

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

---

👥 Sub-Accounts

Create Sub-Account

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

Top-up Sub-Account

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

---

⚠️ Error Handling

All API errors raise domain-specific exceptions:

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:

from pysmscenter.exceptions import CredentialError

---

🧪 Testing

Run the test suite:

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