@beignet/provider-mail-smtp

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

SMTP-backed mail provider for Beignet, implemented with Nodemailer.

The provider installs the app-facing ctx.ports.mailer port and exposes ctx.ports.smtp.transporter only as an escape hatch for Nodemailer-specific features.

createSmtpMailProvider(...) returns the stable SmtpMailProvider type. MailConfig describes its validated config; the Zod schema remains internal.

Install

bun add @beignet/provider-mail-smtp @beignet/core nodemailer@^9.0.1
Copy

Nodemailer 9.x starting at 9.0.1 is required. Earlier releases are affected by a message-level raw access-control bypass.

Setup

import { createSmtpMailProvider } from "@beignet/provider-mail-smtp";
import { createServer } from "@beignet/core/server";

const server = await createServer({
  ports: basePorts,
  providers: [createSmtpMailProvider()],
  context: ({ ports }) => ({ ports }),
  routes,
});
Copy

Environment variables:

The host, port, credentials, and sender are required. MAIL_REQUIRE_TLS is optional and defaults to true.

beignet doctor --strict checks that installed SMTP mail providers are registered in server/providers.ts and that all required MAIL_* env vars are present in app env examples or config.

Use createSmtpMailProvider(...) when you want to pass config directly instead of reading MAIL_* env vars. Options override env-derived values:

import { createSmtpMailProvider } from "@beignet/provider-mail-smtp";

export const providers = [
  createSmtpMailProvider({
    host: "smtp.example.com",
    port: 465,
    user: secrets.smtpUser,
    pass: secrets.smtpPass,
    from: "My App <no-reply@example.com>",
    requireTls: true,
  }),
];
Copy

Calling createSmtpMailProvider() with no options uses the env-backed configuration.

Encrypted transport is required by default. Port 465 uses implicit TLS; other ports must complete STARTTLS negotiation, and provider setup fails when the SMTP server cannot do so. Set requireTls: false or MAIL_REQUIRE_TLS=false only for a trusted local capture service that does not support TLS.

Use in application code

await ctx.ports.mailer.send({
  to: "user@example.com",
  subject: "Welcome",
  text: "Thanks for joining.",
});
Copy

The provider contributes:

• ctx.ports.mailer, the standard Beignet MailerPort
• ctx.ports.smtp, an escape hatch with the Nodemailer transporter and default sender

The same MailerPort works with Resend, memory fakes, and other adapters:

await ctx.ports.mailer.send({
  from: { email: "support@example.com", name: "Support" },
  to: ["user@example.com", "admin@example.com"],
  cc: "audit@example.com",
  replyTo: "support@example.com",
  subject: "Account updated",
  text: "Your account was updated.",
  html: "<p>Your account was updated.</p>",
});
Copy

Escape hatch

Use the Nodemailer transporter only when you need an SMTP-specific feature not covered by MailerPort. The transporter accepts Nodemailer's full message shape and therefore bypasses Beignet's typed mail validation. Construct raw messages, attachment paths, URLs, and recipients only from trusted application data:

await ctx.ports.smtp.transporter.sendMail({
  from: "sender@example.com",
  to: "user@example.com",
  subject: "Invoice",
  text: "Attached.",
  attachments: [
    {
      filename: "invoice.pdf",
      path: "/path/to/invoice.pdf",
    },
  ],
});
Copy

Devtools

When ctx.ports.devtools is installed, this provider records mail.send, mail.sent, and mail.failed events under the mail watcher. Completed and failed events include durationMs in their details. Events retain the provider, recipient count, delivery ID when available, and duration, but never include addresses, subjects, message bodies, or raw SMTP errors.

Failure and retry semantics

The provider fails fast and does not retry. Each send(...) call makes one Nodemailer sendMail(...) call, even for transient network errors or provider-side failures. Mail delivery is not idempotent: a timed-out send may still have been delivered, so a blind provider retry risks duplicate emails.

Delivery failures throw MailDeliveryError from @beignet/core/mail with the provider name, the recipient count, and the original SMTP error preserved as cause for app-owned handling. The error is not copied into provider instrumentation. Redact or restrict access when an application logs the cause.

The provider calls transporter.verify() during setup, so an unreachable SMTP server or rejected credentials fail server startup immediately instead of failing the first send. Startup configuration problems also throw during provider setup.

When mail needs retries, dispatch it from a job or an outbox-backed listener and own idempotency there. The job or outbox row should choose attempts and delay, and the application should record one delivery per business event before sending.

Local and tests

Use a memory or fake MailerPort in use-case tests. For local SMTP testing, point the provider at a local capture service such as Mailpit or MailHog and keep those credentials out of production env files. If that service does not support STARTTLS, explicitly set MAIL_REQUIRE_TLS=false in the local environment; never carry the opt-out into preview, staging, or production.

Deployment notes

SMTP delivery semantics depend on the configured server. Treat mail delivery as an external side effect: trigger important mail from committed workflow state, usually through notifications, jobs, or outbox-backed listeners.

License

MIT