Skip to main content

JavaScript SDK

The @spawnmail/sdk package provides a TypeScript client for the SpawnMail API.

Installation​

bun add @spawnmail/sdk

Initialization​

import SpawnMail from "@spawnmail/sdk";

const client = new SpawnMail("fm_your_api_key");

// With custom base URL (for self-hosted instances)
const client = new SpawnMail("fm_your_api_key", {
  baseUrl: "http://localhost:8000",
});
info

API keys must start with fm_. The default base URL is https://api.spawnmail.sh.

Methods​

createInbox(options?)​

Create a new disposable inbox.

const inbox = await client.createInbox({
  ttl: 300,           // Lifetime in seconds (optional)
  password: "secret", // Password-protect the inbox (optional)
});

// inbox.id       → unique ID (also the email local part)
// inbox.address  → full email: {id}@spawnmail.sh
// inbox.expires_at → ISO timestamp

waitForEmail(inboxId, options?)​

Long-poll until an email arrives or timeout elapses.

const email = await client.waitForEmail(inbox.id, {
  timeout: 30_000,    // Timeout in milliseconds
  password: "secret", // If inbox is password-protected
});

// email.sender, email.subject, email.body_text, email.body_html
caution

Timeout is in milliseconds for the JS SDK. The Python SDK uses seconds.

capture(options?)​

Create an inbox and wait for the first email in one call.

const { inbox, email } = await client.capture({
  ttl: 300,
  timeout: 30_000,
});

getEmails(inboxId, options?)​

List all emails in an inbox.

const emails = await client.getEmails(inbox.id);

getEmail(inboxId, emailId, options?)​

Get a single email by ID.

const email = await client.getEmail(inbox.id, emailId);

deleteInbox(inboxId, options?)​

Delete an inbox and all its emails.

await client.deleteInbox(inbox.id);

Password-Protected Inboxes​

All methods that access an inbox accept an optional password parameter:

const inbox = await client.createInbox({ password: "secret123" });
const emails = await client.getEmails(inbox.id, { password: "secret123" });
await client.deleteInbox(inbox.id, { password: "secret123" });

Types​

interface Inbox {
  id: string;
  address: string;
  password: string | null;
  created_at: string;
  expires_at: string;
  is_active: boolean;
}

interface Email {
  id: string;
  inbox_id: string;
  sender: string;
  subject: string | null;
  body_text: string | null;
  body_html: string | null;
  received_at: string;
}

interface CaptureResult {
  inbox: Inbox;
  email: Email;
}

Error Handling​

import { SpawnMailError } from "@spawnmail/sdk";

try {
  const inbox = await client.createInbox();
} catch (err) {
  if (err instanceof SpawnMailError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}

SpawnMailError has a .status property with the HTTP status code and a .message with the error description.