Buddy Python SDK

After registry publication, install with:

pip install --pre usebuddy

Server-side Python 3.9+ client with no runtime dependencies.

import os
from buddy import Buddy

buddy = Buddy(os.environ["BUDDY_API_KEY"])
account = buddy.me()
buddy.subscribers.create({"phone": "+15550000001", "name": "Amira"})
message = buddy.messages.send({
    "to": "+15550000001",
    "template": "buddy_test_hello",
    "variables": ["Amira"],
}, idempotency_key="my-first-test-message")
print(message["data"]["id"])

Use a test key for this example. Every operation is also available by its OpenAPI operation ID: buddy.call("getMessage", path={"id": message_id}). Use buddy.paginate("listSubscribers", query={"limit": 50}) to iterate all pages.

POST calls create one idempotency key and retain it across bounded retries. Supply a stable key for retries across process restarts. PATCH is not retried. Redirects are refused so credentials are never forwarded to a new location. Replayed server failures are surfaced immediately; never change the key to bypass an uncertain outcome.

Catch BuddyError for status, code, request_id, details and retry_after. SubscriberOptedOut and TemplateNotApproved allow specific handling. Verify webhooks with verify_webhook(raw_bytes, signature_header, signing_secret) before parsing or acting on them. Deduplicate event IDs durably.

Run tests with PYTHONPATH=packages/python python3 -m unittest discover -s packages/python/tests. Install locally using python3 -m pip install ./packages/python in a virtual environment. Package publication requires verified registry ownership.

Every OpenAPI operation also has a generated snake_case method, such as buddy.send_message(body={...}) and buddy.get_subscriber(id="sub_..."). Request and response TypedDict models are exported from buddy.models. Generate both SDKs from the contract with node scripts/generate-sdk.mjs.

Resource helpers include subscribers, messages, templates, events, otp, campaigns and webhooks. Generated snake_case operation methods cover every API endpoint. Safe requests retry network failures, non-JSON gateway errors, rate limits and request_in_progress within max_retries (default 2), retaining the original body and idempotency key. Replayed failures are not retried.

For writes that must survive a process restart or exhausted retry budget, supply and persist your own stable idempotency key before the first call. Automatically generated keys are retained only within that call; a fresh SDK call generates another key.