DEVELOPERS / TYPESCRIPT

TypeScript SDK

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

Install and initialize

EXAMPLE

npm install @startupmail/sdk

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

EXAMPLE

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

EXAMPLE

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

EXAMPLE

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.

EXAMPLE

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.

Loading documentation…

Install and initialize

EXAMPLE

npm install @startupmail/sdk

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

EXAMPLE

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.

Send and reply

EXAMPLE

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.

EXAMPLE

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);
  }
}