Send email from Express: a route, a middleware, a webhook.

// src/notix.ts
import "dotenv/config";
import { Notix } from "notix-js";

if (!process.env.NOTIX_API_KEY) {
  throw new Error("NOTIX_API_KEY is not set");
}

// Pointing at a different Notix base URL (a staging environment, say)?
// Pass it as the second argument.
export const notix = new Notix(process.env.NOTIX_API_KEY);

// src/routes/send.ts
import { Router } from "express";
import { notix } from "../notix.js";

export const send = Router();

// express.json() has already parsed the body by the time this runs.
send.post("/api/send-receipt", async (req, res, next) => {
  const { orderId, to } = req.body as { orderId?: string; to?: string };
  if (!orderId || !to) {
    return res.status(400).json({ error: "orderId and to are required" });
  }

  const { data, error } = await notix.emails.send(
    {
      from: "receipts@acme.com",
      to,
      templateId: "tpl_receipt_v4",
      variables: { orderId },
    },
    // One key per business event, so a retried request can never send twice.
    { idempotencyKey: `order-${orderId}-receipt` },
  );

  if (error) return next(error); // handled by the middleware below
  res.status(202).json({ emailId: data.emailId });
});

// src/errors.ts
import type { ErrorRequestHandler } from "express";

// The API answers every failure as { code, message }; the SDK hands it back as
// `error` instead of throwing. This maps the code to the status your own
// client should see, and never forwards the raw message for a 5xx.
const STATUS: Record<string, number> = {
  BAD_REQUEST: 400,
  UNAUTHORIZED: 500, // our key is wrong, not the caller's problem
  FORBIDDEN: 500,
  NOT_FOUND: 404,
  NOT_UNIQUE: 409,
  RISK_REFUSED: 422,
  INSUFFICIENT_BALANCE: 402,
  RATE_LIMITED: 429,
  INTERNAL_SERVER_ERROR: 502,
  SERVICE_UNAVAILABLE: 503,
};

export const notixErrors: ErrorRequestHandler = (err, _req, res, next) => {
  if (err && typeof err === "object" && "code" in err && "message" in err) {
    const code = String(err.code);
    const status = STATUS[code] ?? 500;
    if (status >= 500) console.error("notix", code, err.message);
    return res.status(status).json({
      error: status >= 500 ? "Email could not be sent" : String(err.message),
    });
  }
  next(err);
};

// src/routes/webhooks.ts
import express, { Router } from "express";
import { notix } from "../notix.js";

export const webhooks = Router();
const verifier = notix.webhooks(process.env.NOTIX_WEBHOOK_SECRET!);

// The signature is computed over the raw bytes, so this route must not go
// through express.json(): express.raw keeps req.body as a Buffer.
webhooks.post(
  "/webhooks/notix",
  express.raw({ type: "application/json" }),
  (req, res) => {
    let event;
    try {
      event = verifier.constructEvent(req.body, { headers: req.headers });
    } catch {
      return res.status(400).send("invalid signature");
    }

    switch (event.type) {
      case "email.delivered":
        // event.data.id is the emailId the send returned
        break;
      case "email.bounced":
        // event.data.bounce.type === "Permanent" means the address is now suppressed
        break;
    }

    // Answer fast; do real work on a queue. Notix retries a non-2xx six times.
    res.sendStatus(200);
  },
);

// src/app.ts
import express from "express";
import { send } from "./routes/send.js";
import { webhooks } from "./routes/webhooks.js";
import { notixErrors } from "./errors.js";

const app = express();

// Mount the webhook router BEFORE express.json(), so its raw parser wins.
app.use(webhooks);
app.use(express.json());
app.use(send);
app.use(notixErrors);

app.listen(3000, () => console.log("listening on :3000"));