Python SDK

The Orbit Python SDK wraps the platform’s core API resources — messaging (SMS, WhatsApp, email), voice, contacts, campaigns, verify (OTP), numbers, and HLR lookup — with typed methods. It targets Python 3.9+ and is fully hand-written on the standard library, so it has zero runtime dependencies.

Pre-publish — source-only. This SDK is not yet on PyPI. The install commands below describe the future registry shape; until first publish, vendor the source from the monorepo (packages/sdk-python/) or call the REST API directly from your client. See the Python: core-scope, not full parity section on the SDK index for exactly what is and isn’t wrapped, and the low-level client.request(method, path, ...) escape hatch for uncovered routes (worked example below).

Installation

Not installable from PyPI yet. Vendor the SDK source from the monorepo (packages/sdk-python/ — a pure-standard-library package you can drop onto your path), or call the REST API directly with any HTTP client until the first release ships (install coordinates change). Requires Python 3.9+.

Client initialization

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_live_sk_...")

Or read the key from an environment variable (ORBIT_API_KEY):

client = OrbitClient.from_env()

Tune timeouts and retries with the direct constructor:

client = OrbitClient(
    api_key="dv_live_sk_...",
    base_url="https://api.orbit.devotel.io/api/v1",  # defaults to prod
    timeout_s=30.0,      # per-request timeout
    max_retries=3,       # 429/5xx retry budget
    initial_backoff_s=1.0,
)

Quickstart: send your first SMS

A runnable end-to-end — the key comes from ORBIT_API_KEY, never from source. Copy it into first_send.py and run it:

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

msg = client.messages.send_sms(to="+14155552671", body="Hello from Orbit!")

print("message id:", msg["data"]["id"])          # msg_abc123
print("status:", msg["data"]["status"])          # 'queued' — watch it reach 'delivered'
print("status URL:", f"/api/v1/messages/{msg['data']['id']}")

Point ORBIT_API_KEY at a sandbox key prefixed dv_test_sk_ first — sandbox sends are simulated, free, and never reach a carrier. Swap in your live key (dv_live_sk_...) when you’re ready to send for real; the code does not change. The WhatsApp and email helpers below follow the same shape, and the full request/response contract with per-language examples lives on the Messages API reference.

Messaging

# Send SMS
msg = client.messages.send_sms(to="+14155552671", body="Hello from Orbit!")
print(msg["data"]["id"])

# Send WhatsApp
client.messages.send_whatsapp(to="+14155552671", body="Hello on WhatsApp!")

# Send email
client.messages.send_email(
    to="user@example.com",
    subject="Welcome",
    body="Thanks for signing up.",
)

Voice

# Initiate an outbound call, then hang up. Termination is handled
# server-side by the Devotel softswitch — the SDK never selects a carrier.
call = client.voice.create(to="+14155552671", from_="+14155550000", record=True)
client.voice.get(call["data"]["id"])
client.voice.hangup(call["data"]["id"])

Second example: verify OTP

The send-and-check round trip is the most common first integration on the platform. Three lines — the key is still just ORBIT_API_KEY read by OrbitClient.from_env():

# 1. Send an OTP (channel: sms | whatsapp | email).
sent = client.verify.send(to="+14155552671", channel="sms")

# 2. Check the code the user typed in, against the verification id send() returned.
result = client.verify.check(verification_id=sent["data"]["id"], code="482901")

print("valid:", result["data"]["valid"])     # True
print("status:", result["data"]["status"])   # 'approved'

A wrongly-typed or expired code reports valid: False — it never raises for a bad guess (only for transport/auth failures), so check the flag. The Verify API reference covers the full contract, and Starter examples includes a complete OTP sign-in starter repo (orbit-otp-nextjs).

Verify (OTP)

sent = client.verify.send(to="+14155552671", channel="sms")  # sms | whatsapp | email
client.verify.check(verification_id=sent["data"]["id"], code="123456")
client.verify.get_detail(sent["data"]["id"])

Contacts

contact = client.contacts.create(phone="+14155552671", first_name="Ada", tags=["vip"])
client.contacts.list(search="ada", limit=20)
client.contacts.get(contact["data"]["id"])
client.contacts.update(contact["data"]["id"], company="Acme Inc.")
client.contacts.add_tags(contact["data"]["id"], ["beta-tester"])
client.contacts.delete(contact["data"]["id"])

