Mail

Beignet treats mail as a port. Application code calls ctx.ports.mailer.send(...); providers decide whether delivery happens through Resend, SMTP, a memory adapter, or an app-owned service.

This keeps email out of use-case internals and makes workflows easy to test.

Use notifications when the application intent is broader than "send one email," such as appointment reminders, message alerts, or delivery that may later fan out to SMS, push, or in-app channels.

App-facing port

bun add @beignet/core
import type { MailerPort } from "@beignet/core/mail";

export type AppPorts = {
  mailer: MailerPort;
};

Use cases and jobs depend on MailerPort, not a vendor SDK:

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

send(...) requires at least one to recipient and accepts text, html, or both. Recipients can be strings or named address objects:

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

Empty optional recipient lists are ignored, so callers can safely pass filtered cc, bcc, or replyTo arrays.

Beignet's shared formatter rejects carriage returns and line feeds in address strings, email fields, and display names before the Resend or SMTP provider builds its recipient headers. Named-address backslashes and quotes are escaped; full email-syntax validation remains the provider's responsibility.

Dev-default provider

Use createMemoryMailerProvider(...) to wire the mailer port before choosing a real mail service. It captures deliveries in memory and records mail.sent devtools events through the mail watcher when instrumentation is installed, including the recipient count, delivery ID, and duration, so local development can see outgoing mail without sending anything. The event excludes addresses, subjects, and message bodies; inspect the memory mailer's captured deliveries only in trusted development and test code when message content is needed.

// server/providers.ts
import { createMemoryMailerProvider } from "@beignet/core/mail";

export const providers = [
  createMemoryMailerProvider({
    defaultFrom: "App <noreply@example.local>",
  }),
] as const;

Swap it for a real provider when the app needs delivery; the mailer port shape stays the same.

Provider setup

Use Resend when you want an HTTP email service:

bun add @beignet/provider-mail-resend resend

The Resend provider supports resend ^2, ^3, ^4, and ^6. Resend v6 uses Beignet's Node.js 22.12-or-newer runtime baseline, which also satisfies the SDK's requirement.

import { createResendMailProvider } from "@beignet/provider-mail-resend";

export const providers = [createResendMailProvider()];

Resend reads RESEND_API_KEY and RESEND_FROM.

Use SMTP when your deployment already has SMTP credentials:

bun add @beignet/provider-mail-smtp nodemailer@^9.0.1
import { createSmtpMailProvider } from "@beignet/provider-mail-smtp";

export const providers = [createSmtpMailProvider()];

createResendMailProvider(options) and createSmtpMailProvider(options) configure either provider in code; options mirror the env fields and override env-derived values.

SMTP reads MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, MAIL_FROM, and optional MAIL_REQUIRE_TLS. Encrypted transport is required by default: port 465 uses implicit TLS, while other ports must negotiate STARTTLS. Set MAIL_REQUIRE_TLS=false only for a trusted local mail-capture service that does not support TLS.

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

Both providers install the same ctx.ports.mailer shape. Resend also exposes ctx.ports.resend.client; SMTP exposes ctx.ports.smtp.transporter. Treat those as escape hatches for provider-specific features such as attachments or custom delivery APIs. The raw SMTP transporter bypasses Beignet's typed mail validation, so construct raw messages, attachment paths, URLs, and recipients only from trusted application data.

Neither provider retries a failed send. Each provider makes one vendor call per send(...); a Resend network error or SMTP sendMail(...) failure becomes a MailDeliveryError. Mail delivery is not idempotent — a timed-out send may still have been delivered — so the providers fail fast instead of risking duplicate emails.

When provider instrumentation is installed, both providers emit mail.send followed by mail.sent or mail.failed. Terminal events include durationMs in their details so mail latency is comparable with storage and other provider operations in devtools. Mail instrumentation records the provider, recipient count, delivery ID when available, and duration. It does not record addresses, subjects, message bodies, or raw provider errors. Delivery errors retain the provider error as cause for app-owned handling, so redact or restrict access when logging that cause.

When mail needs retries, dispatch it from jobs or the outbox 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.

Send mail from jobs

For production workflows, prefer dispatching a job from the use case and sending mail in the job handler. The use case stays focused on the business decision, and mail delivery can be retried independently.

import { retry } from "@beignet/core/jobs";
import { z } from "zod";
import { defineJob } from "@/lib/jobs";

export const SendWelcomeEmailJob = defineJob("mail.welcome", {
  payload: z.object({
    email: z.string().email(),
  }),
  retry: retry.exponential({
    attempts: 3,
  }),
  async handle({ payload, ctx }) {
    await ctx.ports.mailer.send({
      to: payload.email,
      subject: "Welcome",
      text: "Thanks for joining.",
    });
  },
});

Then dispatch the job from the workflow:

await ctx.ports.jobs.dispatch(SendWelcomeEmailJob, {
  email: user.email,
});

Use Jobs for dispatcher and provider worker wiring.

Testing

Use the memory adapter in tests and local examples:

import { createMemoryMailer } from "@beignet/core/mail";

const mailer = createMemoryMailer({
  defaultFrom: "noreply@example.com",
});

await mailer.send({
  to: "user@example.com",
  subject: "Welcome",
  text: "Hello",
});

expect(mailer.deliveries).toHaveLength(1);
expect(mailer.deliveries[0].message.to).toEqual(["user@example.com"]);

Because the memory adapter implements MailerPort, the same use case or job can run against production and test adapters.

Devtools and errors

Mail operations appear in the Mail view of devtools when the devtools provider is installed.

Delivery failures throw MailDeliveryError from @beignet/core/mail. Catch that error when mail delivery is expected to fail independently from the main workflow; otherwise let the job runner record the failure and retry.

Read next