sentroy-client-sdk 2.18.0

Sentroy Client SDK for Python

Server-side SDK to interact with the Sentroy platform API.
Manage mail (domains, mailboxes, templates, inbox, send, audience, suppressions, webhooks, logs), storage (buckets, media) and WhatsApp from a single entry point — plus a separate Auth-as-a-Service client.

Installation

pip install sentroy-client-sdk

Quick Start

from sentroy import Sentroy

sentroy = Sentroy(
    base_url="https://sentroy.com",
    company_slug="my-company",
    access_token="stk_...",
)

Access tokens can be created from Admin > Access Tokens in the Sentroy dashboard.

Usage

Domains

# List all domains
domains = sentroy.domains.list()

# Get a single domain
domain = sentroy.domains.get("domain-id")

Mailboxes

# List all mailbox accounts
mailboxes = sentroy.mailboxes.list()

Templates

# List all templates (optionally filtered by sending domain)
templates = sentroy.templates.list()
templates = sentroy.templates.list(domain_id="domain-id")

# Get a template by ID
template = sentroy.templates.get("template-id")

# Create — name/subject/mjml_body accept a flat string or a {lang: value} map.
# `variables` is NOT an input: the platform extracts placeholders from the
# body and returns them on the created template. Requires templates.manage.
template = sentroy.templates.create(
    name={"en": "Welcome", "tr": "Hosgeldin"},
    subject={"en": "Welcome, {{name}}!", "tr": "Hosgeldin, {{name}}!"},
    mjml_body={"en": "<mjml>...</mjml>", "tr": "<mjml>...</mjml>"},
    domain_id="domain-id",
)

# Partial update
template = sentroy.templates.update("template-id", subject="New subject")

# Delete
sentroy.templates.delete("template-id")

Templates support multiple languages. A field like name or subject can be a plain string or a dict keyed by language code:

# Example template response
{
    "id": "b3f1a2c4-...",
    "name": {"en": "Welcome Email", "tr": "Hosgeldin E-postasi"},
    "subject": {"en": "Welcome, {{name}}!", "tr": "Hosgeldin, {{name}}!"},
    "mjmlBody": {"en": "<mjml>...</mjml>", "tr": "<mjml>...</mjml>"},
    "variables": ["name", "company"],
    "domainId": "a1b2c3d4-...",
    "domainName": "example.com"
}

Use the variables list to know which placeholders ({{name}}, {{company}}) the template expects.

Inbox

from sentroy import InboxListParams

# List messages
messages = sentroy.inbox.list(InboxListParams(
    mailbox="info@example.com",
    folder="INBOX",
    page=1,
    limit=20,
))

# Get a single message
message = sentroy.inbox.get(1234, mailbox="info@example.com")

# List IMAP folders
folders = sentroy.inbox.list_folders("info@example.com")

# Get a thread by subject
thread = sentroy.inbox.get_thread("Re: Project update", "info@example.com")

# Mark as read / unread
sentroy.inbox.mark_as_read(1234, mailbox="info@example.com")
sentroy.inbox.mark_as_unread(1234, mailbox="info@example.com")

# Move message
sentroy.inbox.move(1234, "Trash", from_folder="INBOX", mailbox="info@example.com")

# Delete message
sentroy.inbox.delete(1234, mailbox="info@example.com")

Send Email

from sentroy import SendParams, Attachment

# Send with a template
result = sentroy.send.email(SendParams(
    to="user@example.com",
    from_addr="info@example.com",
    subject="Welcome!",
    domain_id="domain-id",
    template_id="template-id",
    variables={
        "name": "John",
        "company": "Acme",
    },
))

# Send with a specific language
result = sentroy.send.email(SendParams(
    to="user@example.com",
    from_addr="info@example.com",
    subject="Hosgeldin!",
    domain_id="domain-id",
    template_id="template-id",
    lang="tr",
    variables={"name": "Ahmet"},
))

