Callbacks

Lifecycle callbacks hook into each phase of an SMTP session. Set them as constructor options or override them on the server instance after construction. Call callback(null) to accept or callback(error) to reject. To send a custom SMTP error code, set error.responseCode:

const err = new Error("Mailbox does not exist");
err.responseCode = 550;
callback(err);

onConnect

Called as soon as a client connects, before any SMTP dialogue. Use this to block connections by IP or apply rate limits.

type OnConnectCallback = (
  session: SMTPSession,
  callback: (err?: Error | null) => void
) => void

Parameters

SMTPSession

required

The session object for this connection. See Session for details.

(err?: Error | null) => void

required

Call with null to accept the connection, or an Error to reject it.

Example

const server = new SMTPServer({
  onConnect(session, callback) {
    if (session.remoteAddress === "1.2.3.4") {
      const err = new Error("Blocked");
      err.responseCode = 421;
      return callback(err);
    }
    callback(null);
  },
});

Rejecting in onConnect immediately closes the connection without sending a full SMTP greeting.

onSecure

Called after a successful TLS handshake (both implicit TLS and STARTTLS). Use this to inspect client certificates.

type OnSecureCallback = (
  socket: Socket,
  session: SMTPSession,
  callback: (err?: Error | null) => void
) => void

Parameters

Socket

required

The Bun socket object for this connection.

SMTPSession

required

The session object. After TLS is established, session.secure is true and session.tlsOptions contains cipher info.

(err?: Error | null) => void

required

Call with null to proceed, or an Error to close the connection.

Example

const server = new SMTPServer({
  requestCert: true,
  onSecure(socket, session, callback) {
    // Inspect TLS details
    console.log("Cipher:", session.tlsOptions);
    // { name: "...", standardName: "...", version: "TLSv1.3" }
    
    callback(null);
  },
});

onAuth

Called when a client sends AUTH. The auth object varies by method — see the Authentication guide for details.

type OnAuthCallback = (
  auth: AuthObject,
  session: SMTPSession,
  callback: (err: Error | null, response?: AuthResponse) => void
) => void

Parameters

AuthObject

required

Authentication credentials. Shape depends on the SASL method used.

Show AuthObject types

PLAIN / LOGIN:

{
  method: "PLAIN" | "LOGIN",
  username: string,
  password: string
}

CRAM-MD5:

{
  method: "CRAM-MD5",
  username: string,
  challenge: string,
  challengeResponse: string,
  validatePassword: (password: string) => boolean
}

XOAUTH2:

{
  method: "XOAUTH2",
  username: string,
  accessToken: string
}

SMTPSession

required

The session object.

(err: Error | null, response?: AuthResponse) => void

required

Call with (null, response) to accept, or (error) to reject.

AuthResponse

unknown

Stored on session.user for the rest of the connection. Use this to track the authenticated user.

string

Custom success message returned to the client.

number

Custom response code (default is 235).

Record<string, string>

XOAUTH2 error challenge data.

Examples

const server = new SMTPServer({
  onAuth(auth, session, callback) {
    if (auth.method === "PLAIN" || auth.method === "LOGIN") {
      if (auth.username === "user" && auth.password === "secret") {
        return callback(null, { user: auth.username });
      }
    }
    callback(new Error("Invalid credentials"));
  },
});

const server = new SMTPServer({
  authMethods: ["CRAM-MD5"],
  onAuth(auth, session, callback) {
    if (auth.method === "CRAM-MD5") {
      if (auth.validatePassword("secret")) {
        return callback(null, { user: auth.username });
      }
    }
    callback(new Error("Invalid credentials"));
  },
});

const server = new SMTPServer({
  async onAuth(auth, session, callback) {
    try {
      const user = await db.findUser(auth.username);
      if (user && await bcrypt.compare(auth.password, user.passwordHash)) {
        callback(null, { user: user.id });
      } else {
        callback(new Error("Invalid credentials"));
      }
    } catch (err) {
      callback(err);
    }
  },
});

onMailFrom

Called when the client sends MAIL FROM. Use this to validate the sender address or enforce per-user sending policies.

type OnMailFromCallback = (
  address: SMTPAddress,
  session: SMTPSession,
  callback: (err?: Error | null) => void
) => void

Parameters

SMTPAddress

required

The sender address. See Session for the structure.Access ESMTP parameters via address.args:

address.args.SIZE     // "1048576"
address.args.BODY     // "8BITMIME"
address.args.SMTPUTF8 // true

SMTPSession

required

The session object. session.envelope.mailFrom will be set to this address if you accept.

(err?: Error | null) => void

required

Call with null to accept, or an Error to reject.

Example

const server = new SMTPServer({
  onMailFrom(address, session, callback) {
    // Block specific domains
    if (address.address.endsWith("@blocked.example")) {
      return callback(new Error("Sender not allowed"));
    }
    
    // Enforce authenticated user can only send from their own address
    if (session.user && address.address !== session.user.email) {
      const err = new Error("Not authorized to send from this address");
      err.responseCode = 550;
      return callback(err);
    }
    
    callback(null);
  },
});

