How to Build a Transactional Email Workflow with Claude

## Sending email (AhaSend)

- Use the official SDK: `@ahasend/sdk` on npm.
  Do not invent a package name and do not hand-roll fetch calls.
- Server-side only. Supported runtimes include Node.js, Deno, Bun,
  Cloudflare workerd (no `nodejs_compat` needed), and
  Vercel Edge. Keep the client module out of browser bundles. The constructor
  refuses browsers and browser service workers by default, but that is only a
  backstop and does not make exposing a bearer key safe.
- 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?, substitutions? }`, 1 to 100 entries, each getting its
  own 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. Inspect every entry.
- Per-recipient templating: pass `substitutions` and use `{{ variable }}`
  in the subject or body.
- Never let an unauthenticated caller choose the recipient. A send is
  triggered by a server-side event, and the address comes from our own
  records, never straight off a request body. Authenticate, validate, and
  rate-limit anything that can cause a send, and bound the request body
  size. An endpoint that mails whatever address it is handed is a mail
  relay on our verified domain.
- Never detach a send promise from a request handler. Commit a durable,
  uniquely keyed job in the same transaction as the record that triggers
  it and send from a worker: work started after the response goes out can
  be killed with the process.
- For anything the app can retry, pass a stable caller-owned key in the
  second argument: `client.messages.send(body, { idempotencyKey })`,
  derived from the job or business event. Reuse a key only with a
  byte-identical payload; a changed payload comes back as a mismatch.
  Stored results expire after 24 hours, so reconcile instead of assuming
  a later retry is deduplicated. `sandbox` is part of the fingerprinted
  body, so never reuse one key across sandbox and live.
- Errors are typed. Catch `AhaSendAPIError` / `AhaSendRateLimitError` from
  `@ahasend/sdk` and match on `err.status` or `err.code`, never on text.
- Verify webhooks with `WebhookVerifier` from `@ahasend/sdk/webhooks`.
  Signature checks need the RAW request body, not re-serialized JSON.
  `parse()` and `verify()` are async:
  `await verifier.parse(headers, rawBody)`. Prefer the Express, Fastify
  and Next.js adapters from the same module: they read the raw body under
  a size cap and await verification for you.
- Webhooks can be delivered more than once. After verification, atomically
  commit the `webhook-id` and durable work in the same transaction before
  acknowledging it. Acknowledge an already-committed ID without processing
  it again.
- Read `AHASEND_API_KEY`, `AHASEND_ACCOUNT_ID`, and
  `AHASEND_WEBHOOK_SECRET` from the environment. Pass the webhook secret
  exactly as the dashboard returns it, including the `aha-whsec-` prefix.
  Never hardcode or commit these values, and never put them in a
  client-exposed variable (`NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`,
  `NUXT_PUBLIC_`) — those ship to the browser.
- Log only aggregate counts, appropriate opaque IDs, HTTP status, SDK error
  code, and request ID. Never log addresses, message content, secrets,
  idempotency keys, request/response/event/error objects, `err.message`,
  or `err.body`.
- For testing, set `sandbox: true` so nothing is delivered, and use
  `sandbox_result` to simulate an outcome: "deliver", "bounce", "defer",
  "fail", or "suppress".
- Other languages: Go uses github.com/AhaSend/ahasend-go. There is no
  Python SDK yet, so Python calls the REST API directly.

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

export const ahasend = new AhaSendClient({
  apiKey: process.env.AHASEND_API_KEY!,
  accountId: process.env.AHASEND_ACCOUNT_ID!,
});

// Called from the worker that drains welcome-email jobs, with the user
// loaded from your own records — never from an inbound request body.
export async function sendWelcome(job: {
  id: string;
  user: { email: string; firstName: string };
}) {
  const result = await ahasend.messages.send(
    {
      from: { email: "hello@yourdomain.com", name: "Your App" },
      recipients: [
        { email: job.user.email, substitutions: { first_name: job.user.firstName } },
      ],
      subject: "Welcome {{ first_name }}",
      text_content: "Thanks for signing up, {{ first_name }}.",
      html_content: "<p>Thanks for signing up, {{ first_name }}.</p>",
      sandbox: process.env.NODE_ENV !== "production",
    },
    { idempotencyKey: `welcome-${job.id}` },
  );

  const rejected = result.data.filter((r) => r.status === "error");
  if (rejected.length > 0) {
    console.warn(`${rejected.length} recipient(s) rejected`);
  }
  return result;
}

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

const client = new AhaSendClient({
  apiKey: process.env.AHASEND_API_KEY,
  accountId: process.env.AHASEND_ACCOUNT_ID,
});

const result = await client.messages.send({
  from: { email: "hello@yourdomain.com", name: "Your App" },
  recipients: [{ email: "test@example.com", name: "Ada" }],
  subject: "Welcome aboard",
  text_content: "Testing the workflow.",
  sandbox: true,
  sandbox_result: "bounce", // rehearse the failure path
});

console.log(result.data.map((r) => r.status));