Transactional email in Node.js that survives retries, restarts and bounces.

const { data, error } = await notix.emails.send(payload, {
  idempotencyKey: `order-${order.id}-receipt`,
});

if (error) {
  switch (error.code) {
    case "BAD_REQUEST":
      // The message names the field and the limit. Fix the payload; do not retry.
      throw new Error(error.message);
    case "UNAUTHORIZED":
    case "FORBIDDEN":
      // Wrong key, or a key restricted to another domain. Configuration, not luck.
      throw new Error(error.message);
    case "NOT_UNIQUE":
      // Same idempotency key, different body. Your key scheme has a bug.
      throw new Error(error.message);
    case "RATE_LIMITED":
      // Back off and retry with the same key; the key makes the retry safe.
      return retryLater(payload, order.id);
    default:
      // A 409 while the first request is still in flight, or a 5xx:
      // retry with the same key after a short delay.
      return retryLater(payload, order.id);
  }
}

console.log("queued", data.emailId);

const response = await fetch("https://app.usenotix.dev/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOTIX_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-receipt`,
  },
  body: JSON.stringify(payload),
});

if (response.ok) {
  const { emailId } = await response.json();
  console.log("queued", emailId);
} else if (response.status === 429 || response.status === 409 || response.status >= 500) {
  // Same key, later: the server returns the original emailId if the first
  // request went through, or a fresh one if it did not.
  await retryLater(payload, order.id);
} else {
  // 400, 401, 403: the body is { error: { code, message } }. Do not retry.
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

import express from "express";
import { Webhooks } from "notix-js";

const webhooks = new Webhooks(process.env.NOTIX_WEBHOOK_SECRET!);
const app = express();

// The signature is over the raw body, so this route must not go through
// express.json(): a re-serialised body verifies as tampered.
app.post("/webhooks/notix", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = webhooks.constructEvent(req.body, { headers: req.headers });

    switch (event.type) {
      case "email.delivered":
        await db.email.update({ where: { providerId: event.data.id }, data: { status: "delivered" } });
        break;
      case "email.bounced":
      case "email.complained":
      case "email.suppressed":
        await db.email.update({ where: { providerId: event.data.id }, data: { status: event.type } });
        break;
    }

    res.status(200).send("ok");
  } catch (error) {
    res.status(400).send((error as Error).message);
  }
});

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);
const webhooks = notix.webhooks(process.env.NOTIX_WEBHOOK_SECRET!);

export async function POST(request: Request) {
  try {
    // request.text(), never request.json(): the signature covers the raw bytes.
    const event = webhooks.constructEvent(await request.text(), { headers: request.headers });

    if (event.type === "email.delivered") {
      await db.email.update({ where: { providerId: event.data.id }, data: { status: "delivered" } });
    }
    if (event.type === "email.bounced") {
      await db.email.update({ where: { providerId: event.data.id }, data: { status: "bounced" } });
    }

    return new Response("ok");
  } catch (error) {
    return new Response((error as Error).message, { status: 400 });
  }
}