onRcptTo

Called once per RCPT TO command. Reject unknown recipients here to avoid accepting mail you cannot deliver.

type OnRcptToCallback = (
  address: SMTPAddress,
  session: SMTPSession,
  callback: (err?: Error | null) => void
) => void

Parameters

SMTPAddress

required

The recipient address. Access DSN parameters via address.dsn:

address.dsn?.notify  // ["SUCCESS", "FAILURE"]
address.dsn?.orcpt   // "rfc822;original@example.com"

SMTPSession

required

The session object. Accepted recipients are added to session.envelope.rcptTo.

(err?: Error | null) => void

required

Call with null to accept, or an Error to reject.

Example

const server = new SMTPServer({
  onRcptTo(address, session, callback) {
    const known = ["alice@example.com", "bob@example.com"];
    
    if (!known.includes(address.address)) {
      const err = new Error("No such user");
      err.responseCode = 550;
      return callback(err);
    }
    
    callback(null);
  },
});

onRcptTo is called separately for each recipient. A message can have multiple recipients if all are accepted.

onData

Called when the client begins sending the message body. stream is a ReadableStream<Uint8Array>. You must consume it completely before calling callback.

type OnDataCallback = (
  stream: DataStream,
  session: SMTPSession,
  callback: (
    err: Error | null,
    message?: string | Array<string | SMTPError>
  ) => void
) => void

Parameters

DataStream

required

A ReadableStream<Uint8Array> containing the message data. Has two extra properties set after the stream closes:

Show DataStream properties

number

Total bytes received (available after stream closes)

boolean

true if the message exceeded the configured size limit

SMTPSession

required

The session object. Access sender and recipients via session.envelope.

(err: Error | null, message?: string | Array<string | SMTPError>) => void

required

Call after fully consuming the stream.

First argument: null for success, Error to reject
Second argument (optional): Custom success message, or an array of per-recipient responses for LMTP

Examples

const server = new SMTPServer({
  onData(stream, session, callback) {
    const path = `./mail-${Date.now()}.eml`;
    
    stream.pipeTo(Bun.file(path).writer()).then(
      () => {
        console.log(`Saved message to ${path}`);
        callback(null);
      },
      (err) => callback(err)
    );
  },
});

const server = new SMTPServer({
  onData(stream, session, callback) {
    async function process() {
      const chunks = [];
      for await (const chunk of stream) {
        chunks.push(chunk);
      }
      const body = Buffer.concat(chunks).toString();
      
      // Parse or store the message
      console.log("From:", session.envelope.mailFrom.address);
      console.log("To:", session.envelope.rcptTo.map(r => r.address));
      console.log("Size:", stream.byteLength);
      
      callback(null);
    }
    process().catch(callback);
  },
});

const server = new SMTPServer({
  size: 10 * 1024 * 1024, // 10 MB
  onData(stream, session, callback) {
    async function process() {
      for await (const chunk of stream) {
        // drain
      }
      
      if (stream.sizeExceeded) {
        const err = new Error("Message too large");
        err.responseCode = 552;
        return callback(err);
      }
      
      callback(null);
    }
    process().catch(callback);
  },
});

const server = new SMTPServer({
  lmtp: true,
  onData(stream, session, callback) {
    async function process() {
      for await (const chunk of stream) {}
      
      const responses = session.envelope.rcptTo.map((rcpt) => {
        if (rcpt.address === "bad@example.com") {
          const err = new Error("Mailbox full");
          err.responseCode = 452;
          return err;
        }
        return "Message accepted";
      });
      
      callback(null, responses);
    }
    process().catch(callback);
  },
});

You must fully consume the stream before calling the callback. Failing to do so will cause the connection to hang.

onClose

Called when a connection closes, regardless of reason. No callback — return value is ignored. Use this for cleanup or logging.

type OnCloseCallback = (session: SMTPSession) => void

Parameters

SMTPSession

required

The session object for the closed connection.

Example

const server = new SMTPServer({
  onClose(session) {
    console.log(
      `Connection ${session.id} closed after ${session.transaction} transactions`
    );
    
    if (session.error) {
      console.error("Connection error:", session.error);
    }
  },
});

onClose is always called, even if the connection was rejected during onConnect or terminated due to an error.

Get Started

Guides

API Reference

Examples

onConnect

Parameters

Example

onSecure

Parameters

Example

onAuth

Parameters

AuthResponse

Examples

onMailFrom

Parameters

Example

onRcptTo

Parameters

Example

onData

Parameters

Examples

onClose

Parameters

Example

​onConnect

​Parameters

​Example

​onSecure

​Parameters

​Example

​onAuth

​Parameters

​AuthResponse

​Examples

​onMailFrom

​Parameters

​Example

​onRcptTo

​Parameters

​Example

​onData

​Parameters

​Examples

​onClose

​Parameters

​Example

onConnect

Parameters

Example

onSecure

Parameters

Example

onAuth

Parameters

AuthResponse

Examples

onMailFrom

Parameters

Example

onRcptTo

Parameters

Example

onData

Parameters

Examples

onClose

Parameters

Example