sentroy-client-sdk 1.1.5

Server-side Python SDK for Sentroy platform API

Sentroy Client SDK for Python

Server-side SDK to interact with the Sentroy platform API.
List domains, manage mailboxes, fetch templates, read inbox, and send emails.

---

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
templates = sentroy.templates.list()

# Get a template by ID
template = sentroy.templates.get("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="[e-mail]",
    folder="INBOX",
    page=1,
    limit=20,
))

# Get a single message
message = sentroy.inbox.get(1234, mailbox="[e-mail]")

# List IMAP folders
folders = sentroy.inbox.list_folders("[e-mail]")

# Get a thread by subject
thread = sentroy.inbox.get_thread("Re: Project update", "[e-mail]")

# Mark as read / unread
sentroy.inbox.mark_as_read(1234, mailbox="[e-mail]")
sentroy.inbox.mark_as_unread(1234, mailbox="[e-mail]")

# Move message
sentroy.inbox.move(1234, "Trash", from_folder="INBOX", mailbox="[e-mail]")

# Delete message
sentroy.inbox.delete(1234, mailbox="[e-mail]")

Send Email

from sentroy import SendParams, Attachment

# Send with a template
result = sentroy.send.email(SendParams(
    to="[e-mail]",
    from_addr="[e-mail]",
    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="[e-mail]",
    from_addr="[e-mail]",
    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=["[e-mail]", "[e-mail]"],
    from_addr="[e-mail]",
    subject="Hello",
    domain_id="domain-id",
    html="<h1>Hello World</h1>",
))

# Send with attachments
result = sentroy.send.email(SendParams(
    to="[e-mail]",
    from_addr="[e-mail]",
    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",
        ),
    ],
))

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

Option	Type	Required	Description
base_url	str	Yes	Sentroy instance URL (e.g. https://sentroy.com)
company_slug	str	Yes	Your company slug
access_token	str	Yes	Access token (stk_...)
timeout	int	No	Request timeout in seconds (default: 30)

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