@bunmail/smtp

Direct-to-MX SMTP client for Bun. First-class TLS observability + cert validation reporting + DKIM signing. Zero npm dependencies.

[!WARNING] v0.0.1 is a scaffolding release. The full API surface is declared so you can write code against it today, but sendMail() throws NotImplementedError at runtime. The SMTP state machine + DKIM signing + TLS observability land in v0.1.0. Don't ship code that calls sendMail() until then. Watch the repo for the v0.1.0 release notes.

Why

Most Bun email projects today reach for nodemailer. It works, but in direct-MX mode (no relay, send straight to the recipient's MX server) it has three sharp edges:

1. TLS state is opaque. You don't know which cipher was negotiated, whether the peer cert validated, or even whether STARTTLS was used at all — the info response doesn't surface any of it. The only path to that data is parsing the SMTP transcript out of the logger option, which is fragile.
2. Cert validation is all-or-nothing. rejectUnauthorized: false is the standard MTA-to-MTA practice (self-signed and expired certs are everywhere), but there's no way to track what would have happened under strict mode, and no way to enforce strict validation for known-good MX hosts (Gmail, Outlook).
3. DKIM signing is a separate plugin. Works fine, but means another dep to keep current.

@bunmail/smtp is opinionated about all three:

• Every sendMail returns result.tls.{used, protocol, cipher, peerCert.{subject, issuer, validFrom, validTo, selfSigned, validated}} — captured natively, no log scraping.
• Opportunistic TLS is the default (matching real-world MTA practice). requireValidFor: ["gmail.com"] opts into strict cert validation for receivers where you know it should work.
• DKIM signing is built-in (RFC 6376), implemented against node:crypto. No plugin, no extra dep.

Install

bun add @bunmail/smtp

Usage (v0.1.0 surface)

import { sendMail } from "@bunmail/smtp";

const result = await sendMail({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome",
  html: "<p>Hi!</p>",
  text: "Hi!",

  dkim: {
    domain: "your-domain.com",
    selector: "bunmail",
    privateKey: process.env.DKIM_KEY_PEM!,
  },

  tls: {
    requireValidFor: ["gmail.com"], // strict cert validation for known-good MX
  },
});

console.log("Delivered via", result.mxHost);
console.log("TLS used:", result.tls.used);
console.log("Cipher:", result.tls.cipher);
console.log("Cert validated:", result.tls.peerCert?.validated);

Result shape

{
  messageId: string;
  accepted: string[];
  rejected: string[];
  mxHost: string;
  tls: {
    used: boolean;
    protocol?: "TLSv1.2" | "TLSv1.3" | string;
    cipher?: string;
    peerCert?: {
      subject: string;
      issuer: string;
      validFrom: Date;
      validTo: Date;
      selfSigned: boolean;
      validated: boolean;
    };
  };
  trace?: string[]; // SMTP transcript when debug: true
}

Design constraints

• Bun-only. Uses Bun.connect(), node:tls, node:dns/promises, node:crypto. Does not target Node.
• Zero npm dependencies. Pure stdlib. No transitive supply-chain surface beyond Bun itself.
• Direct-to-MX only (v0.1). No relay / no auth / no pooled transport. Send-to-the-recipient's-MX is the only path supported.
• Strict TypeScript. No any, exactOptionalPropertyTypes: true, noUncheckedIndexedAccess: true.

If you need pooled transports, auth/relay mode, or Node compatibility — nodemailer is the right answer.

Roadmap

• v0.0.1 (this release) — scaffolding. Type surface only. Throws.
• v0.1.0 — SMTP state machine (EHLO → STARTTLS → MAIL FROM → RCPT TO → DATA → QUIT), DKIM signing, TLS metadata capture, opportunistic + strict modes. Tested against a fake-server harness.
• v0.2.0 — auth/relay mode (PLAIN/LOGIN), connection pooling.
• v1.0.0 — once the surface stabilises and BunMail has run on it in production for a quarter.

Used by

• BunMail — self-hosted email API. Reference implementation; the package is extracted from BunMail's outbound transport.

License

MIT © mohamedboukari