How to Build Email Features with Windsurf

---
trigger: model_decision
description: Apply the project's AhaSend transactional email and webhook safety rules
---

# AhaSend email

When this project sends email, use the official AhaSend Node.js SDK.

- Package: `@ahasend/sdk` on npm. Do not invent a
  package name and do not hand-roll fetch calls to the REST API.
- Server-side only. Never import the SDK or expose credentials in browser
  code. The constructor's browser check is defense in depth; it cannot
  undo a credential that a bundler has already exposed.
- Never build a route whose caller picks the recipients, subject, or body.
  Derive the recipient from the authenticated session or a server-side
  record, require authentication and authorization on anything that
  triggers mail, validate the input, bound the request body size, and
  rate-limit per account. An unauthenticated send endpoint is an open
  mail relay on your verified domain.
- Construct the client ONCE at module scope, never per request:
  `new AhaSendClient({ apiKey, accountId })`.
- Send with `client.messages.send({ from, recipients, subject,
  html_content, text_content })`. Body fields are snake_case. `from` is
  `{ email, name? }`; `recipients` is an array of `{ email, name? }`,
  1 to 100 entries, and each recipient gets a separate message.
- The response is multi-status (HTTP 202). `result.data` has one entry per
  recipient, and a recipient can come back `status: "error"` with a null
  `id` while the promise resolves. Check every entry, not just the first.
- Errors are typed. Catch `AhaSendAPIError` and `AhaSendRateLimitError`
  from `@ahasend/sdk`, and match on `err.status` or `err.code`, never on
  message text.
- Verify webhooks with `WebhookVerifier` from `@ahasend/sdk/webhooks`.
  Signature checks need the RAW request body. `parse()` and `verify()`
  are async: `await verifier.parse(headers, rawBody)`. Use a framework
  adapter when available and cap the raw body read with the adapter's
  `maxBodyBytes`. Atomically deduplicate `webhook-id` with the durable
  work or outbox record before returning success.
- Read `AHASEND_API_KEY`, `AHASEND_ACCOUNT_ID`, and the fail-closed
  `AHASEND_DELIVERY_MODE` (`sandbox` or `live`) from the environment.
  Never hardcode, print, or commit credentials.
- Derive idempotency keys from a stable server-side business-event ID.
  Prefix the key with delivery mode so sandbox and live requests cannot
  collide. Reuse a key only for the exact same request payload.
- Mock the API boundary by default. Run a real sandbox request only with
  explicit approval and a dedicated Sandbox-mode credential.

---
description: Add a transactional email send via the AhaSend SDK
---

# Add AhaSend email

1. If `lib/ahasend.ts` does not exist, create it: import `AhaSendClient`
   from `@ahasend/sdk` and export one client built from
   `AHASEND_API_KEY` and `AHASEND_ACCOUNT_ID`. Validate those variables
   and `AHASEND_DELIVERY_MODE` (`sandbox` or `live`) at startup. Module
   scope only.
2. In the target handler, import that client and call
   `client.messages.send({ from, recipients, subject, html_content,
   text_content, sandbox }, { idempotencyKey })`. Build a mode-prefixed
   idempotency key from a stable server-side business-event ID. Body
   fields are snake_case.
3. Filter `result.data` for entries with `status === "error"` and log
   how many recipients were rejected. Never read only `result.data[0]`.
4. Wrap the call in a try/catch for `AhaSendAPIError` and log
   only `err.status`, `err.code`, and `err.requestId`, never the whole
   error object or its message.
5. Await the send before completing the handler. If it should happen
   after the response, enqueue a durable job and send from its worker;
   do not start an unobserved promise.
6. Mock the AhaSend boundary in automated tests. Only with explicit user
   approval, run one integration send using a dedicated Sandbox-mode
   credential and confirm no recipient result has `status === "error"`.

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"),
});

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

export const deliveryMode = mode;

import { AhaSendAPIError } from "@ahasend/sdk";
import { ahasend, deliveryMode } from "../lib/ahasend.js";

type SignupEvent = {
  id: string;
  email: string;
  name: string;
};

export async function sendWelcome(signupEvent: SignupEvent) {
  try {
    const result = await ahasend.messages.send(
      {
        from: { email: "hello@yourdomain.com", name: "Your App" },
        recipients: [{ email: signupEvent.email, name: signupEvent.name }],
        subject: "Welcome aboard",
        text_content: "Thanks for signing up.",
        html_content: "<p>Thanks for signing up.</p>",
        sandbox: deliveryMode === "sandbox",
      },
      {
        idempotencyKey: `${deliveryMode}-welcome-${signupEvent.id}`,
      },
    );

    const rejected = result.data.filter((entry) => entry.status === "error").length;
    const accepted = result.data.length - rejected;
    if (rejected > 0) {
      console.warn("AhaSend rejected recipients", { accepted, rejected });
      throw new Error("The welcome email was not accepted");
    }

    return { accepted, rejected };
  } catch (error) {
    if (error instanceof AhaSendAPIError) {
      console.error("AhaSend request failed", {
        status: error.status,
        code: error.code,
        requestId: error.requestId,
      });
      throw new Error("The welcome email request failed");
    }
    throw error;
  }
}