We're glad you're here.
", 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" }); } }, ); ``` Start the server with `app.listen()` at the very **end** of the file, after the webhook route below is declared. Fastify refuses new plugins and routes once `listen()` has resolved, so anything registered after it throws `AVV_ERR_ROOT_PLG_BOOTED` or `FST_ERR_INSTANCE_ALREADY_LISTENING`. Keep `WELCOME_ROUTE_TOKEN` server-side and require your application authentication before accepting a recipient address. Serve the route only over HTTPS, terminating TLS at Fastify or a trusted reverse proxy. `@fastify/rate-limit` keys on `request.ip` and counts in memory per process, so behind a load balancer set Fastify's `trustProxy` and give it a shared store; otherwise every client shares one bucket and each instance counts separately. `eventId` must be a stable identifier for the same welcome-email action; reuse it only with the same payload. A 202 is **multi-status**: `result.data` carries one entry per recipient, and an individual recipient can come back `status: "error"` with a null `id` (a suppressed address, say) while the call itself succeeds, so check every entry, not just the first. The SDK retries transient failures automatically, but a 5xx or timeout does not prove that no email was sent. The stable `idempotencyKey` lets stored results be replayed for 24 hours, but server errors release the key for re-execution. Reconcile an uncertain result before retrying, and persist `eventId` in your application if the welcome email must never be sent twice. Add `sandbox: true` to the send request to validate it without delivering anything. The idempotency key is bound to a hash of the request body, so flipping `sandbox` on or off while reusing the same `eventId` returns `422` `AhaSendIdempotencyMismatchError` — use a distinct key prefix for sandbox traffic. ## Handle Webhooks The SDK ships a dedicated Fastify adapter that verifies the HMAC signature and hands you a typed event. The verifier needs the **raw request body**, which Fastify normally discards after JSON parsing. Register the [`fastify-raw-body`](https://github.com/Eomm/fastify-raw-body) plugin and enable it only on the webhook route. This continues the same `server.ts`, appended after the send route. `await` the `register` call: it installs an `onRoute` hook that only applies to routes declared after the plugin has finished loading, so an unawaited registration leaves `request.rawBody` undefined and the route answers `400` forever. ```ts server.ts theme={null} 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", }); ``` With `global: false`, the raw-body capture hook only runs on routes that opt in via `config: { rawBody: true }`. Note that `encoding: false` also swaps the JSON body parser app-wide — your other routes still get JSON in `request.body`, they just get it from the plugin's parser. The route `bodyLimit` bounds the raw capture as well as the parse, and `maxBodyBytes` bounds what the verifier will hash, so an oversized body is rejected before either reads it all. The adapter replies `200` automatically when your handler completes, `400` if verification fails or the raw body is missing, and `413` if the body exceeds `maxBodyBytes`. If your handler throws, the adapter rethrows so Fastify answers `500` and AhaSend retries the delivery. Timestamp validation does not stop a valid delivery from being replayed inside the accepted window. Before adding side effects, atomically store the `webhook-id` header with durable work and return `200` for an ID you have already accepted. Do not log recipients, message content, request bodies, signatures, or secrets. Create the webhook in your [AhaSend dashboard](https://dash.ahasend.com) pointing at `https://your-app.com/webhooks/ahasend`, and copy its secret into `AHASEND_WEBHOOK_SECRET` exactly as shown (including the `aha-whsec-` prefix). ## Going Further * **Templating**: pass `substitutions` per recipient and use `{{ variable }}` in the subject or body. * **Batch sends**: `recipients` accepts up to 100 entries; each gets a separate, individually-substituted message. * **Scheduling**: set `schedule.first_attempt` to a future RFC 3339 timestamp within 7 days of the request. * **Your own idempotency keys**: pass `{ idempotencyKey: "order-123" }` as the second argument to `send()` so stored results for the same request can be replayed within the server's retention window. * **Attachments**: pass `attachments: [{ data, content_type, file_name, base64: true }]`. Set `base64: true` for binary files such as PDFs. See the [API reference](/docs/api-reference) for every endpoint the SDK exposes. On a different Node framework? The same SDK powers the [Express](/docs/guides/express) and [Hono](/docs/guides/hono) guides. ## Troubleshooting