drin 0.1.0

Official Python SDK for the Drin transactional email API.

drin

Official Python SDK for the Drin transactional email API. Zero dependencies (standard library only), typed, Python 3.8+.

Install

pip install drin

Quick start

from drin import DrinClient

drin = DrinClient(api_key="drin_...")  # or os.environ["DRIN_API_KEY"]

res = drin.emails.send({
    "from": {"email": "[e-mail]", "name": "Acme"},
    "to": [{"email": "[e-mail]"}],
    "subject": "Welcome",
    "html": "<h1>Welcome</h1>",
    "text": "Welcome",
})
print(res["id"], res["status"])

The client defaults to https://api.drin.run; override with base_url. Request bodies are plain dicts whose keys match the REST API; responses are parsed JSON.

Tenant-wide keys

A tenant-wide key must name the sender (its externalId):

drin = DrinClient(api_key, sender="customer_42")
# or per request:
drin.emails.send(body, sender="customer_42")

Idempotency

drin.emails.send(body, idempotency_key="order-1234")  # honored 24h, per sender

Pagination

Every list endpoint returns {"data": [...], "nextCursor": ...}. Use paginate(...) to walk every page lazily:

for message in drin.emails.paginate({"status": "delivered"}):
    print(message["id"])

Typed errors

from drin import DrinRateLimitError, DrinSuppressedError, DrinError

try:
    drin.emails.send(body)
except DrinRateLimitError as e:
    time.sleep(e.retry_after or 1)
except DrinSuppressedError:
    ...  # all recipients suppressed
except DrinError as e:
    print(e.type, e.status, e.code)

Webhook verification

Verify the Drin-Signature header on inbound webhooks. Pass the raw request body. Pure local check — no network call.

from drin import verify_webhook, DrinWebhookVerificationError

# e.g. in a Flask/Django/FastAPI handler:
raw_body = request.get_data(as_text=True)        # the exact bytes received
signature = request.headers["Drin-Signature"]

try:
    result = verify_webhook(raw_body, signature, signing_secret, tolerance_seconds=300)
    event = result.payload  # trusted only AFTER verification
except DrinWebhookVerificationError:
    abort(400)

Resources

drin.emails · drin.domains · drin.inboxes · drin.threads · drin.inbound · drin.webhooks · drin.suppressions · drin.api_keys · drin.metrics · drin.templates · drin.contacts · drin.forms — one method per /v1 endpoint.

A first-party TypeScript SDK is also available: npm install @drin/sdk.

License

MIT