@beignet/provider-mail-smtp

[!CAUTION] Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

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

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

Required environment variables:

| Variable | Description | | --- | --- | | MAIL_HOST | SMTP server hostname | | MAIL_PORT | SMTP server port. Port 465 uses SSL. | | MAIL_USER | SMTP username | | MAIL_PASS | SMTP password | | MAIL_FROM | Default sender address |

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 <[email protected]>",
  }),
];

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

Use in application code

await ctx.ports.mailer.send({
  to: "[email protected]",
  subject: "Welcome",
  text: "Thanks for joining.",
});

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: "[email protected]", name: "Support" },
  to: ["[email protected]", "[email protected]"],
  cc: "[email protected]",
  replyTo: "[email protected]",
  subject: "Account updated",
  text: "Your account was updated.",
  html: "<p>Your account was updated.</p>",
});

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: "[email protected]",
  to: "[email protected]",
  subject: "Invoice",
  text: "Attached.",
  attachments: [
    {
      filename: "invoice.pdf",
      path: "/path/to/invoice.pdf",
    },
  ],
});

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