Python SDK

pip install https://tsmart.ai/sdk/python/tsmart-1.1.1-py3-none-any.whl

tsmart @ https://tsmart.ai/sdk/python/tsmart-1.1.1-py3-none-any.whl

from tsmart import Tsmart

# Reads TSMART_API_KEY (and TSMART_BASE_URL, if set)
client = Tsmart()

# Or pass the key and options yourself
custom = Tsmart("ts_xxxxxxxx_…", timeout=10, max_retries=3)

from tsmart import Tsmart, TsmartError

client = Tsmart()

try:
    sent = client.emails.send({
        "from": "Acme <hello@acme.com>",
        "to": ["jane@example.com"],
        "subject": "Welcome to Acme",
        "html": "<p>Thanks for signing up.</p>",
    })
    print("Email id:", sent["id"])
except TsmartError as e:
    print(e.status_code, e.name, e.message)

from pathlib import Path

sent = client.emails.send(
    {
        "from": "Acme Billing <billing@acme.com>",
        "to": "jane@example.com",
        "cc": ["accounts@example.com"],
        "reply_to": "support@acme.com",
        "subject": "Your invoice INV-1042",
        "html": "<p>Your invoice is attached.</p>",
        "text": "Your invoice is attached.",
        "headers": {"X-Entity-Ref-ID": "INV-1042"},
        "tags": [{"name": "category", "value": "invoice"}],
        "attachments": [
            {
                "filename": "INV-1042.pdf",
                "content": Path("INV-1042.pdf").read_bytes(),
                "content_type": "application/pdf",
            },
        ],
    },
    idempotency_key="invoice-INV-1042",
)

from datetime import datetime, timedelta, timezone

sent = client.emails.send({
    "from": "hello@acme.com",
    "to": "jane@example.com",
    "subject": "Your trial ends tomorrow",
    "text": "Upgrade any time from your account page.",
    "scheduled_at": "in 1 day",
})

istanbul = timezone(timedelta(hours=3))
client.emails.update(sent["id"], {"scheduled_at": datetime(2026, 10, 20, 9, 0, tzinfo=istanbul)})
client.emails.cancel(sent["id"])

# One email, with its html and text while they are kept (3 days) and its tags
email = client.emails.get(email_id)
print(email["last_event"])  # sent, delivered, bounced, opened …

# Its events in time order
for e in client.emails.events(email_id)["data"]:
    print(e["created_at"], e["type"], e["recipient"])

# Recent emails, newest first
recent = client.emails.list(limit=50)

metrics = client.emails.metrics({
    "start_date": "2026-10-01",
    "end_date": "2026-10-07",
    "timezone": "Europe/Istanbul",
    "granularity": "daily",
    "metrics": ["sent", "delivered", "bounced", "delivery_rate", "open_rate"],
    "dimensions": ["period"],
})

print(metrics["totals"])  # {'sent': 1200, 'delivered': 1187, 'bounced': 4, 'delivery_rate': 0.9892, 'open_rate': 0.4103}
for row in metrics["data"]:
    print(row["period"], row["sent"], row["delivered"])

result = client.batch.send(
    [
        {"from": "hello@acme.com", "to": "ana@example.com", "subject": "Your weekly digest", "html": "<p>…</p>"},
        {"from": "hello@acme.com", "to": "ben@example.com", "subject": "Your weekly digest", "html": "<p>…</p>"},
    ],
    idempotency_key="digest-2026-41",
    validation="permissive",
)

print(result["data"])    # [{'id': '…'}, {'id': '…'}]
print(result["errors"])  # [] or [{'index': 1, 'message': '…'}]

# Add a domain; records lists the DNS records to publish
domain = client.domains.create({"name": "acme.com"})
for r in domain["records"]:
    print(r["type"], r["name"], r["value"])

# After publishing them: prove ownership, then check the sending records
client.domains.verify(domain["id"])
print(client.domains.get(domain["id"])["status"])  # not_started, pending, partially_verified or verified

client.domains.update(domain["id"], {"open_tracking": True, "click_tracking": True})
client.domains.list()
client.domains.remove(domain["id"])

# A key that can only send, and only from one domain
key = client.api_keys.create({
    "name": "Web shop",
    "permission": "sending_access",
    "domain_id": domain["id"],
})
print(key["token"])  # shown only once

client.api_keys.list()
client.api_keys.update(key["id"], {"name": "Web shop (production)"})
client.api_keys.remove(key["id"])  # revoked at once

