Mailosaur

Stateful mock of the Mailosaur email/SMS testing API for test suites, plus an HTTP ingest so anything that "sends" mail (the Resend mock's --forward-to-inbox, the Twilio mock, Cognito hooks, a test) drops it into one inbox. The unmodified mailosaur SDK reads it: messages.get returns within ~20 ms of a message arriving instead of long-polling Mailosaur for up to 120 s, and html.codes / text.codes / html.links are parsed the way Mailosaur parses them.

• Operation coverage: SUPPORT.md
• The vendor publishes no OpenAPI spec: openapi.yaml is hand-authored from mailosaur@11.1.0 (the requests it sends and the fields its models read) and our consumer's client.

#Install

npm install -D @crvouga/mockingbird-service-mailosaur

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-mailosaur serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

#Pointing the mailosaur SDK at it

The SDK only speaks HTTPS (https.request, whatever the base URL's scheme) and drops the base URL's port (it passes only the hostname and path, so it always connects to 443). So a MAILOSAUR_BASE_URL alone (G-M1) only works if the mock listens on 443. The mock's secure port therefore also acts as an HTTP CONNECT proxy that tunnels every target into the mock (never to the network). The SDK honours HTTPS_PROXY, reading it once, when a client is constructed:

npx mockingbird-mailosaur serve --port 8793 --tls-port 8794 --tls-cert-out /tmp/mailosaur-mock.pem
# in the process that constructs the SDK client:
HTTPS_PROXY=http://127.0.0.1:8794 NODE_EXTRA_CA_CERTS=/tmp/mailosaur-mock.pem

With that, new MailosaurClient(apiKey) keeps its default https://mailosaur.com/ and every call lands in the mock. The generated certificate names localhost, 127.0.0.1 and mailosaur.com. Set HTTPS_PROXY only around the SDK construction if the rest of the process must not see it, since other HTTP clients (axios) also read it and would be tunnelled into the mock too. If the mock can bind 443, --tls-port 443 and new MailosaurClient(key, "https://127.0.0.1/") work without the proxy.

import { createServer } from "@crvouga/mockingbird-service-mailosaur/server"
import MailosaurClient from "mailosaur"

const inbox = await createServer({ tls: true })
// …trust inbox.cert (NODE_EXTRA_CA_CERTS, or tls.setDefaultCACertificates in a test)…
process.env.HTTPS_PROXY = inbox.proxyUrl
const mailosaur = new MailosaurClient("any-key")
delete process.env.HTTPS_PROXY

// Something "sends" the signup email:
await fetch(`${inbox.url}/__admin/ingest`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    to: "member-app-x1@abcd1234.mailosaur.net",
    subject: "Your verification code",
    text: "Your verification code is 604218. ",
  }),
})
const message = await mailosaur.messages.get("abcd1234", { sentTo: "member-app-x1@abcd1234.mailosaur.net" })
message.text?.codes?.[0]?.value // "604218"

The inbox can also be read without the SDK, through the admin routes:

import { createServer } from "@crvouga/mockingbird-service-mailosaur/server"

const inbox = await createServer()
const response = await fetch(`${inbox.url}/__admin/ingest`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ to: "member-app-x1@abcd1234.mailosaur.net", text: "Your verification code is 604218. " }),
})
const { id } = (await response.json()) as { id: string }
const { codes } = (await (await fetch(`${inbox.url}/__admin/outbox/${id}/links`)).json()) as { codes: string[] }
// codes[0] === "604218"
await inbox.close()

#Routes

Auth is Authorization: Basic base64(<api key>:) (what the SDK sends); any key works, none is a 401 authentication_error. A 400 names the field the way the SDK's error parser expects ({errors: [{field, detail: [{description}]}]}).

Servers are implicit. A message's server is, in order: the ingest's server, the id in a <server>.mailosaur.net recipient, or * (visible from every server id). receivedAfter keeps messages received at or after the instant (on the mock clock).

Codes and links. codes[] lists every distinct standalone run of 4–8 digits in the readable text (HTML without head, styles, scripts, tags; entities decoded), ignoring digits inside URLs. Our consumer keeps the first 6-digit one. html.links is every <a href> with its text; text.links every URL in the text body.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): auth_failed (401, SDK authentication_error), rate_limited (429 on search, SDK api_error), server_error (500), search_never_matches (searches find nothing, so messages.get ends in search_timeout), slow_search (2 s latency).

#Namespaces

The SDK cannot add headers, so a namespace can be chosen by API key: PUT /__admin/credentials {"credentials": {"<MAILOSAUR_API_KEY>": "<namespace>"}}. Also x-mockingbird-namespace or a /ns/<name> prefix for raw HTTP callers. Ingest into a namespace with x-mockingbird-namespace (the Resend mock forwards with its own namespace name).

#Deliberately not modelled

• Real delivery: there is no SMTP listener. Mail arrives only through the ingest route, messages.create, or another mock's --forward-to-inbox.
• Servers, usage, devices (TOTP), previews, spam/deliverability analysis, forward and reply, and file downloads (attachment urls are placeholders; ingest keeps only attachment metadata).
• Mailosaur's exact code detector is not published. The mock's rule (standalone 4–8 digit runs, not inside URLs) reproduces it for our templates (Cognito's "Your verification code is {####}.").
• Server ids are not validated against an account; any 8-character id is an (empty) inbox.

#API

Part of mockingbird.