Quickstart

Get started with bun-smtp in minutes

Quickstart

Get your first SMTP server running with bun-smtp in just a few steps.

Installation

1. Install bun-smtp

   Add bun-smtp to your project:

   bun add bun-smtp
   

   Make sure you have Bun 1.2.0 or higher installed. Check your version with bun --version.

2. Create your server file

   Create a new file called server.ts:

   server.ts

   import { SMTPServer } from "bun-smtp";
   
   const server = new SMTPServer({
     authOptional: true,
     onData(stream, session, callback) {
       async function drain() {
         const chunks: Uint8Array[] = [];
         for await (const chunk of stream) {
           chunks.push(chunk);
         }
         console.log(`Received ${chunks.length} chunks from ${session.envelope.mailFrom?.address}`);
         callback(null);
       }
       drain().catch(callback);
     },
   });
   
   await server.listen(2525);
   console.log("SMTP server listening on port 2525");
   

   This example sets authOptional: true to accept unauthenticated connections. In production, you should implement proper authentication.

3. Run your server

   Start the server with Bun:

   bun server.ts
   

   You should see:

   SMTP server listening on port 2525
   
4. Test your server

   Test your server using curl or telnet. Here’s an example using curl:

   curl --url 'smtp://localhost:2525' \
     --mail-from '[e-mail]' \
     --mail-rcpt '[e-mail]' \
     --upload-file - <<EOF
   From: [e-mail]
   To: [e-mail]
   Subject: Test Email
   
   This is a test message.
   EOF
   

   Your server should log the received chunks.

Understanding the Code

Let’s break down what’s happening in the example:

SMTPServer Options

const server = new SMTPServer({
  authOptional: true,  // Allow connections without authentication
  onData(stream, session, callback) {
    // Handle incoming email data
  },
});

The SMTPServer constructor accepts various options. The most important ones for getting started are:

• authOptional: Set to true to allow unauthenticated connections
• onData: Callback invoked when email data is ready to be processed

The onData Callback

onData(stream, session, callback) {
  async function drain() {
    const chunks: Uint8Array[] = [];
    for await (const chunk of stream) {
      chunks.push(chunk);
    }
    callback(null);  // Signal success
  }
  drain().catch(callback);  // Handle errors
}

The onData callback receives:

• stream: A ReadableStream<Uint8Array> containing the email data
• session: An SMTPSession object with connection and envelope information
• callback: Call this with null on success, or an error object on failure

The stream must be consumed before calling the callback. Use a for await loop to read all chunks.

Starting the Server

await server.listen(2525);

The listen() method starts the server on the specified port. It returns a Promise that resolves when the server is ready.

Next Steps

Now that you have a basic server running, you can:

Add Authentication

Secure your server with SASL authentication

Enable TLS

Encrypt connections with STARTTLS or implicit TLS

Handle Messages

Save emails to a database or forward them

Configure Options

Explore all available server options

Common Patterns

Save Email to File

import { SMTPServer } from "bun-smtp";
import { join } from "path";

const server = new SMTPServer({
  authOptional: true,
  onData(stream, session, callback) {
    async function saveEmail() {
      const chunks: Uint8Array[] = [];
      for await (const chunk of stream) {
        chunks.push(chunk);
      }
      
      const buffer = Buffer.concat(chunks);
      const filename = `${session.id}-${Date.now()}.eml`;
      await Bun.write(join("./emails", filename), buffer);
      
      callback(null);
    }
    saveEmail().catch(callback);
  },
});

await server.listen(2525);

Access Envelope Information

import { SMTPServer } from "bun-smtp";

const server = new SMTPServer({
  authOptional: true,
  onMailFrom(address, session, callback) {
    console.log(`Mail from: ${address.address}`);
    callback();  // Accept the sender
  },
  onRcptTo(address, session, callback) {
    console.log(`Recipient: ${address.address}`);
    callback();  // Accept the recipient
  },
  onData(stream, session, callback) {
    async function drain() {
      const chunks: Uint8Array[] = [];
      for await (const chunk of stream) {
        chunks.push(chunk);
      }
      
      console.log(`Envelope:`, {
        from: session.envelope.mailFrom?.address,
        to: session.envelope.rcptTo.map(r => r.address),
      });
      
      callback(null);
    }
    drain().catch(callback);
  },
});

await server.listen(2525);

Reject Invalid Senders

import { SMTPServer } from "bun-smtp";
import type { SMTPError } from "bun-smtp";

const server = new SMTPServer({
  authOptional: true,
  onMailFrom(address, session, callback) {
    const allowedDomain = "example.com";
    
    if (!address.address.endsWith(`@${allowedDomain}`)) {
      const error = new Error("Invalid sender domain") as SMTPError;
      error.responseCode = 550;
      return callback(error);
    }
    
    callback();  // Accept the sender
  },
  onData(stream, session, callback) {
    async function drain() {
      const chunks: Uint8Array[] = [];
      for await (const chunk of stream) {
        chunks.push(chunk);
      }
      callback(null);
    }
    drain().catch(callback);
  },
});

await server.listen(2525);

Always validate and sanitize email addresses and data before processing them to prevent security vulnerabilities.