idempotency vibeCoded

apps/docs/api-reference/emails/batch-email.mdx

@@ -3,3 +3,13 @@ openapi: post /v1/emails/batch
 ---
 
 Send up to 100 emails in a single request.
+
+## Idempotency
+
+Bulk sends also accept the `Idempotency-Key` header. The key applies to the entire batch payload:
+
+- Same key + identical batch body (all items) → returns the original list of `emailId`s with `200 OK`.
+- Same key + different payload → returns `409 Conflict` with `code: NOT_UNIQUE` so you can detect accidental reuse.
+- Same key while another batch is still being processed → returns `409 Conflict`; retry after the first request finishes.
+
+Keys live for 24 hours.

apps/docs/api-reference/emails/send-email.mdx

@@ -1,3 +1,15 @@
 ---
 openapi: post /v1/emails
 ---
+
+Send a transactional email via the public API.
+
+## Idempotency
+
+Pass the optional `Idempotency-Key` header to make the request safe to retry. The key can be up to 256 characters. The server stores the canonical request body and behaves as follows:
+
+- Same key + same request body → returns the original `emailId` with `200 OK` without re‑sending.
+- Same key + different request body → returns `409 Conflict` with `code: NOT_UNIQUE` so you can detect the mismatch.
+- Same key while another request is still being processed → returns `409 Conflict`; retry after a short delay or once the first request completes.
+
+Entries expire after 24 hours. Use a unique key per logical send (for example, an order or signup ID).

apps/docs/api-reference/introduction.mdx

