<!-- Canonical: https://staging.startupmail.dev/docs/sdk -->
<!-- Documentation index: https://staging.startupmail.dev/llms.txt -->

# TypeScript SDK

> Use the typed Startup Mail client to work with mailboxes, threads, messages, files, and webhooks.

## Install and initialize

```bash
npm install @startupmail/sdk
```

Create one client per API key or workload. Keep the key on the server.

```ts
import { StartupMail } from "@startupmail/sdk";

const mail = new StartupMail({
  apiKey: process.env.STARTUPMAIL_API_KEY!,
});
```

For local or self-hosted development, set `baseUrl`. Tests can also provide a custom `fetch` implementation.

## Read mail

```ts
const mailboxes = await mail.listMailboxes();
const threads = await mail.listThreads({
  mailboxId: mailboxes[0].id,
  label: "inbox",
});
const thread = await mail.getThread(threads[0].id);
```

The key needs `mailboxes:read` to list mailboxes and `mail:read` to read threads.

## Send and reply

```ts
const message = await mail.sendEmail({
  mailboxId: mailboxes[0].id,
  to: ["founder@example.com"],
  subject: "Hello",
  text: "Sent from Startup Mail",
});

await mail.reply({
  mailboxId: mailboxes[0].id,
  replyToMessageId: message.messageId,
  to: ["founder@example.com"],
  subject: "Re: Hello",
  text: "One more detail.",
});
```

## Handle errors

The client throws `StartupMailError` for non-success responses. It includes `status`, stable `code`, and the response `requestId` when available.

```ts
import { StartupMailError } from "@startupmail/sdk";

try {
  await mail.getThread("thr_missing");
} catch (error) {
  if (error instanceof StartupMailError) {
    console.error(error.status, error.code, error.requestId);
  }
}
```

## Agent control plane

The SDK is now organized around public resources rather than dashboard workflows. Use
`createTenant`, `createDomain`, `createMailbox`, `createDraft`, `listDrafts`,
`updateDraft`, `sendDraft`, `createMailboxPolicy`, and `listMailboxPolicies` for agent products.
See [Agent inboxes](https://staging.startupmail.dev/docs/agent-inboxes.md) for a complete provisioning flow.

## Available methods

`listMailboxes`, `listThreads`, `getThread`, `uploadAttachment`, `downloadAttachment`, `sendEmail`, `reply`, `listWebhooks`, `createWebhook`, `deleteWebhook`, and the agent-control methods above.

## Python

The Python SDK lives in `packages/python`. Install it from the package directory while it is being
published, then create `StartupMail("sm_live_...")`. It provides the same provisioning, draft, and
policy resources as the TypeScript SDK. Create and revoke API keys in the authenticated web app.