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

Available methods

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