Idempotency

To send the same message again without delivering it twice, pass an idempotencyKey in the second argument of email.send. The provider uses the key to recognize the repeat.

Example (Sending With a Key on Resend)

import { Effect } from "effect";
import { Email } from "@effect-kit/emails";
import * as Resend from "@effect-kit/emails/resend";

const program = Effect.gen(function* () {
  const email = yield* Email;
  return yield* email.send(
    {
      from: "hello@example.com",
      to: "ada@example.com",
      subject: "Your receipt",
      text: "Thanks for your order.",
    },
    { idempotencyKey: "receipt/order-1042" },
  );
}).pipe(Effect.provide(Resend.layerConfig()));

Use one key per message, derived from something stable such as an order id. A key made fresh on each attempt protects nothing.

Which providers support itCopy Anchor Link

Four providers take a key. Every other provider fails the send before any request.

The modes differ in what a repeated key does:

• replay: the provider treats the repeat as the same send and does not deliver a second message.
• reject: the provider refuses the repeat, and the send fails with IdempotencyConflictError.

retention in email.capabilities.idempotency is the window the package declares. It is a hint for your code. The package does not enforce it.

A key that breaks the rules fails with InvalidMessageError and acceptance: "notSubmitted", with idempotencyKey in paths. Brevo also rejects a custom header named idempotencyKey, because the package sends the key under that name.

Handling a conflictCopy Anchor Link

IdempotencyConflictError means the provider saw the key before and did not accept the new request as a fresh send. The package maps these provider signals to it:

Example (Treating a Repeated Key as Already Sent)

import { Effect } from "effect";
import { Email } from "@effect-kit/emails";

const sendReceipt = Effect.gen(function* () {
  const email = yield* Email;
  return yield* email.send(
    {
      from: "hello@example.com",
      to: "ada@example.com",
      subject: "Your receipt",
      text: "Thanks for your order.",
    },
    { idempotencyKey: "receipt/order-1042" },
  );
}).pipe(Effect.catchReason("EmailError", "IdempotencyConflictError", () => Effect.void));

On Resend a conflict arrives with acceptance: "unknown", so a conflict is not proof that the first send succeeded.

Providers without supportCopy Anchor Link

An idempotencyKey on a provider with mode unsupported fails before any request, with UnsupportedFeatureError and feature: "idempotency".

Keys in batchesCopy Anchor Link

Email.sendMany keeps the key you set on each request and never generates one. A request without a key is sent without one.

Example (Keying Each Message in a Batch)

import { Email } from "@effect-kit/emails";

const orders = ["1042", "1043"];

const program = Email.sendMany(
  orders.map((id) => ({
    message: {
      from: "hello@example.com",
      to: "ada@example.com",
      subject: `Receipt ${id}`,
      text: "Thanks for your order.",
    },
    options: { idempotencyKey: `receipt/order-${id}` },
  })),
);