<!-- Canonical: https://startupmail.dev/docs/sdk -->
<!-- Documentation index: https://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);
  }
}
```

## Available methods

`listMailboxes`, `listThreads`, `getThread`, `uploadAttachment`, `downloadAttachment`, `sendEmail`, `reply`, `listWebhooks`, `createWebhook`, and `deleteWebhook`.