yousend (Python)

Official Python SDK for the YouSend email API. Zero dependencies (stdlib only), Python 3.8+.

Install

pip install yousend

Quick start

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

# 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

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

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

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

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