@@ -22,3 +22,7 @@ Authorization: Bearer us_12345
 ```
 
 You can create a new token/API key under your useSend [Developer Settings](https://app.usesend.com/dev-settings/api-keys).
+
+## Idempotency
+
+Use the optional `Idempotency-Key` header on `POST /v1/emails` and `POST /v1/emails/batch` to make requests safe to retry. Reusing a key with the same request body returns the original response; reusing it with different input returns `409 Conflict` so you can detect mistakes. Keys expire after 24 hours.

apps/web/src/server/public-api/api/emails/batch-email.ts

@@ -1,9 +1,12 @@
 import { createRoute, z } from "@hono/zod-openapi";
 import { PublicAPIApp } from "~/server/public-api/hono";
-import { getTeamFromToken } from "~/server/public-api/auth";
 import { sendBulkEmails } from "~/server/service/email-service";
 import { EmailContent } from "~/types";
 import { emailSchema } from "../../schemas/email-schema"; // Corrected import path
+import { IdempotencyService } from "~/server/service/idempotency-service";
+import { canonicalizePayload } from "~/server/utils/idempotency";
+import { UnsendApiError } from "~/server/public-api/api-error";
+import { logger } from "~/server/logger/log";
 
 // Define the schema for a single email within the bulk request
 // This is similar to the schema in send-email.ts but without the top-level 'required'
@@ -13,6 +16,12 @@ const route = createRoute({
   method: "post",
   path: "/v1/emails/batch",
   request: {
+    headers: z
+      .object({
+        "Idempotency-Key": z.string().min(1).max(256).optional(),
+      })
+      .partial()
+      .openapi("Idempotency headers"),
     body: {
       required: true,
       content: {
@@ -47,29 +56,104 @@ function sendBatch(app: PublicAPIApp) {
     const team = c.var.team;
     const emailPayloads = c.req.valid("json");
 
-    // Add teamId and apiKeyId to each email payload
-    const emailsToSend: Array<
-      EmailContent & { teamId: number; apiKeyId?: number }
-    > = emailPayloads.map((payload) => ({
+    const normalizedPayloads = emailPayloads.map((payload) => ({
       ...payload,
       text: payload.text ?? undefined,
       html:
         payload.html && payload.html !== "true" && payload.html !== "false"
           ? payload.html
           : undefined,
+    }));
+
+    const idemKey = c.req.header("Idempotency-Key") ?? undefined;
+    if (idemKey !== undefined && (idemKey.length < 1 || idemKey.length > 256)) {
+      throw new UnsendApiError({
+        code: "BAD_REQUEST",
+        message: "Invalid Idempotency-Key length",
+      });
+    }
+
+    let payloadHash: string | undefined;
+    let lockAcquired = false;
+
+    if (idemKey) {
+      ({ bodyHash: payloadHash } = canonicalizePayload(normalizedPayloads));
+
+      const existing = await IdempotencyService.getResult(team.id, idemKey);
+      if (existing) {
+        if (existing.bodyHash === payloadHash) {
+          logger.info(
+            { teamId: team.id },
+            "Idempotency hit for bulk email send"
+          );
+          const responseData = existing.emailIds.map((id) => ({ emailId: id }));
+          return c.json({ data: responseData });
+        }
+
+        throw new UnsendApiError({
+          code: "NOT_UNIQUE",
+          message: "Idempotency-Key already used with a different payload",
+        });
+      }
+
+      lockAcquired = await IdempotencyService.acquireLock(team.id, idemKey);
+      if (!lockAcquired) {
+        const again = await IdempotencyService.getResult(team.id, idemKey);
+        if (again) {
+          if (again.bodyHash === payloadHash) {
+            logger.info(
+              { teamId: team.id },
+              "Idempotency hit after contention for bulk email send"
+            );
+            const responseData = again.emailIds.map((id) => ({ emailId: id }));
+            return c.json({ data: responseData });
+          }
+
+          throw new UnsendApiError({
+            code: "NOT_UNIQUE",
+            message: "Idempotency-Key already used with a different payload",
+          });
+        }
+
+        throw new UnsendApiError({
+          code: "NOT_UNIQUE",
+          message:
+            "Request with same Idempotency-Key is in progress. Retry later.",
+        });
+      }
+    }
+
+    // Add teamId and apiKeyId to each email payload
+    const emailsToSend: Array<
+      EmailContent & { teamId: number; apiKeyId?: number }
+    > = normalizedPayloads.map((payload) => ({
+      ...payload,
       teamId: team.id,
       apiKeyId: team.apiKeyId,
     }));
 
-    // Call the service function to send emails in bulk
-    const createdEmails = await sendBulkEmails(emailsToSend);
+    try {
+      // Call the service function to send emails in bulk
+      const createdEmails = await sendBulkEmails(emailsToSend);
 
-    // Map the result to the response format
-    const responseData = createdEmails.map((email) => ({
-      emailId: email.id,
-    }));
+      // Map the result to the response format
+      const responseData = createdEmails.map((email) => ({
+        emailId: email.id,
+      }));
+
+      if (idemKey && payloadHash) {
+        await IdempotencyService.setResult(team.id, idemKey, {
+          bodyHash: payloadHash,
+          emailIds: createdEmails.map((email) => email.id),
+        });
+      }
 
-    return c.json({ data: responseData });
+      return c.json({ data: responseData });
+    } finally {
+      if (idemKey && lockAcquired) {
+        await IdempotencyService.releaseLock(team.id, idemKey);
+      }
+    }
   });
 }
 

apps/web/src/server/public-api/api/emails/send-email.ts

@@ -2,11 +2,21 @@ import { createRoute, z } from "@hono/zod-openapi";
 import { PublicAPIApp } from "~/server/public-api/hono";
 import { sendEmail } from "~/server/service/email-service";
 import { emailSchema } from "../../schemas/email-schema";
+import { IdempotencyService } from "~/server/service/idempotency-service";
+import { canonicalizePayload } from "~/server/utils/idempotency";
+import { UnsendApiError } from "~/server/public-api/api-error";
+import { logger } from "~/server/logger/log";
 
 const route = createRoute({
   method: "post",
   path: "/v1/emails",
   request: {
+    headers: z
+      .object({
+        "Idempotency-Key": z.string().min(1).max(256).optional(),
+      })
+      .partial()
+      .openapi("Idempotency headers"),
     body: {
       required: true,
       content: {
@@ -31,24 +41,93 @@ const route = createRoute({
 function send(app: PublicAPIApp) {
   app.openapi(route, async (c) => {
     const team = c.var.team;
+    const requestBody = c.req.valid("json");
 
-    let html = undefined;
+    let html: string | undefined;
+    const rawHtml = requestBody?.html?.toString();
+    if (rawHtml && rawHtml !== "true" && rawHtml !== "false") {
+      html = rawHtml;
+    }
 
-    const _html = c.req.valid("json")?.html?.toString();
+    const clientPayload = {
+      ...requestBody,
+      text: requestBody.text ?? undefined,
+      html,
+    };
 
-    if (_html && _html !== "true" && _html !== "false") {
-      html = _html;
+    const idemKey = c.req.header("Idempotency-Key") ?? undefined;
+    if (idemKey !== undefined && (idemKey.length < 1 || idemKey.length > 256)) {
+      throw new UnsendApiError({
+        code: "BAD_REQUEST",
+        message: "Invalid Idempotency-Key length",
+      });
     }
 
-    const email = await sendEmail({
-      ...c.req.valid("json"),
-      teamId: team.id,
-      apiKeyId: team.apiKeyId,
-      text: c.req.valid("json").text ?? undefined,
-      html: html,
-    });
+    let payloadHash: string | undefined;
+    let lockAcquired = false;
+
+    if (idemKey) {
+      ({ bodyHash: payloadHash } = canonicalizePayload(clientPayload));
+
+      const existing = await IdempotencyService.getResult(team.id, idemKey);
+      if (existing) {
+        if (existing.bodyHash === payloadHash) {
+          logger.info({ teamId: team.id }, "Idempotency hit for email send");
+          return c.json({ emailId: existing.emailIds[0] });
+        }
+
+        throw new UnsendApiError({
+          code: "NOT_UNIQUE",
+          message: "Idempotency-Key already used with a different payload",
+        });
+      }
+
+      lockAcquired = await IdempotencyService.acquireLock(team.id, idemKey);
+      if (!lockAcquired) {
+        const again = await IdempotencyService.getResult(team.id, idemKey);
+        if (again) {
+          if (again.bodyHash === payloadHash) {
+            logger.info(
+              { teamId: team.id },
+              "Idempotency hit after contention for email send"
+            );
+            return c.json({ emailId: again.emailIds[0] });
+          }
+
+          throw new UnsendApiError({
+            code: "NOT_UNIQUE",
+            message: "Idempotency-Key already used with a different payload",
+          });
+        }
 
-    return c.json({ emailId: email?.id });
+        throw new UnsendApiError({
+          code: "NOT_UNIQUE",
+          message:
+            "Request with same Idempotency-Key is in progress. Retry later.",
+        });
+      }
+    }
+
+    try {
+      const email = await sendEmail({
+        ...clientPayload,
+        teamId: team.id,
+        apiKeyId: team.apiKeyId,
+      });
+
+      if (idemKey && payloadHash) {
+        await IdempotencyService.setResult(team.id, idemKey, {
+          bodyHash: payloadHash,
+          emailIds: [email.id],
+        });
+      }
+
+      return c.json({ emailId: email?.id });
+    } finally {
+      if (idemKey && lockAcquired) {
+        await IdempotencyService.releaseLock(team.id, idemKey);
+      }
+    }
   });
 }
 

apps/web/src/server/service/idempotency-service.ts

@@ -0,0 +1,78 @@
+import { getRedis } from "~/server/redis";
+
+const IDEMPOTENCY_RESULT_TTL_SECONDS = 24 * 60 * 60; // 24h
+const IDEMPOTENCY_LOCK_TTL_SECONDS = 60; // 60s
+
+export type IdempotencyRecord = {
+  bodyHash: string;
+  emailIds: string[];
+};
+
+function resultKey(teamId: number, key: string) {
+  return `idem:${teamId}:${key}`;
+}
+
+function lockKey(teamId: number, key: string) {
+  return `idemlock:${teamId}:${key}`;
+}
+
+export const IdempotencyService = {
+  async getResult(
+    teamId: number,
+    key: string
+  ): Promise<IdempotencyRecord | null> {
+    const redis = getRedis();
+    const raw = await redis.get(resultKey(teamId, key));
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === "object" &&
+        typeof (parsed as any).bodyHash === "string" &&
+        Array.isArray((parsed as any).emailIds)
+      ) {
+        return parsed as IdempotencyRecord;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  },
+
+  async setResult(
+    teamId: number,
+    key: string,
+    record: IdempotencyRecord
+  ): Promise<void> {
+    const redis = getRedis();
+    await redis.setex(
+      resultKey(teamId, key),
+      IDEMPOTENCY_RESULT_TTL_SECONDS,
+      JSON.stringify(record)
+    );
+  },
+
+  async acquireLock(teamId: number, key: string): Promise<boolean> {
+    const redis = getRedis();
+    const ok = await redis.set(
+      lockKey(teamId, key),
+      "1",
+      "EX",
+      IDEMPOTENCY_LOCK_TTL_SECONDS,
+      "NX"
+    );
+    return ok === "OK";
+  },
+
+  async releaseLock(teamId: number, key: string): Promise<void> {
+    const redis = getRedis();
+    await redis.del(lockKey(teamId, key));
+  },
+};
+
+export const IDEMPOTENCY_CONSTANTS = {
+  RESULT_TTL_SECONDS: IDEMPOTENCY_RESULT_TTL_SECONDS,
+  LOCK_TTL_SECONDS: IDEMPOTENCY_LOCK_TTL_SECONDS,
+};
+