Lettermint

The @effect-kit/emails/lettermint subpath sends messages through Lettermint and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect lettermint@3.2.0

The SDK is a pinned optional peer. It is needed only when you import this subpath.

SetupCopy Anchor Link

Lettermint.layerConfig() reads these variables:

Example (Sending a Message With Lettermint)

import { ConfigProvider, Effect, Layer } from "effect";
import { Email } from "@effect-kit/emails";
import * as Lettermint from "@effect-kit/emails/lettermint";

const EmailLive = Lettermint.layerConfig().pipe(
  Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnv())),
);

const program = Effect.gen(function* () {
  const email = yield* Email;
  return yield* email.send({
    from: "hello@example.com",
    to: "ada@example.com",
    subject: "Welcome",
    text: "Your account is ready.",
  });
});

Effect.runPromise(program.pipe(Effect.provide(EmailLive)));

Use a from address your Lettermint account is allowed to send from.

OptionsCopy Anchor Link

Lettermint.layer takes these options. layerConfig builds the same object from a Config.

CapabilitiesCopy Anchor Link

Lettermint reports this in email.capabilities:

Every message feature is supported, so no message fails the capability check.

IdempotencyCopy Anchor Link

Mode replay, with a retention of 24 hours. The package passes the key to Lettermint as the SDK's idempotencyKey option.

The key must be 1 to 255 printable ASCII characters and not blank, otherwise the send fails with InvalidMessageError (path idempotencyKey) and acceptance: "notSubmitted". A conflict from Lettermint fails with IdempotencyConflictError.

Example (Sending With an Idempotency Key)

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

const program = Effect.gen(function* () {
  const email = yield* Email;
  return yield* email.send(
    {
      from: "hello@example.com",
      to: "ada@example.com",
      subject: "Welcome",
      text: "Your account is ready.",
    },
    { idempotencyKey: "welcome-ada-2026-10-29" },
  );
});

Provider notesCopy Anchor Link

• With sandbox: true the provider name becomes lettermint/sandbox, and a response that does not report the sandbox flag fails with UnexpectedResponseError. Without it, a response that reports the flag fails the same way.
• Inline images need a fully qualified content id. A contentId without @ fails with InvalidMessageError (path attachments) before sending, because Lettermint would otherwise append @lm and change the id you chose.
• A send is accepted when Lettermint answers with status pending.

Using your own clientCopy Anchor Link

layerClient takes any object with emails.send(message, { signal, timeout, idempotencyKey }), which a Lettermint client has. options is optional and accepts timeout and sandbox.

Example (Borrowing a Lettermint Client)

import { Lettermint as LettermintSdk } from "lettermint";
import * as Lettermint from "@effect-kit/emails/lettermint";

const client = new LettermintSdk({ sendingToken: "fake-token" });

const EmailLive = Lettermint.layerClient(client);

You own a borrowed client. The Layer never closes it, and the client keeps its own retry, timeout and logging policy. For a sandbox client, pass { sandbox: true } so the provider name and the response check match.

ErrorsCopy Anchor Link

ProviderConfigurationError carries provider: "lettermint" and a field naming the bad option. Layer construction fails with it, and layerClient fails with it for the client options.

Other API errors use their HTTP status with the shared mapping.