How to Send Email with Koa

AHASEND_API_KEY=aha-sk-...
AHASEND_ACCOUNT_ID=your-account-uuid
AHASEND_WEBHOOK_SECRET=aha-whsec-...
AHASEND_DELIVERY_MODE=sandbox
WELCOME_ENDPOINT_TOKEN=a-long-random-server-to-server-token

import { AhaSendClient } from "@ahasend/sdk";

export function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

export const deliveryMode = requireEnv("AHASEND_DELIVERY_MODE");
if (deliveryMode !== "sandbox" && deliveryMode !== "live") {
  throw new Error("AHASEND_DELIVERY_MODE must be sandbox or live");
}

export const ahasend = new AhaSendClient({
  apiKey: requireEnv("AHASEND_API_KEY"),
  accountId: requireEnv("AHASEND_ACCOUNT_ID"),
});
export const sandboxMode = deliveryMode === "sandbox";
export const welcomeToken = requireEnv("WELCOME_ENDPOINT_TOKEN");

import { createHash, timingSafeEqual } from "node:crypto";
import Koa from "koa";
import type { Middleware } from "koa";
import Router from "@koa/router";
import { bodyParser } from "@koa/bodyparser";
import { AhaSendAPIError } from "@ahasend/sdk";
import { ahasend, deliveryMode, sandboxMode, welcomeToken } from "./lib/ahasend.js";

const app = new Koa();
const router = new Router();
const expectedTokenHash = createHash("sha256").update(welcomeToken).digest();
const uuidPattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

const requireWelcomeToken: Middleware = async (ctx, next) => {
  const authorization = ctx.get("authorization");
  const provided = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
  const providedHash = createHash("sha256").update(provided).digest();
  if (!provided || !timingSafeEqual(providedHash, expectedTokenHash)) {
    ctx.status = 401;
    return;
  }
  await next();
};

router.post("/api/welcome", requireWelcomeToken, async (ctx) => {
  const input = ctx.request.body as Record<string, unknown>;
  const eventID = input?.event_id;
  const email = input?.email;
  const name = input?.name;
  if (
    typeof eventID !== "string" ||
    !uuidPattern.test(eventID) ||
    typeof email !== "string" ||
    email.length > 320 ||
    !emailPattern.test(email) ||
    (name !== undefined && (typeof name !== "string" || name.length > 200))
  ) {
    ctx.status = 400;
    ctx.body = { error: "Invalid request" };
    return;
  }

  try {
    const result = await ahasend.messages.send({
      from: { email: "hello@yourdomain.com", name: "Your App" },
      recipients: [{ email, name }],
      subject: "Welcome to Your App!",
      html_content: "<h1>Welcome aboard 🎉</h1><p>We're glad you're here.</p>",
      text_content: "Welcome aboard! We're glad you're here.",
      sandbox: sandboxMode,
    }, { idempotencyKey: `welcome-${deliveryMode}-${eventID}` });

    const accepted = result.data.filter((entry) =>
      entry.status === "queued" || entry.status === "scheduled"
    );
    const rejected = result.data.length - accepted.length;
    if (rejected > 0 || accepted.length === 0) {
      console.error("AhaSend rejected recipients", { count: rejected });
      ctx.status = 502;
      ctx.body = { error: "Email was not accepted" };
      return;
    }

    ctx.status = 202;
    ctx.body = { queued: accepted.length };
  } catch (err) {
    if (err instanceof AhaSendAPIError) {
      console.error("AhaSend request failed", {
        status: err.status,
        code: err.code,
        requestId: err.requestId,
      });
      ctx.status = 502;
      ctx.body = { error: "Failed to send email" };
      return;
    }
    throw err;
  }
});

app.on("error", () => console.error("Unhandled request error"));
app.use(bodyParser({ enableTypes: ["json"], jsonLimit: "64kb" }));
app.use(router.routes()).use(router.allowedMethods());

const server = app.listen(Number(process.env.PORT ?? 3000));
server.requestTimeout = 30_000;
server.headersTimeout = 10_000;
server.keepAliveTimeout = 5_000;

for (const signal of ["SIGINT", "SIGTERM"] as const) {
  process.once(signal, () => {
    server.close((error) => {
      if (error) process.exitCode = 1;
    });
  });
}

import { requireEnv } from "./lib/ahasend.js";
import getRawBody from "raw-body";
import {
  AhaSendWebhookVerificationError,
  type AnyWebhookEvent,
  WebhookVerifier,
  isKnownWebhookEvent,
} from "@ahasend/sdk/webhooks";

interface WebhookStore {
  // Atomically commit webhookId and durable work for event.
  // Return false when that ID was already committed.
  enqueueOnce(webhookId: string, event: AnyWebhookEvent): Promise<boolean>;
}

const WEBHOOK_BODY_LIMIT_BYTES = 1_000_000;

export function createAhaSendWebhookRouter(secret: string, store: WebhookStore): Router {
  const verifier = new WebhookVerifier(secret);
  const webhookRouter = new Router();

  webhookRouter.post("/webhooks/ahasend", async (ctx) => {
    let raw: Buffer;
    try {
      raw = await getRawBody(ctx.req, { limit: WEBHOOK_BODY_LIMIT_BYTES });
    } catch (error) {
      // An aborted read leaves the rest of the body on the socket, which
      // would corrupt the next request on a keep-alive connection.
      ctx.set("connection", "close");
      ctx.status =
        typeof error === "object" && error !== null && "status" in error && error.status === 413
          ? 413
          : 400;
      return;
    }

    try {
      const event = await verifier.parse(ctx.req.headers, raw);
      if (!isKnownWebhookEvent(event)) {
        ctx.status = 204;
        return;
      }

      const webhookID = ctx.get("webhook-id");
      const accepted = await store.enqueueOnce(webhookID, event);
      ctx.status = accepted ? 202 : 200;
    } catch (error) {
      if (error instanceof AhaSendWebhookVerificationError) {
        ctx.status = error.reason === "body_too_large" ? 413 : 400;
        return;
      }
      throw error;
    }
  });

  return webhookRouter;
}

// Replaces the two mounting lines in the first block. Koa composes its
// middleware when app.listen() runs, so every app.use() must precede it.
const webhookRouter = createAhaSendWebhookRouter(
  requireEnv("AHASEND_WEBHOOK_SECRET"),
  webhookStore, // your durable WebhookStore implementation
);
app.use(webhookRouter.routes()).use(webhookRouter.allowedMethods());
app.use(bodyParser({ enableTypes: ["json"], jsonLimit: "64kb" }));
app.use(router.routes()).use(router.allowedMethods());