@beignet/provider-mail-resend

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

[!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.

Resend-backed mail provider for Beignet.

The provider installs the app-facing ctx.ports.mailer port and exposes ctx.ports.resend.client only as an escape hatch for Resend-specific features.

createResendMailProvider(...) returns the stable ResendMailProvider type. ResendMailConfig describes its validated config; the Zod schema remains internal.

Install

bun add @beignet/provider-mail-resend @beignet/core resend

The provider requires resend ^6.14.0 for attachment metadata support. Upgrade older SDK installations with bun add resend@^6.14.0. Beignet's Node.js 22.12-or-newer runtime baseline also satisfies Resend v6's requirement.

Setup

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

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

Required environment variables:

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

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

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

export const providers = [
  createResendMailProvider({
    apiKey: secrets.resendApiKey,
    from: "My App <[email protected]>",
  }),
];

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

Use in application code

await ctx.ports.mailer.send({
  to: "[email protected]",
  subject: "Welcome",
  html: "<h1>Hello</h1>",
});

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

await ctx.ports.mailer.send({
  from: { email: "[email protected]", name: "Support" },
  to: ["[email protected]", "[email protected]"],
  replyTo: "[email protected]",
  subject: "Account updated",
  text: "Your account was updated.",
  html: "<p>Your account was updated.</p>",
});

Attachments and inline images

Send files through the standard mailer:

await ctx.ports.mailer.send({
  to: "[email protected]",
  subject: "Workspace summary",
  text: "Your summary is attached.",
  attachments: [
    {
      filename: "summary.json",
      content: new TextEncoder().encode(JSON.stringify({ completed: 12 })),
      contentType: "application/json",
    },
  ],
});

Each MailAttachment requires a nonblank filename without control characters and content: Uint8Array; Node.js Buffers also work. Optional contentType specifies a MIME type without parameters; the provider infers it from the filename when omitted. Set contentId: "logo" on an image attachment and reference it with <img src="cid:logo"> in the HTML body to embed the image. IDs must be unique per message: 1–127 letters, digits, dots, underscores, @, +, or -, beginning with a letter or digit. Omit the cid: prefix from the attachment's ID.

The shared mailer copies metadata and bytes before delivery, permits empty files, and rejects invalid attachment fields with MailDeliveryError before calling the vendor. It accepts bytes rather than paths, URLs, streams, or base64 strings. Provider size and file-type limits apply. Attachment names, bytes, and content IDs are excluded from mail instrumentation.

Use createMemoryMailer() from @beignet/core/mail to assert mailer.deliveries[0].message.attachments in tests. Queued jobs and notifications should carry storage keys or JSON-safe source data; construct attachment bytes in the handler or channel renderer.

Escape hatch

Use the Resend client only when you need a Resend-specific feature not covered by MailerPort:

await ctx.ports.resend.client.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Invoice",
  html: "<p>Your invoice is ready.</p>",
  tags: [{ name: "category", value: "invoice" }],
});

The provider contributes:

• ctx.ports.mailer, the standard Beignet MailerPort
• ctx.ports.resend, an escape hatch with the Resend client

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 Resend errors.

Failure and retry semantics

The provider fails fast and does not retry. Each send(...) call makes one Resend SDK 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 Resend 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. Startup configuration problems 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. Keep Resend sandbox or test-mode credentials in environment-specific config and avoid sending real mail from automated tests.

Deployment notes

Set RESEND_FROM to a verified domain sender. 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