TypeScript SDK

The official shipmail package provides type-safe access to the full API. Works in Node.js 18+, Bun, Deno, and edge runtimes.

Last updated July 5, 2026

Installation

npm install shipmailbun add shipmail

Quick start

import ShipMail from "shipmail";

const shipmail = new ShipMail(process.env.SHIPMAIL_API_KEY);

// Send an email
const message = await shipmail.messages.send({
  from: "hello@yourdomain.com",
  to: ["recipient@example.com"],
  subject: "Hello from shipmail",
  text: "It works.",
});

console.log(message.id); // msg_...

Configuration

Pass a string for the API key alone, or an object for full control:

const shipmail = new ShipMail({
  apiKey: process.env.SHIPMAIL_API_KEY,
  baseUrl: "https://shipmail.to/api/v1",  // default
  maxRetries: 2,                           // default
  timeout: 30_000,                         // ms, default
  defaultHeaders: { "X-Custom": "value" },
});

Option	Default	Description
apiKey	required	Your `sm_live_...` key.
baseUrl	https://shipmail.to/api/v1	API base URL.
maxRetries	2	Retry count for 429 and 5xx responses.
timeout	30000	Request timeout in ms.
defaultHeaders	{}	Headers sent with every request.
fetch	globalThis.fetch	Custom fetch implementation for testing or proxying.

Resources

The client exposes each API resource as a property:

Property	Methods
shipmail.domains	create, list, get, update, delete, verify, search, register
shipmail.mailboxes	create, list, get, update, delete, updateAutoReply
shipmail.messages	send, get
shipmail.threads	list, get, reply
shipmail.webhooks	create, list, get, update, delete, rotateSecret, test, listDeliveries
shipmail.suppressions	list, remove
shipmail.audiences	create, list, get, update, delete
shipmail.audiences.subscribers	add, addBatch, list, get, getByEmail, update, unsubscribe, remove
shipmail.newsletters	create, createFromChangelog, list, get, update, preview, preflight, sendTest, schedule, cancel, resume
shipmail.newsletters.domains	list
shipmail.newsletters.assets	list, upload
shipmail.status	get

Newsletter workflow

Use blocks for editable newsletters. Prose fields inside blocks are plain text; use newlines for paragraph breaks. Use body_html or custom_html only when you need raw HTML.

import { readFile } from "node:fs/promises";

const newsletterDomains = await shipmail.newsletters.domains.list({ limit: 25 });
const assets = await shipmail.newsletters.assets.list({ kind: "image", limit: 25 });
const image = await shipmail.newsletters.assets.upload({
  filename: "feature.png",
  content_type: "image/png",
  data: await readFile("feature.png"),
});
const existingImage = await shipmail.newsletters.assets.registerFromUrl({
  url: "https://cdn.shipmail.to/newsletter-images/org_123/demo.png",
  filename: "demo.png",
});

console.log(assets.storage.used_bytes, assets.storage.limit_bytes);

const newsletter = await shipmail.newsletters.create({
  audience_id: "aud_...",
  newsletter_domain_id: newsletterDomains.data[0].id,
  name: "July changelog",
  subject: "What shipped in July",
  preview_text: "A quick product update",
  blocks: [
    { type: "heading", level: 1, text: "July updates" },
    { type: "callout", variant: "info", title: "Quick note", body: "A short intro." },
    { type: "paragraph", body: "Use blank lines for paragraph breaks." },
    { type: "image", url: image.url, alt: "Product screenshot" },
    { type: "image", url: existingImage.url, alt: "Existing CDN screenshot" },
    {
      type: "columns",
      ratio: "50-50",
      left: { title: "For teams", body: "Shared inbox improvements." },
      right: { title: "For agents", body: "API and MCP improvements." },
    },
  ],
});

await shipmail.newsletters.preview(newsletter.id);
await shipmail.newsletters.sendTest(newsletter.id, {
  recipient_email: "owner@example.com",
});
await shipmail.newsletters.preflight(newsletter.id);
await shipmail.newsletters.schedule(newsletter.id, {
  scheduled_at: "2026-08-01T09:00:00.000Z",
});

Preflight returns a URL breakdown. Links, images, and video thumbnails count toward the 20 unique URL limit.

Error handling

API errors throw typed subclasses of ShipMailError. Each error exposes status, type, requestId, and retryable. Newsletter guardrail failures on test-send and schedule are ValidationErrors with preflight fields in details.

import ShipMail, {
  ValidationError,
  RateLimitError,
  ShipMailError,
} from "shipmail";

try {
  await shipmail.messages.send({ ... });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.details); // per-field errors
  } else if (err instanceof RateLimitError) {
    console.log(err.retryAfter); // seconds to wait
  } else if (err instanceof ShipMailError) {
    console.log(err.status, err.requestId);
  }
}

Class	Status
AuthenticationError	401
AuthorizationError	403
ValidationError	422
NotFoundError	404
ConflictError	409
RateLimitError	429
InternalServerError	500
ConnectionError	Network failure

Pagination

List methods return a Page object that implements AsyncIterable. Iterate with for await to automatically fetch all pages:

const domains = shipmail.domains.list();

for await (const domain of domains) {
  console.log(domain.name);
}

Pass limit and cursor for manual control:

const page = shipmail.domains.list({ limit: 10 });

Webhook verification

The SDK exports a standalone verifyWebhook function. It is async because it dynamically imports the crypto module for portability.

import { verifyWebhook } from "shipmail";

const event = await verifyWebhook(
  rawBody,
  request.headers,
  process.env.WEBHOOK_SECRET,
);

console.log(event.event_type); // "message.received"

Throws WebhookVerificationError if the signature is invalid or the timestamp is outside the 5-minute tolerance window. Pass { toleranceInSeconds: 600 } to customize.

Per-request options

Every method accepts an optional last argument for request-level overrides:

await shipmail.domains.create(
  { name: "example.com" },
  {
    idempotencyKey: "550e8400-...",
    timeout: 10_000,
    signal: AbortSignal.timeout(5000),
  },
);