hook = client.webhooks.create({
    "endpoint": "https://example.com/hooks/tsmart",
    "events": ["email.delivered", "email.bounced"],
})
print(hook["signing_secret"])  # whsec_…, keep it with your receiver

client.webhooks.test(hook["id"])  # queues an example email.sent event
client.webhooks.update(hook["id"], {"events": ["email.bounced"], "status": "enabled"})
client.webhooks.rotate_secret(hook["id"])  # the old secret stops working at once

# What was delivered, and how each attempt went
events = client.webhooks.events.list(hook["id"])
event_id = events["data"][0]["id"]  # msg_…
client.webhooks.events.get(hook["id"], event_id)
client.webhooks.events.attempts(hook["id"], event_id)
client.webhooks.events.replay(hook["id"], event_id)

client.webhooks.remove(hook["id"])

client.suppressions.create({"email": "jane@example.com"})
suppression = client.suppressions.get("jane@example.com")  # by id or by address
print(suppression["reason"])  # bounce, complaint or manual

client.suppressions.list()
client.suppressions.remove("jane@example.com")

# API requests of the last 30 days, newest first (no bodies are kept)
page = client.logs.list(limit=20)
for entry in page["data"]:
    print(entry["created_at"], entry["method"], entry["endpoint"], entry["response_status"])

one = client.logs.get(page["data"][0]["id"])
print(one["error"])  # the error name of a failed request, or None

box = client.mailboxes.create({
    "email": "jane@acme.com",
    "first_name": "Jane",           # or "name": "Jane Doe"
    "last_name": "Doe",
    "quota_mb": 2048,               # optional: 256 to 51200, lowered to the plan's mailbox size
    "org_unit_id": 12,              # optional: default the root unit
})
print(box["temporary_password"])    # shown only once; must be changed at the first sign-in

client.mailboxes.list(domain="acme.com", limit=100)          # ordered by address
client.mailboxes.get("jane@acme.com")
client.mailboxes.update("jane@acme.com", {"name": "Jane Smith", "quota_mb": 4096})
client.mailboxes.update("jane@acme.com", {"active": False})    # suspend; True restores
reset = client.mailboxes.reset_password("jane@acme.com")       # reset["temporary_password"]
client.mailboxes.remove("jane@acme.com")    # with its mail and alternate emails; company owners only

# Alternate emails: mail to them reaches the mailbox, which may also send as them
client.mailboxes.aliases.create("jane@acme.com", {"address": "j.doe@acme.com"})
client.mailboxes.aliases.list("jane@acme.com")
client.mailboxes.aliases.remove("jane@acme.com", "j.doe@acme.com")

client.groups.create({
    "address": "team@acme.com",
    "name": "Team",
    "members": ["jane@acme.com", "partner@example.org"],   # mailboxes or outside addresses, up to 200
})
client.groups.get("team@acme.com")
client.groups.list(domain="acme.com")

# members is the complete new list: read, change, send back
team = client.groups.get("team@acme.com")
client.groups.update("team@acme.com", {"members": team["members"] + ["sam@acme.com"]})

client.groups.remove("team@acme.com")       # company owners only

after = None
while True:
    page = client.emails.list(limit=100, after=after)
    for email in page["data"]:
        print(email["id"], email["last_event"])
    if not page["has_more"]:
        break
    after = page["data"][-1]["id"]

from tsmart import TsmartError

try:
    client.emails.send(email, idempotency_key=key)
except TsmartError as e:
    if e.name in ("validation_error", "missing_required_field"):
        raise ValueError("Bad request: " + e.message) from e
    elif e.name in ("rate_limit_exceeded", "network_error"):
        pass  # try again later, with the same idempotency key
    else:
        print(e.status_code, e.name, e.message)

import os
from http.server import BaseHTTPRequestHandler, HTTPServer
from tsmart import WebhookVerificationError, verify_webhook

SECRET = os.environ["TSMART_WEBHOOK_SECRET"]


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))  # the raw body
        try:
            event = verify_webhook(body, self.headers, SECRET)
        except WebhookVerificationError:
            self.send_response(400)
            self.end_headers()
            return
        if event["type"] == "email.bounced":
            print("Bounced:", event["data"]["to"], event["data"]["bounce"]["message"])
        self.send_response(204)
        self.end_headers()


HTTPServer(("", 8000), Receiver).serve_forever()