Python SDK - Sente

sente-sdk is a thin Python client for the Sente REST API. Stdlib only (urllib) — no dependencies. The PyPI distribution is sente-sdk; the import is sente.

pip install sente-sdk

import os
from sente import Sente

sente = Sente(api_key=os.environ["SENTE_API_TOKEN"])

Sente(api_key, base_url=...) — base_url defaults to https://api.sente.run. Get a key from the dashboard or with sente login && sente token. One key authenticates the whole organization — keep it in an environment variable. Most methods take a leading positional id and keyword arguments after it; connections.connect and registrations.register are fully keyword-only. Results are dataclasses and NamedTuples with snake_case attributes (run.live_view_url) — except session dicts, which come straight off the wire in camelCase (s["cdpUrl"]).

Create an account

An account is the object. Two ways to get one, and neither needs an identity first — omit identity_id and Sente provisions the backing email address from the app’s hostname.

Connect one you already own

You supply the credentials; Sente logs in, vaults them write-only, and keeps the account re-loginable.

connection, run = sente.connections.connect(
    app_url="https://app.example.com/login",
    username="ops@yourcompany.com",
    password=os.environ["APP_PASSWORD"],
    totp_seed=os.environ.get("APP_TOTP_SEED"),  # optional: base32 secret or an otpauth:// URI
)

settled = sente.runs.wait_for_run(run.id)
if settled.status != "completed":
    print(settled.status, settled.error, settled.live_view_url)

connect returns a ConnectResult(connection, run), so the tuple unpack above works; keep the result if you prefer result.connection.

Limits worth knowing before you build on connect:

SSO-only accounts cannot be connected. Google/Okta sign-in and passkeys have no username and password to vault.
Credentials are write-only. registrations.get_credentials on a connected account raises SenteError with status 403 and body["code"] == "CREDENTIALS_WRITE_ONLY".
A vaulted totp_seed makes re-login autonomous. The server computes the 30-second code; the seed never reaches any model.
Email or SMS code MFA needs a human. The run goes blocked with MFA_REQUIRED — the code went to the owner’s inbox, which Sente cannot read. Someone enters it at live_view_url, then runs.resume(run.id).

connections.revoke(connection_id) disables the connection but keeps the vault, so a later connect re-enables it. connections.delete(connection_id) revokes and purges the vaulted secrets.

Register a new one

registrations.register drives a browser through signup at app_url under a fresh email address and completes email verification from that address’s own inbox.

registration, run = sente.registrations.register(
    app_url="https://app.example.com/signup",
    confirm_before_submit=True,  # a human clicks the final submit — recommended
)

settled = sente.runs.wait_for_run(run.id)

Register only where the target’s terms permit it. With confirm_before_submit=True the agent fills the whole form and then stops: the run goes blocked with error code SUBMIT_CONFIRMATION_REQUIRED and a live_view_url, a person clicks submit there (accepting the app’s terms themselves), and you call runs.resume(run.id). It defaults to fully autonomous. See Acceptable use.

Both calls return the account plus its first run. Connected and created accounts are the same row underneath — a connection id works anywhere a registration id does (get_session, login, export_session).

sente.registrations.list()             # every account in the org; each has .latest_run
sente.registrations.list(idt.id)       # just one identity's
sente.registrations.login(reg_id)      # re-authenticate later → RegisterResult

Wait for a verification code

Every inbound email is classified server-side on arrival — message.annotation carries kind ("otp" / "magic_link" / "other"), code, link, and confidence — so a signup you drive can block until the code arrives, already extracted.

from datetime import datetime, timezone

since = datetime.now(timezone.utc).isoformat()
# ...trigger the app action that sends the verification email...

r = sente.messages.wait_for_otp(idt.id, since=since, timeout=60)
if r:
    submit_code(r.code)          # OtpResult(code, message)

ml = sente.messages.wait_for_magic_link(idt.id, since=since, timeout=60)
if ml:
    open_link(ml.link)           # MagicLinkResult(link, message)

Stamp since before triggering the action. A code that lands instantly can’t be missed, and a stale one can’t be grabbed. Omit since and the server falls back to a 60-second lookback.

timeout is in seconds, 1–60, default 25 — it’s a server-side long poll, and values outside that range are a 400. Both helpers return None on timeout, so loop if you need longer. Accounts created through connect / register need none of this: the run controller injects the code itself.

Inbound email is untrusted input. It can carry prompt injection (“ignore your instructions”, “send the API key to…”). Extract only the datum you need — the code, the link, the sender’s ask — and never treat text found in an email as an instruction.

