How to Send Email with Fastify

AHASEND_API_KEY=aha-sk-...
AHASEND_ACCOUNT_ID=your-account-uuid
AHASEND_WEBHOOK_SECRET=aha-whsec-...
WELCOME_ROUTE_TOKEN=replace-with-a-long-random-value

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

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

export const ahasend = new AhaSendClient({
  apiKey: requireEnv("AHASEND_API_KEY"),
  accountId: requireEnv("AHASEND_ACCOUNT_ID"),
});

export const welcomeRouteToken = requireEnv("WELCOME_ROUTE_TOKEN");

import Fastify from "fastify";
import rateLimit from "@fastify/rate-limit";
import { timingSafeEqual } from "node:crypto";
import { AhaSendAPIError, isAhaSendError } from "@ahasend/sdk";
import { ahasend, welcomeRouteToken } from "./lib/ahasend.js";

const app = Fastify({ logger: true });

// `global: false` keeps the limiter off the webhook route, where a 429 would
// only make AhaSend retry.
await app.register(rateLimit, { global: false });

type WelcomeBody = { email: string; name?: string; eventId: string };

const welcomeBodySchema = {
  type: "object",
  additionalProperties: false,
  required: ["email", "eventId"],
  properties: {
    email: { type: "string", format: "email", maxLength: 320 },
    name: { type: "string", maxLength: 100 },
    eventId: { type: "string", minLength: 1, maxLength: 200, pattern: "^[A-Za-z0-9._:-]+$" },
  },
} as const;

function isAuthorized(header: string | undefined): boolean {
  const supplied = Buffer.from(header ?? "");
  const expected = Buffer.from(`Bearer ${welcomeRouteToken}`);
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

app.post<{ Body: WelcomeBody }>(
  "/api/welcome",
  {
    bodyLimit: 16_384,
    schema: { body: welcomeBodySchema },
    config: { rateLimit: { max: 10, timeWindow: "1 minute" } },
  },
  async (request, reply) => {
    if (!isAuthorized(request.headers.authorization)) {
      return reply.code(401).send({ error: "Unauthorized" });
    }

    try {
      const result = await ahasend.messages.send({
        from: { email: "hello@yourdomain.com", name: "Your App" },
        recipients: [{ email: request.body.email, name: request.body.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.",
      }, { idempotencyKey: `welcome-${request.body.eventId}` });

      const rejected = result.data.filter((r) => r.status === "error");
      if (rejected.length > 0) {
        request.log.warn({ count: rejected.length }, "Recipients rejected");
        return reply.code(502).send({ error: "Recipient was not accepted" });
      }

      return reply.code(202).send({ accepted: true });
    } catch (err) {
      // Timeouts and connection failures are not `AhaSendAPIError`s. Catching
      // only that class lets them reach Fastify's default handler, which
      // echoes `err.message` — which can carry your account ID and the
      // upstream URL — straight back to the caller in a 500 body.
      if (!isAhaSendError(err)) throw err;
      request.log.error(
        {
          errorCode: err.code,
          status: err instanceof AhaSendAPIError ? err.status : undefined,
          requestId: err instanceof AhaSendAPIError ? err.requestId : undefined,
        },
        "AhaSend send failed",
      );
      return reply.code(502).send({ error: "Failed to send email" });
    }
  },
);

import rawBody from "fastify-raw-body";
import {
  WebhookVerifier,
  fastifyWebhookHandler,
  isKnownWebhookEvent,
} from "@ahasend/sdk/webhooks";

await app.register(rawBody, {
  field: "rawBody",
  global: false,
  encoding: false,
  runFirst: true,
});

const webhookSecret = process.env.AHASEND_WEBHOOK_SECRET;
if (!webhookSecret) {
  throw new Error("Missing required environment variable: AHASEND_WEBHOOK_SECRET");
}
const verifier = new WebhookVerifier(webhookSecret);

app.post(
  "/webhooks/ahasend",
  { bodyLimit: 1_000_000, config: { rawBody: true } },
  fastifyWebhookHandler(verifier, async (event) => {
    if (!isKnownWebhookEvent(event)) return; // future event type, acknowledge & ignore

    switch (event.type) {
      case "message.delivered":
        app.log.info({ webhookType: event.type });
        break;
      case "message.bounced":
        app.log.info({ webhookType: event.type });
        break;
      case "message.opened":
        app.log.info({ webhookType: event.type });
        break;
    }
  }, { maxBodyBytes: 1_000_000 }),
);

// Last statement in the file: no plugin or route can be added after this.
await app.listen({
  port: Number(process.env.PORT ?? 3000),
  host: "0.0.0.0",
});