Python SDK

The official drin Python client is a thin wrapper over the REST API — with built-in retries, cursor pagination, typed errors, and local webhook signature verification, and zero third-party dependencies (standard library only). The SDK is published to PyPI as drin. It mirrors the wire contract one-to-one, so anything you can do over REST you can do here with the same request and response shapes.

Requirements. Python 3.8+. The SDK has zero third-party dependencies — the default HTTP backend uses the standard-library urllib. You can inject your own backend (requests / httpx) via the http_handler option.

Install

pip install drin

Create a client

Construct one client and reuse it. The only required argument is api_key; pass sender only when you authenticate with a tenant-wide key (see Authentication).

import os
from drin import DrinClient

drin = DrinClient(
    api_key=os.environ["DRIN_API_KEY"],  # required
    sender="my-project",                 # only for tenant-wide keys
    # base_url="https://api.drin.run",   # default
    # timeout=30.0,                      # per-request timeout in seconds
    # max_retries=2,                     # transient-failure retries
)

The client exposes one resource per area of the API. Each has the create / get / list / delete methods as appropriate:

emails · domains · inboxes · threads · inbound · webhooks
suppressions · contacts · templates · api_keys · metrics · forms

Request bodies are plain dicts whose keys match the REST API wire format (camelCase), e.g. {"from": {...}, "to": [...], "templateId": "..."}. Responses are returned as parsed JSON (dict / list).

Send

emails.send() resolves to a dict carrying the message id you can use to retrieve status or reply later.

res = drin.emails.send({
    "from": {"email": "hello@acme.com", "name": "Acme"},
    "to": [{"email": "customer@example.com"}],
    "subject": "Welcome aboard",
    "html": "<h1>You're in</h1>",
    "text": "You're in",
})
print(res["id"], res["status"])

To pick a verified sending domain in code rather than hard-coding it, use the domains.list_verified() convenience — it auto-pages and returns only the domains a from address may use:

domains = drin.domains.list_verified()
domain = domains[0]

drin.emails.send({
    "from": {"email": f"hello@{domain['domain']}"},
    "to": [{"email": "customer@example.com"}],
    "subject": "Hi",
    "html": "<p>…</p>",
})

Idempotent sends. Pass idempotency_key to make a retry safe — drin.emails.send(body, idempotency_key="order-42"). It is honored for 24h, per sender. See Idempotency & retries.

Paginate

Every list endpoint returns {"data": [...], "nextCursor": ...}. The easiest way to walk all of it is .paginate(), a lazy iterator that fetches each page and stops when nextCursor is empty — re-using whatever filter you passed:

# Walk every bounced message across all pages — no cursor bookkeeping.
for message in drin.emails.paginate({"status": "bounced"}):
    print(message["to"], message["subject"])

When you want to control paging yourself — for cursor-based UIs, say — call .list() and thread the cursor:

# Or take one page at a time and thread the cursor yourself.
page = drin.emails.list({"limit": 50})
print(len(page["data"]), "messages")
if page.get("nextCursor"):
    nxt = drin.emails.list({"cursor": page["nextCursor"]})

paginate() is available on emails, domains, threads, contacts, suppressions, templates, webhooks, api_keys, and forms.

Receive & reply

Inbound mail lands on an inbox and is joined into a thread alongside your outbound messages. Reply in one call — Drin handles the addressing and the threading headers, so the recipient’s mail client threads the conversation correctly:

# One-call threaded reply. From, To, Subject ("Re: …"), and the
# In-Reply-To / References headers are all set for you.
drin.emails.reply(inbound_message_id, {
    "html": "<p>Thanks for reaching out — we're on it.</p>",
})

Verify a webhook

Use verify_webhook() (also exposed as drin.webhooks.verify()) — a pure, local check with no network call. Pass the raw request body (the exact bytes you received, before any JSON parsing) and the Drin-Signature header. It returns the verified result on success and raises DrinWebhookVerificationError on any mismatch.

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,        # the endpoint's signing secret
        tolerance_seconds=300, # optional freshness window; 0 disables it
    )
    event = result.payload     # trusted only AFTER verification
    print(event["type"], event["data"])
except DrinWebhookVerificationError:
    abort(400)

Use the raw body. Most frameworks parse JSON before your handler runs, which re-serializes the bytes and breaks the signature. Capture the raw body (e.g. request.get_data(as_text=True) in Flask) and verify that, not the parsed object.

Typed errors

Every failure is a subclass of DrinError, so you can branch with except or on err.type. The base carries type, status, code, param, request_id, and the raw body.

import time
from drin import (
    DrinError,
    DrinValidationError,
    DrinRateLimitError,
    DrinSuppressedError,
)

try:
    drin.emails.send({ ... })
except DrinSuppressedError:
    # every recipient is suppressed — nothing was sent
    ...
except DrinRateLimitError as err:
    time.sleep((err.retry_after or 1))
except DrinValidationError as err:
    print("Bad field:", err.param, err)
except DrinError as err:
    print(err.type, err.status, err.request_id)

The full set of typed errors: DrinValidationError, DrinAuthenticationError, DrinPermissionError, DrinNotFoundError, DrinConflictError, DrinSuppressedError, DrinRateLimitError, DrinInternalError, and DrinConnectionError (raised on a network failure, timeout, or abort before any HTTP response was received). The SDK auto-retries 429 and 5xx with exponential backoff and full jitter (default 2 retries). A POST is retried only when you supplied an idempotency_key, so a send is never duplicated. See Errors for the full type table.

Next steps

API reference

Every endpoint, parameter, and response shape the SDK wraps.

Other languages

No Python? Call the same REST API from any stack.

Authentication

Project-scoped vs tenant-wide keys, and the sender option.

Webhooks

Subscribe to delivery, bounce, complaint, open, and click events.

Get started

Sending

Receiving

Domains & deliverability

Agents & SDKs

Account

Install

Create a client

Send

Paginate

Receive & reply

Verify a webhook

Typed errors

Next steps

API reference

Other languages

Authentication

Webhooks

​Install

​Create a client

​Send

​Paginate

​Receive & reply

​Verify a webhook

​Typed errors

​Next steps

API reference

Other languages

Authentication

Webhooks

Install

Create a client

Send

Paginate

Receive & reply

Verify a webhook

Typed errors

Next steps