Metadata-Version: 2.4
Name: yousend
Version: 0.1.0
Summary: Official Python SDK for the YouSend email API
Project-URL: Homepage, https://github.com/Armonika-dz/Yousend-SDK/tree/main/python
Project-URL: Repository, https://github.com/Armonika-dz/Yousend-SDK
Project-URL: Documentation, https://api.yousend.app
Project-URL: Issues, https://github.com/Armonika-dz/Yousend-SDK/issues
License: MIT
License-File: LICENSE
Keywords: api,email,smtp,transactional,yousend
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# yousend (Python)

Official Python SDK for the [YouSend](https://yousend.app) email API. Zero dependencies (stdlib only), Python 3.8+.

## Install

```bash
pip install yousend
```

## Quick start

```python
from yousend import YouSend

ys = YouSend("ys_live_...")

resp = ys.emails.send(
    from_="hello@yourdomain.com",
    to="customer@example.com",
    subject="Welcome aboard",
    html="<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    track_opens=True,
    track_clicks=True,
)
print(resp["messages"][0]["id"])
```

> `from` is a Python keyword, so the send parameter is `from_`.

## Sending

```python
# Multiple recipients
ys.emails.send(from_=sender, to=["a@x.com", "b@x.com"], subject=s, html=h)

# Template + variables
ys.emails.send(from_=sender, to=to, template="welcome", data={"name": "Sam"})

# Idempotent send (safe to retry)
ys.emails.send(from_=sender, to=to, subject=s, html=h, idempotency_key="order-1234")

# Batch — up to 100, one recipient each
ys.emails.batch([
    {"from_": sender, "to": "a@x.com", "subject": s, "html": h},
    {"from_": sender, "to": "b@x.com", "subject": s, "html": h},
])

# Retrieve / list
email = ys.emails.get(message_id)
recent = ys.emails.list(status="delivered", limit=50)
```

## Other resources

```python
ys.domains.create("yourdomain.com")   # returns DNS records to publish
ys.domains.verify(domain_id)
ys.templates.upsert(name="welcome", subject="Hi {{name}}", html="<p>Hi {{name}}</p>")
ys.webhooks.create(url="https://you.com/hooks", events=["email.delivered", "email.opened"])
ys.suppressions.add("bounced@x.com")
ys.api_keys.create("live")            # returns the key once
```

## Verifying webhooks

Pass the **raw** request body — not a re-serialized dict.

### Flask

```python
from flask import Flask, request
from yousend import verify_webhook, YouSendError

app = Flask(__name__)

@app.post("/webhooks/yousend")
def hook():
    try:
        event = verify_webhook(request.get_data(), request.headers.get("Courier-Signature"), SECRET)
    except YouSendError:
        return "", 400
    if event["type"] == "email.clicked":
        print("clicked", event["data"]["url"])
    return "", 200
```

### FastAPI

```python
from fastapi import FastAPI, Request, Response
from yousend import verify_webhook, YouSendError

app = FastAPI()

@app.post("/webhooks/yousend")
async def hook(request: Request):
    raw = await request.body()
    try:
        event = verify_webhook(raw, request.headers.get("Courier-Signature"), SECRET)
    except YouSendError:
        return Response(status_code=400)
    return Response(status_code=200)
```

## Errors

```python
from yousend import YouSend, YouSendError

try:
    ys.emails.send(from_=sender, to=to, subject=s, html=h)
except YouSendError as e:
    print(e.status, e.code, e.message)
```

## License

MIT
