A TypeScript SDK for the mxRaven mail-facing runtime surfaces: SMTP submission, webhook verification and decoding, and recipient feedback.
It is the TypeScript counterpart of the Go SDK at
github.com/synqronlabs/mxraven-go/mail
and exposes the same capabilities behind an idiomatic TypeScript API.
Status: early development. The public API is not yet stable.
pnpm add @mxraven/mail
import { Client, Message } from "@mxraven/mail";
const secret = process.env.MXRAVEN_SECRET;
if (secret === undefined || secret === "") {
throw new Error("MXRAVEN_SECRET is required");
}
const client = new Client({
host: "smtp.mxraven.com",
username: "mxr_tx_ab12cd34ef56",
secret,
});
const result = await client.send(
new Message()
.from("Acme <noreply@acme.example>")
.to("customer@example.com")
.subject("Your receipt")
.text("Thanks for your order.")
.html("<p>Thanks for your order.</p>"),
);
console.log("accepted as", result.messageRef);
await client.close();
The submission service requires STARTTLS and SMTP AUTH, so both are always
used. The SDK does not read environment variables itself; the example validates
the variable before constructing the client. Load secrets from a secret manager
in production. Setting both a plain-text and an HTML body produces a
multipart/alternative message; attachFile and attachInline add
multipart/mixed attachments.
Use sendRaw to stream an already serialized RFC 5322 message with an explicit
envelope. The caller is responsible for RFC 5322 correctness.
await client.sendRaw(
{ from: "bounce@acme.example", to: ["customer@example.com"] },
rawMessageBytes,
);
Rejected commands throw SMTPError; when every recipient is rejected,
SMTPTransactionError is thrown with the per-recipient result.
import { SMTPError } from "@mxraven/mail";
try {
await client.send(message);
} catch (error) {
if (error instanceof SMTPError && error.permanent) {
// 5xx: do not retry the same message.
}
}
Verification and decoding live in a separate entry point that uses the webhook signing secret, not the submission API key.
import { Verifier, eventType, fetchRawEmail } from "@mxraven/mail/webhook";
const signingSecret = process.env.MXRAVEN_WEBHOOK_SECRET;
if (signingSecret === undefined || signingSecret === "") {
throw new Error("MXRAVEN_WEBHOOK_SECRET is required");
}
const verifier = new Verifier({ secret: signingSecret });
const event = await verifier.verifyAndDecode(request);
if (event.type === eventType.inboundEmail) {
const raw = await fetchRawEmail(event.inboundEmail.raw_email);
}
The signing secret is used as literal key bytes; do not base64-decode it. Pass
per-key secrets to Verifier with keys for rotation. The raw-email
access_token is a secret; do not log it.
Verifier accepts a WHATWG Request.
Runtimes and frameworks that provide one work directly: Cloudflare Workers,
Deno, Bun, Next.js (App Router), Remix, SvelteKit, Astro, Hono (c.req.raw),
and @whatwg-node/server.
Node frameworks expose their own request objects — IncomingMessage in
Express, FastifyRequest in Fastify, ctx in Koa. Bridge them by constructing
a Request, keeping two things in mind:
X-Forwarded-Proto/X-Forwarded-Host, not Host.import express from "express";
const app = express();
app.post(
"/mxraven/webhook",
express.raw({ type: "*/*" }), // keeps the exact bytes on req.body
async (req, res) => {
const request = new Request(`https://${req.headers.host}${req.originalUrl}`, {
method: req.method,
headers: req.headers as HeadersInit,
body: req.body,
});
const event = await verifier.verifyAndDecode(request);
res.sendStatus(204);
},
);
In Fastify, capture the raw buffer in an addContentTypeParser hook, then build
the Request from request.method, request.url, and request.headers.
decode operates on bytes alone, so it can be used without any request object.
The runtime surfaces are published as separate entry points so the root import stays free of webhook and feedback code:
@mxraven/mail/webhook — HMAC-SHA256 verification, payload decoding, and raw
message download.@mxraven/mail/feedback — tenant spam/ham training and RFC 8058 one-click
unsubscribes.Teach the spam filter with the exact raw message bytes mxRaven processed, or perform a one-click unsubscribe. Learning uses the same submission API key as SMTP submission, over HTTP Basic auth.
import { Client } from "@mxraven/mail/feedback";
const secret = process.env.MXRAVEN_SECRET;
if (secret === undefined || secret === "") {
throw new Error("MXRAVEN_SECRET is required");
}
const feedback = new Client({
baseUrl: "https://feedback.mxraven.com",
username: "mxr_tx_ab12cd34ef56",
secret,
});
await feedback.learnSpam(rawMessageBytes);
Requires Node.js 20.19 or later and pnpm.
pnpm install # install dependencies
pnpm run build # dual ESM + CJS build with declarations (tsdown)
pnpm run test # vitest
pnpm run lint # oxlint (includes TSDoc validation)
pnpm run format # oxfmt
pnpm run docs # typedoc (Markdown) into docs/
pnpm run check runs formatting, lint, typecheck, test, and build in sequence.
| Concern | Tool |
|---|---|
| Language / typecheck | TypeScript (tsc --noEmit), NodeNext, strict |
| Build (dual ESM + CJS) | tsdown (Rolldown) with declarations and source maps |
| Testing | Vitest |
| Lint / format | oxlint + oxfmt |
| TSDoc validation | eslint-plugin-tsdoc loaded as an oxlint JS plugin |
| API docs | TypeDoc + typedoc-plugin-markdown |
| Versioning / release | Changesets, published from GitHub Actions with npm publish --provenance |
Releases are managed with Changesets. Add a changeset with pnpm run changeset;
merging the generated release pull request bumps versions and publishes to npm
with provenance.