# Send with raw HTML
result = sentroy.send.email(SendParams(
    to=["user1@example.com", "user2@example.com"],
    from_addr="info@example.com",
    subject="Hello",
    domain_id="domain-id",
    html="<h1>Hello World</h1>",
))

# Send with attachments
result = sentroy.send.email(SendParams(
    to="user@example.com",
    from_addr="info@example.com",
    subject="Invoice",
    domain_id="domain-id",
    html="<p>Please find your invoice attached.</p>",
    attachments=[
        Attachment(
            filename="invoice.pdf",
            content=base64_string,
            content_type="application/pdf",
        ),
    ],
))

Audience (Contacts & Lists)

Company-wide contact records plus named lists (groupings).

# Contacts — paginated list with filters
result = sentroy.audience.contacts.list(page=1, limit=50, status="active", tags=["vip"])
print(result.total, len(result.contacts))

# Email-prefix autocomplete (server-capped at 10 results)
matches = sentroy.audience.contacts.search("john@")

# CRUD
contact = sentroy.audience.contacts.get("contact-id")
contact = sentroy.audience.contacts.create(email="user@example.com", name="John", tags=["vip"])
contact = sentroy.audience.contacts.update("contact-id", status="unsubscribed")
sentroy.audience.contacts.delete("contact-id")  # soft-delete: marks unsubscribed

# Lists
lists = sentroy.audience.lists.list()
lst = sentroy.audience.lists.get("list-id")
lst = sentroy.audience.lists.create(name="Newsletter", description="Weekly digest")
sentroy.audience.lists.delete("list-id")  # only removes the grouping

# List membership (scoped sub-resource)
members = sentroy.audience.lists.members("list-id")
contacts = members.list()
members.add("contact-id")
members.remove("contact-id")  # contact record preserved

Suppressions

Suppressed recipients are skipped at send time. Bounces/complaints are added automatically server-side; use add for manual opt-outs.

suppressions = sentroy.suppressions.list(page=1, limit=50, domain_id="domain-id")

suppression = sentroy.suppressions.add(
    email="user@example.com",
    domain_id="domain-id",
    reason="manual",
)

sentroy.suppressions.remove("suppression-id")

Webhooks

# List (optionally scoped to a domain)
webhooks = sentroy.webhooks.list(domain_id="domain-id")

# Create — `secret` is returned ONLY here; store it for HMAC verification
webhook = sentroy.webhooks.create(
    url="https://example.com/hooks/mail",
    events=["sent", "bounced", "opened"],
    domain_id="domain-id",
)
print(webhook.secret)

# Read / update / delete (reads never return the secret)
webhook = sentroy.webhooks.get("webhook-id")
webhook = sentroy.webhooks.update("webhook-id", active=False)
sentroy.webhooks.delete("webhook-id")

# Fire a custom test payload at the current URL
result = sentroy.webhooks.test("webhook-id", event="sent", payload={"demo": True})
print(result.status, result.response_status, result.duration_ms)

# Delivery log (test/replay dispatches only)
deliveries = sentroy.webhooks.deliveries("webhook-id")
page = deliveries.list(page=1, limit=20, status="failed")
row = deliveries.get("delivery-id")     # full payload + response body (4KB cap)
replayed = deliveries.replay("delivery-id")  # re-fires at the CURRENT URL

Mail Logs

logs = sentroy.logs.list(
    page=1,
    limit=50,
    status="sent",              # queued|processing|sent|bounced|failed
    domain_id="domain-id",
    from_="2026-01-01T00:00:00Z",  # ISO, inclusive
    to="2026-01-31T23:59:59Z",     # ISO, inclusive
)

log = sentroy.logs.get("log-id")
print(log.status, log.opened_at, log.clicked_at)

WhatsApp

WhatsApp Santral — same stk_ token as mail/storage.

# Connected numbers (only connected ones can send)
numbers = sentroy.whatsapp.numbers.list()

