TypeScript SDK

Install and initialize

During the beta, install the SDK directly from the public repository:

npm install github:startupmail/startupmail-sdk

The public SDK and examples repository is the canonical source until the npm package is published.

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

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

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

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

Send and reply

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.

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