Metadata-Version: 2.3
Name: smsir-sdk
Version: 1.0.1
Summary: Python client for the SMS.ir REST API
Author: saeid
Author-email: saeid <samani0019@gmail.com>
License: MIT License
         
         Copyright (c) 2026 Saeid Ghafari
         
         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.
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.13
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/Youknow-sys/smsir
Project-URL: Repository, https://github.com/Youknow-sys/smsir
Project-URL: Issues, https://github.com/Youknow-sys/smsir/issues
Description-Content-Type: text/markdown

# smsir

Python client for the [SMS.ir](https://sms.ir) REST API.

## Installation

```bash
pip install smsir-sdk
```

## Requirements

- Python >= 3.12
- httpx
- pydantic

## Usage

### Create Client

```python
from smsir import SMSIRClient

client = SMSIRClient("your-api-key")
```

Async client is also available:

```python
from smsir import AsyncSMSIRClient

async with AsyncSMSIRClient("your-api-key") as client:
    ...
```

### Send Bulk SMS

Send a message to multiple recipients from your dedicated line:

```python
from smsir import SMSIRClient
from smsir.endpoints import BulkSend

client = SMSIRClient("your-api-key")
result = client.execute(BulkSend(
    line_number=30004505000017,
    message_text="Your message here",
    mobiles=["09121234567", "09191234567"],
))
print(result.pack_id, result.message_ids, result.cost)
```

### Send Like-to-Like SMS

Send different messages to different numbers, paired one-to-one:

```python
from smsir.endpoints import LikeToLikeSend

result = client.execute(LikeToLikeSend(
    line_number=30004505000017,
    message_texts=["Message for user 1", "Message for user 2"],
    mobiles=["09121234567", "09191234567"],
))
```

### Send Scheduled SMS

Add `send_datetime` to any send endpoint for scheduled delivery:

```python
from datetime import datetime, timedelta

result = client.execute(BulkSend(
    line_number=30004505000017,
    message_text="Scheduled message",
    mobiles=["09121234567"],
    send_datetime=datetime.now() + timedelta(hours=2),
))
```

### Cancel Scheduled SMS

```python
from smsir.endpoints import CancelScheduledSend

result = client.execute(CancelScheduledSend(pack_id="2b99e63c-9bf8-4a21-..."))
print(result.returned_credit_count, result.sms_count)
```

### Send Verification Code

Send OTP/verification codes using a predefined template:

```python
from smsir.endpoints import VerifySend

result = client.execute(VerifySend(
    mobile="09191234567",
    template_id=123456,
    parameters={"Code": "12345"},
))
print(result.message_id, result.cost)
```

### Send via URL

Send a single SMS using username/password authentication:

```python
from smsir.endpoints import SendByURL

result = client.execute(SendByURL(
    username="your-username",
    password="your-api-key",
    line=30004505000017,
    mobile="09121234567",
    text="Hello!",
))
```

### Message Report

Get the status of a specific message:

```python
from smsir.endpoints import MessageReport

report = client.execute(MessageReport(message_id=86522023))
print(report.delivery_state, report.cost)
```

### Pack Report

Get all messages in a send pack:

```python
from smsir.endpoints import PackReport

messages = client.execute(PackReport(pack_id="2b99e63c-9bf8-4a21-..."))
for msg in messages:
    print(msg.mobile, msg.delivery_state)
```

### Pack List Report

List all send packs from today:

```python
from smsir.endpoints import PackListReport

packs = client.execute(PackListReport(page_size=50, page_number=1))
```

### Live Send Report

Get today's sent messages:

```python
from smsir.endpoints import LiveSendReport

messages = client.execute(LiveSendReport(page_size=100, page_number=1))
```

### Archived Send Report

Get sent messages from previous days:

```python
from datetime import datetime
from smsir.endpoints import ArchiveSendReport

messages = client.execute(ArchiveSendReport(
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 6, 1),
    page_size=100,
))
```

### Latest Received Messages

Get the most recent unread received messages:

```python
from smsir.endpoints import LatestReceive

messages = client.execute(LatestReceive(count=50))
```

### Live Received Messages

Get today's received messages:

```python
from smsir.endpoints import LiveReceive

messages = client.execute(LiveReceive(
    page_size=20,
    page_number=1,
    sort_by_newest=True,
))
```

### Archived Received Messages

Get received messages from previous days:

```python
from smsir.endpoints import ArchiveReceive

messages = client.execute(ArchiveReceive(
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 6, 1),
))
```

### Get Credit

Get your current account credit:

```python
from smsir.endpoints import GetCredit

credit = client.execute(GetCredit())
print(credit)  # 165.3
```

### Get Line Numbers

Get your available send lines:

```python
from smsir.endpoints import GetLines

lines = client.execute(GetLines())
print(lines)  # [10002155613464, 30004505000017]
```

## Error Handling

```python
from smsir.exceptions import APIError, AuthenticationError, RateLimitError

try:
    client.execute(BulkSend(...))
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests")
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.api_status}")  # StatusCode enum
```

## License

MIT