# Templates — variables auto-extracted from {{placeholders}} in body
templates = sentroy.whatsapp.templates.list()
tpl = sentroy.whatsapp.templates.create(
    name="Order shipped",
    body="Hi {{name}}, your order {{orderId}} has shipped!",
)
tpl = sentroy.whatsapp.templates.update(tpl.id, category="transactional")
sentroy.whatsapp.templates.delete(tpl.id)

# Audiences — entries accept plain phones or per-recipient variable maps
audience = sentroy.whatsapp.audiences.create(
    name="Beta users",
    entries=[
        "+905551112233",
        {"phone": "+905554445566", "variables": {"name": "Ayse"}},
    ],
)

# Send — single (`to`) XOR bulk (`audience_id`); template XOR raw body
result = sentroy.whatsapp.send(
    to="+905551112233",
    template_id=tpl.id,
    variables={"name": "John", "orderId": "1234"},
)
result = sentroy.whatsapp.send(
    audience_id=audience.id,
    body="Hello {{name}}!",   # global variables merged UNDER per-recipient ones
    variables={"name": "there"},
)
print(result.total, result.sent, result.failed)
for r in result.results:
    print(r.to, r.status, r.wa_message_id or r.error)

# Send logs
logs = sentroy.whatsapp.logs.list(page=1, limit=20, status="failed")

Buckets

Storage is organized into buckets — isolated containers with their own visibility (public vs private) and usage counters.

# List all buckets
buckets = sentroy.buckets.list()

# Get a single bucket by its slug
bucket = sentroy.buckets.get("product-assets")

# Create (slug auto-derived from name if omitted)
bucket = sentroy.buckets.create(
    name="User Uploads",
    description="Avatars and profile media",
    is_public=False,
)

# Update — toggling is_public cascades to every file's ACL
bucket = sentroy.buckets.update("product-assets", is_public=True)

# Delete (pass force=True to purge files first)
sentroy.buckets.delete("product-assets", force=True)

Media

Upload, list, download, and delete files. The same access token that authorizes mail calls also authorizes storage.

# List files in a bucket
result = sentroy.media.list("product-assets", type="image", limit=50)
print(result.total, len(result.items))

# Get a single media record
media = sentroy.media.get("product-assets", "media-id")

# Upload from a file path
uploaded = sentroy.media.upload(
    "product-assets",
    body="./photo.jpg",
    folder="products",
    tags=["v1", "cover"],
    is_public=True,
)

# Upload from raw bytes
uploaded = sentroy.media.upload(
    "product-assets",
    body=photo_bytes,
    filename="photo.jpg",
    content_type="image/jpeg",
)

# Download — returns (bytes, content_type)
data, content_type = sentroy.media.download("product-assets", "media-id")

# Thumbnail variant (500px wide — falls back to original if unavailable)
thumb, _ = sentroy.media.download(
    "product-assets", "media-id", quality=500,
)

# Delete
sentroy.media.delete("product-assets", "media-id")

Video uploads

# Light single-pass H.264 re-encode (sync — roughly doubles upload latency)
uploaded = sentroy.media.upload("videos", body="./clip.mp4", compress_video=True)

# Async multi-quality ladder (144p/480p/720p/1080p) — implies compress_video.
# Returns immediately with processing.status == "queued"; poll media.get.
uploaded = sentroy.media.upload("videos", body="./clip.mp4", transcode_video=True)

import time
media = sentroy.media.get("videos", uploaded.id)
while media.processing and media.processing.status not in ("completed", "failed"):
    time.sleep(4)
    media = sentroy.media.get("videos", media.id)
print([v.height for v in media.video_meta.variants])

Thumbnail helpers

Pure URL helpers — pick the right pre-generated thumbnail for a display target instead of shipping the original. Call with a 2x target for retina.

from sentroy import pick_thumbnail_url, pick_preset_thumbnail_url, THUMBNAIL_PRESETS

avatar_url = pick_thumbnail_url(media, 56 * 2)          # explicit px target
card_url = pick_preset_thumbnail_url(media, "card")     # avatar|card|preview|hero
print(THUMBNAIL_PRESETS)  # {"avatar": 128, "card": 500, "preview": 960, "hero": 1600}

