cloudsms 1.0.1
Python SDK for CloudSMS API
Requires Python: >=3.6

# CloudSMS Python SDK

A Python SDK for the CloudSMS API, allowing you to easily integrate SMS functionality into your Python applications.

## Installation

You can install the package using pip:

```bash
pip install cloudsms
```

## Requirements

- Python 3.6 or higher
- requests>=2.25.0

## Quick Start

```python
from cloudsms import CloudSMSClient

# Initialize the client
client = CloudSMSClient(
    api_token="your-api-token",
    sender_id="your-sender-id"
)

# Test the connection
test_response = client.test_connection()
print(test_response["status"])  # 'success' or 'error'

# Check your balance
balance_response = client.get_balance()
if balance_response["status"] == "success":
    print(f"Current balance: {balance_response['data']}")

# Send an SMS
sms_response = client.send_sms(
    phone_number="+1234567890",
    message="Hello from CloudSMS!"
)
if sms_response["status"] == "success":
    print("SMS sent successfully!")
else:
    print(f"Error: {sms_response['message']}")
```

## API Reference

### CloudSMSClient

The main class for interacting with the CloudSMS API.

#### Constructor

```python
client = CloudSMSClient(api_token: str = "", sender_id: str = "")
```

- `api_token`: Your CloudSMS API token
- `sender_id`: Your CloudSMS sender ID

#### Methods

##### get_balance()

Get your current account balance.

```python
response = client.get_balance()
```

Returns:
```python
{
    "status": "success",
    "data": "100.00"  # Balance amount without currency symbol
}
```

##### test_connection()

Test the API connection.

```python
response = client.test_connection()
```

Returns:
```python
{
    "status": "success",
    "message": "Connection successful! Your account is properly configured."
}
```

##### send_sms(phone_number: str, message: str)

Send an SMS message.

```python
response = client.send_sms(
    phone_number="+1234567890",
    message="Hello from CloudSMS!"
)
```

Returns:
```python
{
    "status": "success",
    "success": True
}
```

## Error Handling

All methods return a dictionary with at least a "status" key that can be either "success" or "error". When an error occurs, the response will include an error message:

```python
{
    "status": "error",
    "message": "Error description here"
}
```
## Usage

### Initialize the SDK

```python
from gsoftware_sms import GSoftwareSMS

# Initialize with your API token and base URL
sms = GSoftwareSMS(
    api_token='your_api_token_here',
    base_url='https://your-gsoftware-instance.com'
)
```

### Send SMS to Single Number

```python
response = sms.send_sms(
    recipient='31612345678',
    sender_id='YourName',
    message='This is a test message'
)
print(response)
```

### Send SMS to Multiple Numbers

```python
response = sms.send_sms(
    recipient=['31612345678', '8801721970168'],
    sender_id='YourName',
    message='This is a test message'
)
print(response)
```

### Schedule an SMS

```python
from datetime import datetime

scheduled_time = datetime(2024, 12, 20, 7, 0)  # Year, Month, Day, Hour, Minute
response = sms.send_sms(
    recipient='31612345678',
    sender_id='YourName',
    message='This is a scheduled message',
    schedule_time=scheduled_time
)
print(response)
```

### Send Campaign to Contact Lists

```python
response = sms.send_campaign(
    contact_list_ids=['6415907d0d37a', '6415907d0d7a6'],
    sender_id='YourName',
    message='This is a campaign message'
)
print(response)
```

### Get SMS Details

```python
# Get details of a specific SMS
sms_details = sms.get_sms('606812e63f78b')
print(sms_details)

# List all SMS messages
all_messages = sms.list_sms()
print(all_messages)
```

### Get Campaign Details

```python
campaign_details = sms.get_campaign('campaign_uid_here')
print(campaign_details)
```

## Response Format

All methods return a dictionary with the following structure:

### Success Response
```json
{
    "status": "success",
    "data": "response data here"
}
```

### Error Response
```json
{
    "status": "error",
    "message": "A human-readable description of the error"
}
```

## Requirements

- Python 3.6 or higher
- requests>=2.25.1
- python-dateutil>=2.8.2

## License

This project is licensed under the MIT License.
## License

This project is licensed under the MIT License.

## Support

For support, please visit [https://cloudsms.gr](https://cloudsms.gr) or contact info@gsoftware.gr.