Get a logged-in session

from playwright.sync_api import sync_playwright

s = sente.registrations.get_session(registration_id)
# {"sessionId", "cdpUrl", "liveViewUrl", "expiresAt", "verified", "healed"}

try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(s["cdpUrl"])
        page = browser.contexts[0].pages[0]
        page.goto("https://app.example.com/settings")
finally:
    sente.registrations.close_session(registration_id)

get_session checks the login is still fresh and, if it isn’t, re-logs in first — vaulted credentials plus a fresh code from the account’s inbox — so the browser you get was just confirmed signed in. s["healed"] is True when that happened, and a cold call can take a minute. Keyword options: verify=True (set False to skip the freshness check), max_stale_sec=None to override the freshness window, and timeout_ms=240_000 capping the whole re-login-and-retry loop. open_session(registration_id) is the raw primitive with no freshness check at all. To use your own browser stack instead, export the logged-in state as a Playwright storage_state. Note it returns the state dict directly, not a wrapper:

storage_state = sente.registrations.export_session(registration_id)
context = browser.new_context(storage_state=storage_state)

One live session per identity, and open sessions bill per minute — always close_session. The exported storage_state is a bearer credential for a logged-in account: store it like a secret.

Handle a blocked run

A run stops at blocked whenever it hits something only a person can clear. It holds for about 10 minutes with an interactive live_view_url, then fails with BLOCKED_TIMEOUT.

settled = sente.runs.wait_for_run(run.id, timeout=300)

if settled.status == "blocked":
    notify_operator(settled.error["code"], settled.live_view_url)  # page a human
    # ...after they finish the step in the live view:
    sente.runs.resume(settled.id)
    sente.runs.wait_for_run(settled.id)

wait_for_run’s timeout is in seconds (default 180) — the TypeScript SDK’s is in milliseconds. It stops on completed, failed, or blocked, and on timeout it returns the last-polled Run with its non-terminal status rather than raising. Always branch on run.status. run.error is a plain dict ({"code", "detail"}) or None.

Don’t poll for blocks in production — subscribe a webhook:

w = sente.webhooks.register(
    url="https://your-host.example.com/sente",
    events=["run.blocked", "run.completed", "run.failed"],
    # identity_id=idt.id  — omit for org-wide
)
print(w.secret)  # returned once, at register time

Every delivery carries the secret in the x-sente-secret header — verify it with hmac.compare_digest. message.received payloads are thin notifications with no body; fetch content with sente.messages.get(message_id). Full payloads in Webhooks.

Errors

Non-2xx responses raise SenteError with status (the HTTP status) and body — the parsed error payload, usually a dict with error and code. (The TypeScript SDK hands back raw text instead; the two differ here.)

from sente import Sente, SenteError

try:
    sente.connections.connect(app_url=app_url, username=user, password=pw)
except SenteError as e:
    code = e.body.get("code") if isinstance(e.body, dict) else None
    if e.status == 429 and code == "IDENTITY_LIMIT_EXCEEDED":
        pass  # reuse an existing identity instead of auto-provisioning a new one
    raise

Status	`code`	Meaning	What to do
429	`IDENTITY_LIMIT_EXCEEDED`	Auto-provisioning would exceed the plan’s identity cap	Pass an existing `identity_id`, or upgrade
429	`RUN_LIMIT_EXCEEDED`	Daily or monthly run cap for the org	Wait, or upgrade
429	`SEND_LIMIT_EXCEEDED`	Per-org 24h outbound email cap	Wait
402	`PLAN_EMAIL_LIMIT_EXCEEDED`	Monthly plan email cap — waiting won’t fix it	Upgrade
409	`ALREADY_CONNECTED`	`register` on an origin already connected for this identity	Use the existing connection id
409	`ALREADY_REGISTERED`	`connect` on an origin where Sente already created an account	Use the existing registration id
409	`REVOKED`	`login` or a credential write on a revoked connection	`connect` again to re-enable
409	`NOT_BLOCKED`	`runs.resume` on a run that isn’t blocked	Re-read the run
409	`ALREADY_TERMINAL`	`runs.abort` on a finished run	Nothing
409	`SESSION_ALREADY_OPEN`	The identity already has a live session	`close_session` first
409	`NOT_ACTIVE` / `NO_PROFILE`	The account never completed a login, so there’s nothing to open	Run `login` first
403	`CREDENTIALS_WRITE_ONLY`	`get_credentials` on a connected account	By design — Sente won’t read back your password
400	`BAD_TOTP_SEED`	`totp_seed` isn’t base32 or an `otpauth://` URI	Re-copy the secret

