SMTPServer

The main SMTPServer class and its methods

Constructor

Create a new SMTP server instance.

import { SMTPServer } from "bun-smtp";

const server = new SMTPServer(options);

options · SMTPServerOptions

Configuration options for the server. See Configuration for all available options.

---

Methods

listen()

Start the SMTP server and bind to a port.

Port only

server.listen(2525);

Parameters:

port · number

Port number to bind to

hostname · string · default: "0.0.0.0"

Hostname or IP address to bind to

callback · () => void

Function called when the server starts listening

Returns: this (for chaining)

The listening event is emitted after the server successfully binds to the port.

---

close()

Gracefully shut down the server. Active connections are allowed to finish within the closeTimeout period.

server.close(() => {
  console.log("Server has shut down");
});

callback · () => void

Function called when the server has fully closed

Returns: this (for chaining)

Connections still active after closeTimeout milliseconds are forcibly terminated.

---

updateSecureContext()

Hot-reload TLS certificates without restarting the server. New connections will use the updated certificates.

server.updateSecureContext({
  key: await Bun.file("new-key.pem").text(),
  cert: await Bun.file("new-cert.pem").text()
});

options · object · required

Show properties

key · string | Buffer

New private key in PEM format

cert · string | Buffer

New certificate in PEM format

ca · string | Buffer | Array

New CA bundle

---

Event Methods

on()

Register an event listener.

server.on("error", (err) => {
  console.error("Server error:", err);
});

event · string · required

Event name. See Events for available events.

listener · function · required

Callback function to invoke when the event is emitted

Returns: this (for chaining)

---

once()

Register a one-time event listener that is automatically removed after firing once.

server.once("listening", () => {
  console.log("Server started for the first time");
});

event · string · required

Event name

listener · function · required

Callback function to invoke once

Returns: this (for chaining)

---

off()

Remove an event listener.

const errorHandler = (err) => console.error(err);
server.on("error", errorHandler);
// Later...
server.off("error", errorHandler);

event · string · required

Event name

listener · function · required

The exact listener function to remove

Returns: this (for chaining)

---

Properties

options · SMTPServerOptions

The resolved configuration options (defaults merged with constructor options)

connections · Set<ConnectionContext>

Set of currently active connections

closing · boolean

Whether the server is in the process of shutting down

---

Example

import { SMTPServer } from "bun-smtp";

const server = new SMTPServer({
  secure: false,
  authOptional: true,
  onData(stream, session, callback) {
    console.log(`Message from ${session.envelope.mailFrom.address}`);
    stream.pipeTo(new WritableStream()).then(
      () => callback(null),
      (err) => callback(err)
    );
  }
});

server.on("error", (err) => {
  console.error("SMTP Error:", err);
});

server.listen(2525, () => {
  console.log("SMTP Server listening on port 2525");
});

// Graceful shutdown
process.on("SIGTERM", () => {
  server.close(() => {
    console.log("Server closed");
    process.exit(0);
  });
});