SMTP (Nodemailer)

The @effect-kit/emails/nodemailer subpath sends messages over SMTP with Nodemailer and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect nodemailer@10.2.1

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

SetupCopy Anchor Link

Nodemailer.layerConfig() reads these variables:

The default Config requires SMTP_USER and SMTP_PASSWORD. For a server without authentication, pass your own Config or use layer with a transport that has no auth.

Example (Sending a Message With Nodemailer)

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

const EmailLive = Nodemailer.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 Nodemailer account is allowed to send from.

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Nodemailer reports this in email.capabilities:

These fail with UnsupportedFeatureError and acceptance: "notSubmitted" before any request:

• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• The owned transport disables file and URL access, turns Nodemailer logging off and sets maxRequeues: 0, so Nodemailer never requeues a message. Closing the Layer's scope closes the transport and waits for in-flight sends.
• SMTP accepts or rejects each recipient. When some recipients are rejected, the receipt has status: "partiallyAccepted" with one outcome per recipient, and rejected ones carry rejectionCode SMTP_<code>. When every recipient is rejected, the send fails with RecipientRejectedError.
• The receipt's reference has kind smtpMessageId, taken from the server's message id.

Using your own clientCopy Anchor Link

layerClient takes any object with sendMail(message), which a Nodemailer transporter has. options is optional. If the transporter exposes options and pool is true, maxRequeues must be 0, otherwise Layer construction fails with field: "retries".

Example (Borrowing a Nodemailer Client)

import { createTransport } from "nodemailer";
import * as Nodemailer from "@effect-kit/emails/nodemailer";

const transporter = createTransport({
  host: "smtp.example.com",
  port: 587,
  maxRequeues: 0,
});

const EmailLive = Nodemailer.layerClient(transporter);

You own a borrowed client. The Layer never closes it, and the client keeps its own retry, timeout and logging policy.

ErrorsCopy Anchor Link

Layer construction fails with NodemailerConfigurationError, whose field names the bad option. layerClient fails with it for the client options.

The Nodemailer error code is kept as providerCode and the SMTP response code as statusCode. Failures before submission (connection, DNS, TLS, greeting, authentication) are acceptance: "notSubmitted". An SMTP response code makes it rejected. Anything else is unknown.