@contract-kit/provider-mail-smtp

SMTP-backed mail provider for Contract Kit, 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.

Install

bun add @contract-kit/provider-mail-smtp nodemailer

Setup

import { mailSmtpProvider } from "@contract-kit/provider-mail-smtp";
import { createServer } from "@contract-kit/server";

const server = await createServer({
  ports: basePorts,
  providers: [mailSmtpProvider],
  createContext: ({ 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 |

Use in application code

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

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:

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.

Errors

Delivery failures throw MailDeliveryError from @contract-kit/mail. Startup configuration and connection problems throw during provider setup.

License

MIT