@beignet/provider-mail-smtp

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

Required environment variables:

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>",
  }),
];
Copy

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

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.

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. Message bodies and credentials are never included.

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.

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