Transactional email in Next.js without duplicate sends

The shortest Next.js email endpoint parses JSON, calls a provider, and returns the response. It also has no answer for a lost response.

1. 01The Route Handler asks the provider to send an order receipt.
2. 02The provider accepts the email.
3. 03The network closes before the Route Handler receives the answer.
4. 04The function returns an error or times out.
5. 05The browser, queue, or application tries again.
6. 06The second request creates a second receipt email.

A blind retry may send the receipt twice. Avoiding all retries is not a solution because temporary failures still need recovery. The useful rule is: retries are allowed, but they must point to the same customer-visible action.

Engineers often call this behavior idempotency. In plain English, it is duplicate-send protection. One order receipt has one stable label. Repeating the request with that label returns the existing result instead of creating another email.

Next.js Route Handlers use the standard Web Request and Response APIs inside an App Router route.ts file. Next.js also states that Route Handlers are public HTTP endpoints. Their location in your repository does not make them private.

The handler should do a small, explicit set of jobs:

Do not put the provider token in a Client Component. Next.js only exposes browser variables that use its public prefix, but a secret also needs server-only code, narrow permissions, separate environments, and safe logging.

The key should answer, "Which customer-visible message is this?" Good inputs come from trusted business records and a message version.

Store a hash of the normalized recipient, template version, and variables beside the key. If the same key returns with the same content, return the original record. If the content changed, return a conflict. Quietly changing the recipient or message under an old key makes the label meaningless.

This example leaves database and authentication libraries open because the important contract is the order of operations. The database function must use a unique constraint, not a fragile read-then-write check.

// app/api/orders/[orderId]/receipt/route.ts
export async function POST(
  request: Request,
  { params }: { params: Promise<{ orderId: string }> }
) {
  const user = await requireUser(request)
  const { orderId } = await params
  const order = await requireViewableOrder(user, orderId)

  // One stable label for one customer-visible message.
  const requestKey = `order-receipt:${order.id}:v1`
  const payload = buildReceiptEmail(order)

  const result = await saveOrReadEmailRequest({
    accountId: order.accountId,
    requestKey,
    recipient: order.customerEmail,
    template: "order-receipt-v1",
    payload,
  })

  if (result.kind === "conflict") {
    return Response.json({ error: "request_key_conflict" }, { status: 409 })
  }

  if (result.kind === "created") {
    await addToOutbox(result.emailRequest.id)
  }

  return Response.json(
    { id: result.emailRequest.id, status: result.emailRequest.status },
    { status: 202 }
  )
}

Put a unique database constraint on the account and request key. If two requests arrive together, the database decides which one created the record. The other reads the existing request. A process-level lock is insufficient when separate functions can run on separate machines.

Return 202 Accepted when the durable request exists and dispatch will continue asynchronously. Return a conflict when the same key arrives with different content. Ordinary authentication, validation, and rate-limit errors keep their ordinary status codes.

Next.js notes that some hosts deploy Route Handlers as lambda functions. Those handlers cannot share memory between requests, may not have a writable file system, and may be terminated by a timeout. An in-memory array or a promise left running after the response is not a delivery system.

A transactional outbox writes the business change and the email request in one database transaction. A separate worker claims pending records, talks to the provider, and stores the result. If it stops, another worker can resume from the same request.

Pass the stable request identity to the provider when its API supports duplicate protection. Provider behavior differs, so check the exact endpoint, time window, and conflict behavior you use. Resend, for example, currently documents duplicate protection for its single and batch email endpoints and keeps keys for 24 hours.

Provider protection is a useful second line of defense, not your only record. A provider window may expire, another provider may use a different contract, and your application still needs an explanation months later. The durable application record is the long-term truth about the intended message.

Moosewave's transactional email API uses the same plain contract: a repeated request with the same content returns the existing result, while a repeated key with different content conflicts. It also keeps the request, provider receipt, and later events connected.

Webhooks can repeat for the same reason API requests repeat: the sender may not receive your acknowledgement. Resend currently documents at-least-once webhook delivery and says event order is not guaranteed. Its guidance recommends using the event delivery ID to detect duplicates.

1. 01Read the raw body when the provider's signature scheme requires it.
2. 02Verify the signature and timestamp before trusting any field.
3. 03Insert the provider event ID under a unique database constraint.
4. 04Return success when that event is already stored.
5. 05Update the email request only through allowed state transitions.
6. 06Create any follow-up as a separately named business request, not an immediate side effect hidden inside the webhook.

A delivered event usually means the recipient's mail server accepted the message. It does not prove inbox placement, a human read, or a purchase. Keep provider acceptance, receiving-server acceptance, controlled placement observations, interactions, and product outcomes as separate facts. Moosewave's deliverability and analytics models preserve those distinctions.

• ✓The Route Handler authenticates, authorizes, validates, and rate-limits the request.
• ✓The provider secret stays in server-only code and the correct environment.
• ✓The request key comes from a trusted business event and message version.
• ✓A database uniqueness rule resolves concurrent duplicates.
• ✓The same key with different recipient or content returns a conflict.
• ✓A durable outbox or queue survives function termination.
• ✓Retries use bounded backoff and the same request identity.
• ✓Unclear provider outcomes remain unknown until reconciled.
• ✓Webhook signatures are checked before events are stored.
• ✓Webhook event IDs are deduplicated before side effects.
• ✓Suppression and complaint state is checked before execution.
• ✓Logs omit message content, reset tokens, and unnecessary personal data.
• ✓A pause control stops unsent work without deleting evidence.
• ✓Tests cover timeouts after provider acceptance and concurrent requests.

Moosewave is self-serve, and an AI agent is optional. A developer can use the API and inspect each request directly. A compatible agent can work through scoped MCP tools against the same permissions and receipts, which is useful for diagnosis and operations without creating a second sending path. Review the integration directory or open the product walkthrough to see the full lifecycle.

The production unit is one durable email request, any number of technical attempts, and one connected evidence history. Once the application remembers that unit, retries become recovery instead of a second permission to send.

• Next.js: Backend for Frontend. Current Route Handler guidance, including public endpoint security and deployment-environment limits.
• Next.js: Environment Variables. How Next.js loads server variables and which public prefix exposes values to the browser bundle.
• Resend: Idempotency Keys. The provider's current stable-key contract, supported endpoints, retention window, and conflict responses.
• Resend: Managing Webhooks. Current webhook retry schedule, at-least-once delivery, event IDs, and out-of-order delivery guidance.

Sources checked 28 August 2026. Product behavior and documentation can change, so the linked primary source takes precedence if it differs from this article.