Metadata-Version: 2.4
Name: sending-sdk
Version: 0.1.0
Summary: SDK Python ufficiale per l'API di Sending.dev (email + WhatsApp + Telegram)
Project-URL: Homepage, https://sending.dev
Project-URL: Documentation, https://sending.dev/api-reference
Author: Sending.dev
License: MIT
Keywords: api,email,sdk,sending,telegram,whatsapp
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic[email]>=2
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# sending-sdk

SDK Python ufficiale per l'[API di Sending.dev](https://sending.dev) (email + WhatsApp + Telegram).

I modelli Pydantic sono generati dallo spec OpenAPI; il client e' scritto a mano per la migliore DX.

## Installazione

```bash
pip install sending-sdk
```

Si importa come `sending`:

```python
from sending import Sending
```

Richiede Python >= 3.10.

## Uso

```python
from sending import Sending

client = Sending(api_key="sk_...")

# Email transazionale (accetta un dict oppure un modello Pydantic)
client.emails.send({
    "to": "cliente@esempio.com",
    "from": "you@tuodominio.com",
    "subject": "Benvenuto",
    "html": "<p>Ciao!</p>",
    "idempotencyKey": "welcome-001",
})

# Messaggio multi-canale
client.messages.send({
    "channel": "whatsapp",
    "to": "+393331234567",
    "text": "Ciao!",
    "idempotencyKey": "wa-001",
})
```

Come context manager (chiude la connessione httpx):

```python
with Sending(api_key="sk_...") as client:
    page = client.contacts.list(q="mario", page=1, page_size=50)
    print(page["total"], page["data"])
```

### Client asincrono

Stessa API, su `httpx.AsyncClient`:

```python
import asyncio
from sending import AsyncSending

async def main():
    async with AsyncSending(api_key="sk_...") as client:
        await client.emails.send({
            "to": "cliente@esempio.com",
            "from": "you@tuodominio.com",
            "subject": "Benvenuto",
            "html": "<p>Ciao!</p>",
            "idempotencyKey": "welcome-001",
        })
        page = await client.contacts.list(q="mario", page=1, page_size=50)
        print(page["total"])

asyncio.run(main())
```

### Modelli tipizzati (opzionali)

```python
from sending import models

body = models.SendEmailInput(
    to="a@b.com", **{"from": "you@dominio.com"},
    subject="Ciao", html="<p>Hi</p>", idempotencyKey="welcome-001",
)
client.emails.send(body)  # serializzato con gli alias corretti (es. "from")
```

### Gestione errori

```python
from sending import SendingError

try:
    client.emails.send({...})
except SendingError as err:
    print(err.status, err.code, err.body)
```

## Risorse disponibili

`emails` · `messages` · `events` · `campaigns` · `contacts` · `lists` · `tags` ·
`custom_fields` · `segments` · `domains` · `inboxes` · `email_rules` · `automations` ·
`webhooks` · `utm` · `integrations` · `usage`.

## Sviluppo

```bash
pip install -e ".[dev]"
python scripts/gen.py   # rigenera sending/models.py da openapi.json
pytest
```

Lo `openapi.json` viene copiato qui da `pnpm openapi:generate` (package `@sending/openapi`).
