@mailbase/sdk

Official TypeScript/JavaScript SDK for Mailbase — an email API for developers. Zero dependencies, works in Node.js ≥ 18, edge runtimes, and browsers.

Install

npm install @mailbase/sdk

Send an email

import { Mailbase } from "@mailbase/sdk";

const mailbase = new Mailbase("mb_live_..."); // or set MAILBASE_API_KEY

const { id } = await mailbase.emails.send({
  from: "Acme <[email protected]>",
  to: "[email protected]",
  subject: "Hello",
  html: "<strong>It works!</strong>",
});

Idempotent sends, scheduling, batch:

await mailbase.emails.send(
  { from: "...", to: "...", subject: "...", text: "...", scheduled_at: "2026-08-01T09:00:00Z" },
  { idempotencyKey: "welcome/user_123" }
);

await mailbase.emails.batch([
  { from: "...", to: "[email protected]", subject: "Hi A", text: "..." },
  { from: "...", to: "[email protected]", subject: "Hi B", text: "..." },
]);

Read config and delivery data

await mailbase.domains.list(); // sending domains: status, region, DNS records
await mailbase.domains.get(domainId);
await mailbase.emails.get(emailId);
await mailbase.emails.events(emailId); // delivery timeline
await mailbase.suppressions.list(); // bounced/complained recipients
await mailbase.suppressions.add("[email protected]"); // e.g. on unsubscribe

Account settings live in the dashboard. Creating and verifying domains, managing webhook endpoints, and issuing API keys are done in the Mailbase dashboard — the SDK intentionally does not expose these management operations. It covers sending and the read/business data your application needs at runtime.

The entire SDK surface works with a sending_access key — issue those to integrating applications. Keys scoped to a domain only see that domain's emails and config.

Errors throw MailbaseError with status, type, code, and param. Requests that hit 429/5xx are retried automatically (respecting retry-after, max 2 retries by default).

Verify webhooks

import { verifyWebhookSignature } from "@mailbase/sdk/webhooks";

const valid = await verifyWebhookSignature({
  payload: rawRequestBody, // exact raw body string
  headers: {
    "mailbase-id": req.headers["mailbase-id"],
    "mailbase-timestamp": req.headers["mailbase-timestamp"],
    "mailbase-signature": req.headers["mailbase-signature"],
  },
  secret: process.env.MAILBASE_WEBHOOK_SECRET, // mbwh_...
});

Support chat widget

Embed the Mailbase support chat on your site — conversations land in your shared inbox, replies reach the visitor in the widget and by email. Enable it first in Settings → Chat widget, then:

// React / Next.js (client component)
"use client";
import { useEffect } from "react";
import { loadWidget } from "@mailbase/sdk/widget";

export function SupportWidget() {
  useEffect(() => loadWidget({ inboxId: "inb_...", theme: "auto" }), []);
  return null;
}

// Any other frontend
import { loadWidget } from "@mailbase/sdk/widget";
loadWidget({ inboxId: "inb_...", theme: "auto" }); // returns a cleanup function

// Zero-config: register your domains in Settings → Chat widget, then just
loadWidget(); // the inbox is resolved from this page's domain

The loader is a ~1KB, dependency-free script-tag injector — the widget itself (React, styles, shadow-root isolation) loads from the Mailbase CDN. SSR-safe and idempotent. theme accepts dark, light or auto.

Inbox Widget for teams

Embed the full shared inbox in your own dashboard so your staff can read, reply and start emails to customers without leaving it. Two halves:

1. Backend — mint a session with your secret key (never expose the key):

// e.g. GET /internal/mailbase-session, behind your own staff auth
const session = await mailbase.inbox.createWidgetSession({
  staff: { email: req.user.email, name: req.user.name }, // attribution
  ttl_seconds: 8 * 3600,
});
res.json({ token: session.token });

2. Frontend — load the widget with a token refresher:

import { loadInboxWidget } from "@mailbase/sdk/inbox";

const inbox = loadInboxWidget({
  getToken: () => fetch("/internal/mailbase-session").then(r => r.json()).then(d => d.token),
  theme: "auto",
  staffLabel: "[email protected]",
  cta: { mode: "auto", exclude: ["#billing"] },
});

inbox.compose({ to: "[email protected]" }); // programmatic

The CTA injector puts a small ✉ button next to email addresses in your dashboard; clicking it opens the widget's compose screen with To prefilled. manual mode (default) only decorates elements you mark with data-mailbase-compose="[email protected]"; auto additionally scans text and mailto links — use exclude to fence off areas. Replies your staff send are attributed to them ("Trang from Acme") and audited per session.

Configuration

new Mailbase(apiKey, {
  baseUrl: "https://api.mailbase.work", // override for self-hosted deployments
  maxRetries: 2,
});

License

MIT