Browse documentation

@dads-framework/email-sender

On this page

Keep outbound mail code independent of the delivery provider. Callers use EmailSender.send(). The application chooses the driver when it creates the sender.

Try it

In a project using Node.js 22 or later, install the example dependencies.

Shell
npm install @dads-framework/email-sender
npm install -D tsx

Save this as example.mts and run npx tsx example.mts.

TypeScript
import {
  CapturedMailbox,
  createEmailSender,
} from "@dads-framework/email-sender";

const mailbox = new CapturedMailbox();
const sender = createEmailSender(
  {
    driver: "capture",
    from: "orders@example.com",
    mailbox,
  },
  console,
);
const receipt = await sender.send({
  to: [{ address: "customer@example.com" }],
  subject: "Order ready",
  text: "Order 1042 is ready for pickup.",
});

console.log(receipt.providerMessageId);
console.log(mailbox.list()[0]?.text);

The script prints mail-1 and Order 1042 is ready for pickup. from the local mailbox. The capture driver keeps the message in memory and requires no provider account.

The package tests exercise the capture driver and its mailbox outside the starter. packages/server/email-sender/src/lib/capture-email-sender.test.ts

Use it

TypeScript
const receipt = await emailSender.send({
  to: [{ address: "invitee@example.com", name: "Dana Reyes" }],
  subject: "Your invitation",
  text: `Accept your invitation: ${activationLink}`,
});

to is a list because one message can have many recipients; cc, bcc, replyTo, from, html, attachments, headers and tags are optional and complete the envelope:

TypeScript
await emailSender.send({
  to: [{ address: "ops@example.com" }],
  cc: [{ address: "audit@example.com" }],
  replyTo: { address: "support@example.com" },
  subject: "Order 1042 is ready",
  text: "Order 1042 is ready for pickup.",
  html: renderedHtml,
  attachments: [
    {
      filename: "packing-slip.pdf",
      contentType: "application/pdf",
      content: pdfBytes,
    },
  ],
  headers: { "X-App-Kind": "order-ready" },
  tags: ["order-ready"],
});

send() returns an EmailSendReceipt — { providerMessageId }, the vendor's id for the accepted message, or null from a driver that never sends. Store it beside the row that asked for the send; it is the only handle a support conversation with the vendor has.

Addresses are rendered for the wire by formatEmailAddress (addr, or Name <addr>, quoted when the name would otherwise break the header). Tags are plain ASCII labels ([A-Za-z0-9_-]{1,256}) for vendor-side delivery reporting.

Call createEmailSender once at the application's composition root using the chosen driver and its credentials. The domain that sends an invitation or verification email owns the message content.

Drivers

MAIL_DRIVER Driver Sends? Receipt Use
log LogEmailSender No null Default. Records email.logged and withholds the address and body.
log-verbose VerboseLogEmailSender No null A developer's own machine. Renders the whole email into the logs.
capture CaptureEmailSender No the mail-N id Development. The application can inspect captured messages in memory.
resend ResendEmailSender Yes Resend's message id Real delivery. Requires the resend SDK and RESEND_API_KEY.
mailgun MailgunEmailSender Yes Mailgun's message id Real delivery. Requires MAILGUN_API_KEY + MAILGUN_DOMAIN; MAILGUN_REGION picks the US or EU host.

Install the optional SDK with npm install resend@^6.17.2 when using the Resend driver. The sender loads the SDK on its first send. If the SDK is missing, that send rejects with the install command.

Attachment BYTES stop at the two non-sending drivers: capture and log-verbose keep each attachment's filename, content type and size, never its content. A base64 blob helps nobody read an email, and a log is the last place a document belongs.

log is the CI and shared-environment default on purpose: bodies carry one-time invitation and verification tokens, so a full-body log is credential material. log-verbose exists only so a developer can read the email — and click the link — without a mail vendor. Never set it anywhere other people's tokens flow.

capture makes the same trade for the development mail page instead of the logs: the mailbox lives in the API process's memory, so captured mail is lost on restart, and it must never run outside development either.

For tests, import FakeEmailSender from @dads-framework/email-sender/testing and assert on sent; it never reaches a driver at all.

Adding a driver

Add a driver at the composition boundary using the shared sender contract.

  1. Add <vendor>-email-sender.ts — a class implementing EmailSender that translates EmailMessage into the vendor's call and throws on rejection. Follow resend-email-sender.ts.
  2. Add the name to EmailSenderDriver and a branch in createEmailSender. Fail loudly there when a required credential is missing, the way resend does — a misconfigured mailer must not boot and silently drop email.
  3. Export the class from src/index.ts.
  4. Surface the vendor SDK as a dependency in the plan/PR (NEVER rule 4), widen the application’s driver configuration, and document the new env vars in the application’s example environment file.

Nothing else moves: no caller, no domain, no message body.

mailgun is the worked example of all four steps, and of the case where the vendor needs no SDK at all: mailgun-email-sender.ts is one multipart fetch, the envelope translation lives in the pure logic/build-mailgun-form.ts, and fetch is injected so the tests read the exact request rather than a vendor's mock.

What it refuses to do

The log driver withholds addresses and message bodies to protect recipients and one-time tokens. Keep the capture and log-verbose drivers in development environments.

Contract

Import the sender and message contracts from @dads-framework/email-sender/core when implementing or accepting a sender. Import the capturing fake and conformance cases from @dads-framework/email-sender/core/testing. Both entry points work without the Resend SDK. Resend and Mailgun run the shared sender tests with in-memory transport responses.

After installing the dependencies from Try it, save this as example.mts and run npx tsx example.mts.

TypeScript
import type { EmailSender } from "@dads-framework/email-sender/core";
import { FakeEmailSender } from "@dads-framework/email-sender/core/testing";

async function notify(sender: EmailSender) {
  return sender.send({
    to: [{ address: "customer@example.com" }],
    subject: "Order ready",
    text: "Order 1042 is ready for pickup.",
  });
}

const sender = new FakeEmailSender();
const receipt = await notify(sender);
console.log(receipt.providerMessageId, sender.sent[0]?.subject);

The script prints fake-1 Order ready. In a test, inspect sent for the message your feature submitted.

The starter implements the EmailSender contract with a local spool that writes each message to a JSON file. apps/kit-workbench/assembly/local-mail.ts