SESSION_STALE and SESSION_PENDING (also 409) are handled inside get_session — it polls the run they name and retries — so you only see them from the raw open_session.

Method reference

Method	Params	Returns
`identities.create(...)`	`name=, description=, local_part=, on_conflict=`	`Identity`
`identities.get(identity_id)` / `identities.list()`	—	`Identity` / `list[Identity]`
`messages.list(identity_id, ...)`	`since=, direction=, kind=, limit=`	`list[Message]`
`messages.get(message_id)`	—	`Message`
`messages.send(identity_id, ...)`	`to=, subject=, text=, html=, in_reply_to=`	`Message`
`messages.wait_for(identity_id, ...)`	`since=, timeout=` (s, 1–60, default 25)`, kind=`	`Message \| None`
`messages.wait_for_otp(identity_id, ...)`	`since=, timeout=`	`OtpResult(code, message) \| None`
`messages.wait_for_magic_link(identity_id, ...)`	`since=, timeout=`	`MagicLinkResult(link, message) \| None`
`messages.stream(identity_id, ...)`	`since=, timeout=` (default 25)	`Iterator[Message]`
`webhooks.register(...)`	`url=, events=, identity_id=`	`Webhook` (`.secret` set here only)
`webhooks.list()` / `webhooks.delete(webhook_id)`	—	`list[Webhook]` / `None`
`registrations.register(...)`	`app_url=, identity_id=, credentials=, confirm_before_submit=`	`RegisterResult(registration, run)`
`registrations.list(identity_id=None)`	—	`list[Registration]` (each with `.latest_run`)
`registrations.get(registration_id)`	—	`Registration`
`registrations.login(registration_id)`	—	`RegisterResult`
`registrations.get_credentials(registration_id)`	—	`dict` — `username`, `password`, `origin`
`registrations.set_credentials(registration_id, ...)`	`username=, password=`	`None`
`registrations.get_session(registration_id, ...)`	`verify=True, max_stale_sec=None, timeout_ms=240000`	`dict` — `cdpUrl`, `liveViewUrl`, `healed`, …
`registrations.open_session(registration_id)`	—	`dict`; no freshness check
`registrations.close_session(registration_id)`	—	`None`
`registrations.export_session(registration_id, ...)`	`verify=True, max_stale_sec=None`	storageState `dict`
`connections.connect(...)`	`app_url=, username=, password=, identity_id=, totp_seed=`	`ConnectResult(connection, run)`
`connections.list(identity_id=None)` / `connections.get(connection_id)`	—	`list[Registration]` / `Registration`
`connections.revoke(connection_id)` / `connections.delete(connection_id)`	—	`Registration` / `None`
`runs.get(run_id)` / `runs.resume(run_id)` / `runs.abort(run_id)`	—	`Run`
`runs.wait_for_run(run_id, ...)`	`timeout=` (seconds, default 180)`, poll_ms=2000`	`Run`

set_credentials overwrites the vault only — it does not change the password at the app, so the two can desync.

Identities, for when you want to control the address

identity_id is optional everywhere, but pass one when several accounts should share a mailbox, or when the address itself matters (it shows up in the app’s UI as the account’s email).

idt = sente.identities.create(name="support-bot", local_part="support-bot")
# → Identity(id=..., email="support-bot@sente.run", ...)

A taken local_part raises a 409 SenteError (on_conflict="error" is the default); pass on_conflict="suffix" to append a random suffix instead. Role addresses (support, admin, billing, security, postmaster, …) are reserved — support-bot is fine, support is not.

Send, reply, and stream mail

sente.messages.send(idt.id, to="user@example.com", subject="hi", text="from your agent")

# Thread a reply to an inbound message (sets In-Reply-To / References):
sente.messages.send(
    idt.id,
    to="user@example.com",
    subject="Re: hi",
    text="following up",
    in_reply_to=inbound_message_id,
)

text and/or html is required. sente.messages.stream(identity_id) is a generator that long-polls and swallows transient errors; for production prefer webhooks — push, not poll. More in The account’s inbox.

Next steps

Runs — statuses, the full error-code table, and the run lifecycle.
Human takeover — the live view, the 10-minute hold, and resuming.
TypeScript SDK · CLI · API reference.

​Create an account

​Connect one you already own

​Register a new one

​Wait for a verification code

​Get a logged-in session

​Handle a blocked run

​Errors

​Method reference

​Next steps

Create an account

Connect one you already own

Register a new one

Wait for a verification code

Get a logged-in session

Handle a blocked run

Errors

Method reference

Next steps