Storage quota & usage

quota = sentroy.storage.quota()
print(quota.used, quota.limit, quota.mail_used)  # limit 0 = unlimited

usage = sentroy.storage.usage()
for bucket in usage.buckets:
    print(bucket.slug, bucket.storage_used, bucket.file_count)
for row in usage.by_type:
    print(row.type, row.count, row.bytes)

Auth-as-a-Service (SentroyAuth)

Separate client for Sentroy Auth Projects (your own end-user pool) — it is not attached to the root Sentroy client: different base URL (https://auth.sentroy.com) and a different credential (project aps_ API key).

The aps_ key is the project's master key — keep it server-only, never ship it to a browser.

from sentroy import SentroyAuth, SentroyAuthError

auth = SentroyAuth(
    project_slug="my-app",
    api_key="aps_...",                        # server-only
    # auth_base_url="https://auth.sentroy.com",  # default
)

# Sign up / sign in
res = auth.sign_up(email="user@example.com", password="s3cret!", display_name="John")

outcome = auth.sign_in(email="user@example.com", password="s3cret!")
if outcome.kind == "mfa":
    auth.verify_mfa(mfa_token=outcome.mfa.mfa_token, code="123456")

print(auth.user)          # current SentroyAuthUser (or None)
print(auth.access_token)  # current end-user access token (or None)

# Session lifecycle
auth.refresh_now()        # exchange refresh token for new tokens
auth.sign_out()           # best-effort revoke + clear local session

# Email / password flows
auth.send_password_reset("user@example.com")
auth.confirm_password_reset(token="...", new_password="...")
auth.verify_email("token-from-mail")
auth.send_magic_link(email="user@example.com", redirect_uri="https://rp/cb")
auth.consume_magic_link("token-from-mail")
auth.accept_invitation(token="...", password="...")

# Social login (URL builder only — redirect the user's browser to it)
url = auth.social_authorize_url("google", redirect_uri="https://rp/cb")

# Signed-in user (bearer) endpoints
user = auth.get_current_user()
sessions = auth.list_sessions()
auth.revoke_session("session-id")
auth.change_password(current_password="...", new_password="...")  # clears session
auth.request_email_change(new_email="new@example.com", current_password="...")
auth.confirm_email_change("token-from-mail")
auth.request_account_deletion("current-password")
auth.confirm_account_deletion("token-from-mail")
activity = auth.get_activity()

# MFA (TOTP)
status = auth.mfa.get_status()
enroll = auth.mfa.enroll_totp()               # secret + otpauth URI
codes = auth.mfa.verify_totp_enrollment("123456").recovery_codes  # shown once
auth.mfa.disable_totp("current-password")

# Passkeys (management; WebAuthn register/authenticate ceremonies are browser-only)
passkeys = auth.passkey.list()
auth.passkey.delete("passkey-id")

# Firebase-style state subscription
unsubscribe = auth.on_auth_state_changed(lambda user: print("auth state:", user))
unsubscribe()

# Error handling
try:
    auth.sign_in(email="user@example.com", password="wrong")
except SentroyAuthError as err:
    print(err.code, err.status)  # e.g. "invalid_credentials", 401

Session state is held in memory by default; pass a custom storage object with read() / write(value) / clear() for persistence. There is no background refresh timer — call refresh_now() when the token nears expiry.

Error Handling

from sentroy import Sentroy, SentroyError

try:
    sentroy.send.email(params)
except SentroyError as err:
    print(err.status_code)  # 401, 403, 500, etc.
    print(err)              # Human-readable error

Configuration

Requirements

• Python 3.10+
• Zero external dependencies (stdlib only)

Raw Documentation

For AI agents and LLMs — plain-text version of this document:

https://raw.githubusercontent.com/Sentroy-Co/client-sdk/refs/heads/main/python/README.md

License

MIT