Node SDK

npm i mailbay

import { Mailbay } from "mailbay";

// Reads MAILBAY_API_KEY when no key is given.
const mailbay = new Mailbay();

// Or pass the key and options yourself.
const custom = new Mailbay("mb_live_xxxxxxxxx", {
  maxRetries: 3,
  timeoutMs: 30_000,
});

// Send now. Every send gets an Idempotency-Key, so a retry never sends twice.
const { id } = await mailbay.emails.send({
  from: "Acme <noreply@acme.com>",
  to: "bob@example.com",
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
});

// Send later: an ISO 8601 string, a Date, or "in 2 hours".
const later = await mailbay.emails.send({
  from: "Acme <noreply@acme.com>",
  to: "bob@example.com",
  subject: "Your trial ends tomorrow",
  text: "Hi Bob, your trial ends tomorrow.",
  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
});
await mailbay.emails.reschedule(later.id, "2026-10-21T09:00:00Z");
await mailbay.emails.cancel(later.id);

// Up to 100 emails in one request.
const { data, errors } = await mailbay.emails.batch(
  [
    { from: "Acme <noreply@acme.com>", to: "alice@example.com", subject: "Hi Alice", text: "Hello" },
    { from: "Acme <noreply@acme.com>", to: "bob@example.com", subject: "Hi Bob", text: "Hello" },
  ],
  { batchValidation: "permissive" },
);

// Read the status, and page through the sent log.
const email = await mailbay.emails.get(id); // email.status, email.recipients
const page = await mailbay.emails.list({ limit: 20 }); // page.data, page.next_cursor

const inbox = await mailbay.inboxes.create({ local_part: "signup-test" });

// Block until the code arrives (up to 120 seconds). null when nothing came in time.
const got = await mailbay.messages.wait(inbox.id, { from: "github.com", timeout: 60 });
console.log(got?.codes[0]);

// Send from the inbox and reply in the thread.
const sent = await mailbay.messages.send(inbox.id, {
  to: "bob@example.com",
  subject: "Hello",
  text: "Hi Bob",
});
await mailbay.messages.reply(sent.id, { text: "One more thing", reply_all: true });

const { data: messages, next_cursor } = await mailbay.messages.list(inbox.id, { limit: 50 });
const raw = await mailbay.messages.raw(messages[0].id); // the .eml as a string
const { data: threads } = await mailbay.threads.list(inbox.id);
const thread = await mailbay.threads.get(threads[0].id); // the thread with its messages

// The shared inbox view: open, closed and snoozed conversations.
const open = await mailbay.conversations.list({ status: "open", assignee: "me" });
await mailbay.conversations.update(open.data[0].id, { status: "closed" });

const domain = await mailbay.domains.create({ name: "acme.com" });
for (const r of domain.records) console.log(r);  // publish these DNS records

// Later: check the records now. Accepts the id or the name.
const checked = await mailbay.domains.verify("acme.com");
console.log(checked.status, checked.next_step); // "verified" when every record is in place

const hook = await mailbay.webhooks.create({
  url: "https://example.com/hooks/mailbay",
  event_types: ["message.delivered", "message.bounced", "message.scheduled"],
});
// hook.secret is whsec_..., shown once: store it to verify signatures.

const { key, secret } = await mailbay.keys.create({
  name: "production sender",
  permissions: "sending",
  domain_id: "acme.com",
});
// secret is the API key, shown once.

await mailbay.suppressions.delete("bob@example.com");
const { data: events, next_after } = await mailbay.events.list({ limit: 100 });
const { data: senders } = await mailbay.senders.list(); // addresses you can use as from

import { Mailbay, MailbayError } from "mailbay";

try {
  await mailbay.emails.send({ from: "me@unverified.dev", to: "bob@example.com", subject: "Hi", text: "Hi" });
} catch (err) {
  if (err instanceof MailbayError) {
    console.log(err.status);  // 403
    console.log(err.code);    // "sender_not_verified"
    console.log(err.message); // "unverified.dev is not a domain of this project, ..."
    console.log(err.fix);     // "Add the domain with `mailbay domain add unverified.dev`, ..."
  }
  throw err;
}

import { verifyWebhook } from "mailbay";

// Next.js route handler, Workers, Deno or Bun: any runtime with Request.
export async function POST(req: Request) {
  const event = await verifyWebhook({
    payload: await req.text(), // the raw body, before any JSON parsing
    headers: req.headers,
    secret: process.env.MAILBAY_WEBHOOK_SECRET!,
  });
  if (event.type === "message.bounced") {
    // event.data.recipient, event.data.response, ...
  }
  return new Response(null, { status: 204 });
}