TypeScript SDK

@sente-labs/sdk is a thin typed client for the Sente REST API. Zero runtime dependencies (it uses global fetch, so Node 18+), and types ship with the package — no @types/* install.

npm install @sente-labs/sdk

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_TOKEN! });

new Sente(opts) takes { apiKey, baseUrl?, fetch? }. baseUrl defaults to https://api.sente.run; the fetch override exists for tests. Get a key from the dashboard or with sente login && sente token. One key authenticates the whole organization — keep it in an environment variable.

Create an account

An account is the object. Two ways to get one, and neither needs an identity first — omit identityId 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.

const { connection, run } = await sente.connections.connect({
  appUrl: "https://app.example.com/login",
  credentials: {
    username: "ops@yourcompany.com",
    password: process.env.APP_PASSWORD!,
    totpSeed: process.env.APP_TOTP_SEED, // optional: base32 secret or an otpauth:// URI
  },
});

const settled = await sente.runs.waitForRun(run.id);
if (settled.status !== "completed") {
  console.log(settled.status, settled.error?.code, settled.liveViewUrl);
}

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.getCredentials on a connected account returns 403 CREDENTIALS_WRITE_ONLY.
A vaulted totpSeed 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 liveViewUrl, then runs.resume(run.id).

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

Register a new one

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

const { registration, run } = await sente.registrations.register({
  appUrl: "https://app.example.com/signup",
  confirmBeforeSubmit: true, // a human clicks the final submit — recommended
});

const settled = await sente.runs.waitForRun(run.id);

Register only where the target’s terms permit it. With confirmBeforeSubmit: true the agent fills the whole form and then stops: the run goes blocked with error.code === "SUBMIT_CONFIRMATION_REQUIRED" and a liveViewUrl, 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 (getSession, login, exportSession).

await sente.registrations.list();          // every account in the org, each with latestRun
await sente.registrations.list(idt.id);    // just one identity's
await sente.registrations.login(id);       // re-authenticate later → { registration, run }

Wait for a verification code

Every inbound email is classified server-side on arrival — message.annotation is { kind: "otp" | "magic_link" | "other", code, link, confidence } — so a signup you drive can block until the code arrives, already extracted.

const since = new Date().toISOString();
// ...trigger the app action that sends the verification email...

const otp = await sente.messages.waitForOtp(idt.id, { since, timeout: 60 });
if (otp) submitCode(otp.code); // otp is { code, message } | null

const ml = await sente.messages.waitForMagicLink(idt.id, { since, timeout: 60 });
if (ml) await fetch(ml.link!);

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 resolve null 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

import { chromium } from "playwright";

const s = await sente.registrations.getSession(registration.id);
// { sessionId, cdpUrl, liveViewUrl, expiresAt, verified, healed }

const browser = await chromium.connectOverCDP(s.cdpUrl);
try {
  const page = browser.contexts()[0].pages()[0];
  await page.goto("https://app.example.com/settings");
} finally {
  await sente.registrations.closeSession(registration.id);
}

getSession 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. healed: true says that happened, and a cold call can take a minute. Options: { verify?, maxStaleSec?, timeoutMs? }. verify: false skips the freshness check; maxStaleSec overrides the freshness window for this call; timeoutMs caps the whole re-login-and-retry loop and defaults to 240000 (4 minutes). openSession(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 storageState:

const { storageState } = await sente.registrations.exportSession(registration.id);
const context = await browser.newContext({ storageState: storageState as any });

One live session per identity, and open sessions bill per minute — always closeSession. The exported storageState 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 liveViewUrl, then fails with BLOCKED_TIMEOUT.

const settled = await sente.runs.waitForRun(run.id, { timeout: 300_000 });

if (settled.status === "blocked") {
  notifyOperator(settled.error?.code, settled.liveViewUrl); // page a human
  // ...after they finish the step in the live view:
  await sente.runs.resume(settled.id);
  await sente.runs.waitForRun(settled.id);
}

waitForRun’s timeout is in milliseconds (default 180000) — the Python SDK’s is in seconds. It stops on completed, failed, or blocked, and on timeout it returns the last-polled run with its non-terminal status rather than throwing. Always branch on run.status.

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

const { secret } = await sente.webhooks.register({
  url: "https://your-host.example.com/sente",
  events: ["run.blocked", "run.completed", "run.failed"],
  // identityId: idt.id  — omit for org-wide
});

The secret is returned once, at register time. Every delivery carries it in the x-sente-secret header — verify with a timing-safe compare. message.received payloads are thin notifications with no body; fetch content with messages.get(id). Full payloads in Webhooks.

Errors

Non-2xx responses throw SenteError with status (the HTTP status) and body.

SenteError.body is the raw response text, not parsed JSON. Parse it yourself when you need the error code. (The Python SDK parses it for you — the two differ here.)

import { Sente, SenteError } from "@sente-labs/sdk";

try {
  await sente.connections.connect({ appUrl, credentials: { username, password } });
} catch (e) {
  if (!(e instanceof SenteError)) throw e;
  const code = (() => {
    try { return JSON.parse(String(e.body)).code as string; } catch { return undefined; }
  })();
  if (e.status === 429 && code === "IDENTITY_LIMIT_EXCEEDED") {
    // reuse an existing identity instead of auto-provisioning a new one
  }
}

Status	`code`	Meaning	What to do
429	`IDENTITY_LIMIT_EXCEEDED`	Auto-provisioning would exceed the plan’s identity cap	Pass an existing `identityId`, 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	`closeSession` 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`	`getCredentials` on a connected account	By design — Sente won’t read back your password
400	`BAD_TOTP_SEED`	`totpSeed` isn’t base32 or an `otpauth://` URI	Re-copy the secret

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

Method reference

Method	Params	Returns
`identities.create(input?)`	`{ name?, description?, localPart?, onConflict?: "error" \| "suffix" }`	`Promise<Identity>`
`identities.get(id)` / `identities.list()`	—	`Promise<Identity>` / `Promise<Identity[]>`
`messages.list(identityId, opts?)`	`{ since?, direction?, kind?, limit? }`	`Promise<Message[]>`
`messages.get(id)`	—	`Promise<Message>`
`messages.send(identityId, input)`	`{ to, subject, text?, html?, inReplyTo? }`	`Promise<Message>`
`messages.waitFor(identityId, opts?)`	`{ since?, timeout? (s, 1–60, default 25), kind? }`	`Promise<Message \| null>`
`messages.waitForOtp(identityId, opts?)`	`{ since?, timeout? }`	`Promise<{ code, message } \| null>`
`messages.waitForMagicLink(identityId, opts?)`	`{ since?, timeout? }`	`Promise<{ link, message } \| null>`
`messages.stream(identityId, opts?)`	`{ since?, timeout? }`	`AsyncGenerator<Message>`
`webhooks.register(input)`	`{ url, events, identityId? }`	`Promise<Webhook & { secret }>`
`webhooks.list()` / `webhooks.delete(id)`	—	`Promise<Webhook[]>` / `Promise<void>`
`registrations.register(input)`	`{ appUrl, identityId?, credentials?: { username?, password? }, confirmBeforeSubmit? }`	`Promise<{ registration, run }>`
`registrations.list(identityId?)`	—	`Promise<(Registration & { latestRun })[]>`
`registrations.get(id)`	—	`Promise<Registration>`
`registrations.login(id)`	—	`Promise<{ registration, run }>`
`registrations.getCredentials(id)`	—	`Promise<{ username, password, origin }>`
`registrations.setCredentials(id, input)`	`{ username?, password? }`	`Promise<void>`
`registrations.getSession(id, opts?)`	`{ verify?, maxStaleSec?, timeoutMs? (default 240000) }`	`Promise<{ sessionId, cdpUrl, liveViewUrl, expiresAt, verified, healed }>`
`registrations.openSession(id)`	—	same minus `verified`/`healed`; no freshness check
`registrations.closeSession(id)`	—	`Promise<void>`
`registrations.exportSession(id, opts?)`	`{ verify?, maxStaleSec? }`	`Promise<{ storageState }>`
`connections.connect(input)`	`{ appUrl, identityId?, credentials: { username, password, totpSeed? } }`	`Promise<{ connection, run }>`
`connections.list(identityId?)` / `connections.get(id)`	—	`Promise<(Registration & { latestRun })[]>` / `Promise<Registration>`
`connections.revoke(id)` / `connections.delete(id)`	—	`Promise<Registration>` / `Promise<void>`
`runs.get(id)` / `runs.resume(id)` / `runs.abort(id)`	—	`Promise<Run>`
`runs.waitForRun(id, opts?)`	`{ timeout? (ms, default 180000), pollMs? (default 2000) }`	`Promise<Run>`

Identities, for when you want to control the address

identityId 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).

const idt = await sente.identities.create({ name: "support-bot", localPart: "support-bot" });
// → { id, email: "support-bot@sente.run", ... }

A taken localPart throws a 409 (onConflict: "error" is the default); pass onConflict: "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

await 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):
await sente.messages.send(idt.id, {
  to: "user@example.com",
  subject: "Re: hi",
  text: "following up",
  inReplyTo: inboundMessageId,
});

text and/or html is required. messages.stream(identityId) is an async 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.
Python 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