Session & Envelope

SMTPSession object and related types

Every callback receives a session object representing the current connection state.

---

SMTPSession

The main session object passed to all callbacks.

id · string

Unique connection identifier.

secure · boolean

true if the connection is currently using TLS.

servername · string | undefined

SNI hostname from the TLS handshake (if TLS is active).

localAddress · string

Server IP address.

localPort · number

Server port.

remoteAddress · string

Client IP address.

remotePort · number

Client port.

clientHostname · string

Reverse-DNS hostname of the client. Falls back to "[remoteAddress]" if lookup fails or is disabled.

hostNameAppearsAs · string

Hostname the client claimed in HELO/EHLO.

openingCommand · string

The first command the client sent: "HELO", "EHLO", or "LHLO".

transmissionType · string

SMTP transmission type string, e.g. "ESMTPSA" (Extended SMTP with Auth).

tlsOptions · TLSCipherInfo | false

TLS cipher info after TLS is established, false before. See TLSCipherInfo below.

user · unknown

Value passed as user in a successful onAuth response. Use this to track the authenticated user.

transaction · number

Number of completed mail transactions on this connection (incremented after each successful onData).

envelope · SMTPEnvelope

Current mail envelope. See SMTPEnvelope below.

xClient · Map<string, string | false>

XCLIENT header values (when useXClient: true).

xForward · Map<string, string | false>

XFORWARD header values (when useXForward: true).

---

TLSCipherInfo

TLS cipher and protocol information, available after TLS handshake.

name · string

OpenSSL cipher name (e.g. "ECDHE-RSA-AES128-GCM-SHA256").

standardName · string | undefined

IANA cipher name.

version · string | undefined

TLS protocol version (e.g. "TLSv1.3").

Example

const server = new SMTPServer({
  onSecure(socket, session, callback) {
    console.log(session.tlsOptions);
    // {
    //   name: "ECDHE-RSA-AES128-GCM-SHA256",
    //   standardName: "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    //   version: "TLSv1.2"
    // }
    callback(null);
  },
});

---

SMTPEnvelope

Available as session.envelope. Populated progressively as the client sends MAIL FROM and RCPT TO commands.

mailFrom · SMTPAddress | false

Sender address from MAIL FROM, or false before MAIL FROM is received.

rcptTo · SMTPAddress[]

Array of accepted recipient addresses from RCPT TO.

bodyType · '7bit' | '8bitmime'

Body encoding declared by the client.

smtpUtf8 · boolean

true if the client declared SMTPUTF8 support.

requireTLS · boolean

true if the client sent REQUIRETLS (RFC 8689).

dsn · DSNEnvelope | undefined

DSN envelope parameters. See DSNEnvelope below.

Example

const server = new SMTPServer({
  onData(stream, session, callback) {
    const { envelope } = session;
    
    console.log("From:", envelope.mailFrom?.address);
    console.log("To:", envelope.rcptTo.map(r => r.address));
    console.log("UTF-8:", envelope.smtpUtf8);
    
    stream.pipeTo(new WritableStream()).then(
      () => callback(null),
      callback
    );
  },
});

---

SMTPAddress

Represents an email address from MAIL FROM or RCPT TO commands.

address · string

The email address (e.g. "[e-mail]").

args · SMTPAddressArgs | false

ESMTP parameters from the command, or false if none. See SMTPAddressArgs below.

dsn · DSNRcpt | undefined

Per-recipient DSN parameters. See DSNRcpt below.

---

SMTPAddressArgs

ESMTP parameters parsed from the MAIL FROM or RCPT TO command.

SIZE · string | undefined

Declared message size in bytes.

BODY · string | undefined

Body type: "7BIT" or "8BITMIME".

SMTPUTF8 · true | undefined

UTF-8 support flag.

REQUIRETLS · true | undefined

TLS-required flag (RFC 8689).

RET · string | undefined

DSN return type ("FULL" or "HDRS").

ENVID · string | undefined

DSN envelope ID.

NOTIFY · string | undefined

DSN notification conditions (comma-separated, e.g. "SUCCESS,FAILURE").

ORCPT · string | undefined

DSN original recipient address.

[key: string] · string | true | undefined

Any unrecognized ESMTP parameter is also available as a string or true.

Example

const server = new SMTPServer({
  onMailFrom(address, session, callback) {
    console.log("Sender:", address.address);
    
    if (address.args) {
      console.log("Declared size:", address.args.SIZE);
      console.log("Body type:", address.args.BODY);
      console.log("UTF-8:", address.args.SMTPUTF8);
    }
    
    callback(null);
  },
});

---

DSNEnvelope

DSN (Delivery Status Notification) parameters from the envelope.

ret · 'FULL' | 'HDRS' | null

Return type requested by the client:

• "FULL": Return full message in DSN
• "HDRS": Return headers only
• null: No preference specified

envid · string | null

Envelope identifier for tracking DSN reports.

---

DSNRcpt

Per-recipient DSN parameters.

notify · string[] | undefined

DSN notification conditions (e.g. ["SUCCESS", "FAILURE", "DELAY"]).

orcpt · string | undefined

Original recipient address (for forwarding scenarios).

Example

const server = new SMTPServer({
  onRcptTo(address, session, callback) {
    console.log("Recipient:", address.address);
    
    if (address.dsn) {
      console.log("Notify on:", address.dsn.notify);
      console.log("Original:", address.dsn.orcpt);
    }
    
    callback(null);
  },
});

---

DataStream

A ReadableStream<Uint8Array> with extra metadata set after the stream closes.

byteLength · number | undefined

Total bytes received (available after stream closes).

sizeExceeded · boolean | undefined

true if the message exceeded the configured size limit.

Example

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

---

Complete Example

import { SMTPServer } from "bun-smtp";

const server = new SMTPServer({
  onConnect(session, callback) {
    console.log(`New connection from ${session.remoteAddress}`);
    callback(null);
  },
  
  onAuth(auth, session, callback) {
    callback(null, { user: { username: auth.username } });
  },
  
  onData(stream, session, callback) {
    const { envelope, user } = session;
    
    console.log("Connection ID:", session.id);
    console.log("Secure:", session.secure);
    console.log("TLS:", session.tlsOptions);
    console.log("User:", user);
    console.log("From:", envelope.mailFrom?.address);
    console.log("To:", envelope.rcptTo.map(r => r.address));
    console.log("UTF-8:", envelope.smtpUtf8);
    console.log("Transaction #", session.transaction);
    
    stream.pipeTo(new WritableStream()).then(
      () => {
        console.log("Received:", stream.byteLength, "bytes");
        callback(null);
      },
      callback
    );
  },
  
  onClose(session) {
    console.log(`Connection ${session.id} closed`);
  },
});

server.listen(2525);