Campaigns

campaign = client.campaigns.create(
    name="Fall promo",
    channel="sms",
    message_template="Hi {{first_name}}!",
)
client.campaigns.list()
client.campaigns.send(campaign["data"]["id"])
client.campaigns.update(campaign["data"]["id"], name="Fall promo v2")
client.campaigns.delete(campaign["data"]["id"])

Numbers and HLR lookup

available = client.numbers.search(country="US", type="local", capabilities=["sms", "voice"])
client.numbers.purchase(number="+14155552671")

client.lookup.number("+14155552671")                              # validity, carrier, line type
client.lookup.bulk(["+14155552671", "+442071838750"])             # up to 100 per request

Paginate a list

List endpoints are cursor-paginated — read meta.pagination.cursor and meta.pagination.has_more off each response and pass the cursor back until has_more is False. Page through SMS messages:

params = {"channel": "sms", "limit": 100}
total = 0

while True:
    page = client.request("GET", "/messages", params=params)

    total += len(page["data"])
    pagination = page["meta"]["pagination"]
    if not pagination["has_more"]:
        break
    params["cursor"] = pagination["cursor"]

print(f"Fetched {total} messages")

The full pagination model (cursor vs. offset endpoints, page-size caps, and why cursors are not bookmarkable) is in the Pagination guide.

Error handling

All Orbit-originated errors inherit from OrbitError:

Exception	Raised when
`OrbitAuthenticationError`	401/403 — bad or missing-scope API key
`OrbitClientError`	other 4xx (invalid request)
`OrbitRateLimitError`	429 after retries exhausted; check `exc.retry_after`
`OrbitServerError`	5xx after retries exhausted, or persistent network failure
`OrbitError`	base class — catch to handle any Orbit-originated error

from orbit_sdk import (
    OrbitError,
    OrbitAuthenticationError,
    OrbitRateLimitError,
)

try:
    client.messages.send_sms(to="+14155552671", body="...")
except OrbitRateLimitError as exc:
    print(f"throttled — retry in {exc.retry_after}s")
except OrbitAuthenticationError:
    print("bad API key — rotate it")
except OrbitError as exc:
    print(f"orbit error: {exc.code} ({exc.status}) — {exc.message}")

Every non-GET request automatically carries an Idempotency-Key header, so a retry never produces a duplicate charge on billable paths. Override per call with your own stable key (idempotency_key="job-7a3b9d-attempt-1").

Covered route missing? Use the escape hatch

The typed clients wrap 8 core resources; the rest of the API — contact segments, event sinks, frequency caps, and everything else listed as out of scope on the SDK index — is reachable through client.request(method, path, ...). It returns the raw JSON body as a dict. Fetch a segment by id:

segment = client.request("GET", "/contacts/segments/seg_01hxyz")
print(segment["data"]["name"])

The escape hatch carries the same auth, retry, and error model as the typed clients — treat it as a first-class client, not a fallback urllib call.

Webhook signature verification

from orbit_sdk import verify_webhook, OrbitWebhookSignatureError

@app.post("/webhooks/orbit")
def handler(request):
    try:
        event = verify_webhook(
            payload=request.body,                            # bytes
            signature=request.headers["X-Devotel-Signature"],
            secret=os.environ["ORBIT_WEBHOOK_SECRET"],
        )
    except OrbitWebhookSignatureError:
        # Forgery attempt — drop, do not 200.
        return Response(status=400)

    # event is a dict — act on event["type"], event["data"], ...
    return Response(status=200)

Signatures use the t=<unix_ts>,v1=<hex_hmac> format (same as Stripe) with a 5-minute replay window enforced by default.

SDKs

Python SDK: Orbit quickstart for Python

Python SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Numbers and HLR lookup

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

​Python SDK

​Installation

​Client initialization

​Quickstart: send your first SMS

​Messaging

​Voice

​Second example: verify OTP

​Verify (OTP)

​Contacts

​Campaigns

​Numbers and HLR lookup

​Paginate a list

​Error handling

​Covered route missing? Use the escape hatch

​Webhook signature verification

Python SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Numbers and HLR lookup

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification