The Post

Finally a mail server that can be managed.

Note

Perfect for local development and testing environments. Production-ready release coming soon!

While this mail server works in a zero-setup & zero-config way, you still have to maintain the infrastructure that the server is deployed & running on. To automate it, including pretty server metrics visualizations & alerting, you may want to check out Stacks, as it ships a full-featured mail server with a management interface/dashboard.

Features

• 📨 Mail Server lightweight & configurable
• 🛠️ Mail Utilities send, receive, and manage emails
• 📦 Mail UI web interfaces for managing emails, including a component library
• 🤖 CLI command-line interface for managing emails
• 🔒 Security TLS support, authentication, and spam protection
• 🚀 Performance optimized for high-throughput environments
• 🎯 Modern built with TypeScript, zero dependencies
• 📝 Logging detailed logging and monitoring capabilities

Install

bun install -d @stacksjs/post

Get Started

There are two ways of using the mail server: as a library or as a CLI.

Library Usage

import { SMTPServer } from '@stacksjs/post'

// Basic SMTP Server
const server = new SMTPServer({
  secure: true,
  name: 'mail.example.com',
  banner: 'Welcome to My Mail Server',
})

server.listen(25)

// Advanced Configuration
const secureServer = new SMTPServer({
  // TLS Configuration
  secure: true,
  needsUpgrade: false,
  sniOptions: new Map([
    ['example.com', {
      key: fs.readFileSync('certs/example.com.key'),
      cert: fs.readFileSync('certs/example.com.cert')
    }]
  ]),

  // Authentication
  authMethods: ['PLAIN', 'LOGIN'],
  onAuth: (auth, session, callback) => {
    if (auth.username === 'user' && auth.password === 'pass')
      callback(null, { user: 'user' })
    else
      callback(new Error('Invalid credentials'))
  },

  // Message Handling
  size: 1024 * 1024, // 1MB limit
  onData: (stream, session, callback) => {
    stream.pipe(process.stdout) // Echo message to console
    stream.on('end', callback)
  },

  // Logging
  logger: {
    info: console.log,
    debug: console.debug,
    error: console.error
  }
})

secureServer.listen(465) // SMTPS port

Event Handling

server.on('connect', (session) => {
  console.log('New connection from', session.remoteAddress)
})

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

server.on('close', () => {
  console.log('Server shutting down')
})

CLI Usage

The Post CLI provides a comprehensive set of commands for managing your mail server:

# Start the server
post start                   # Start with default config
post start --config custom   # Use custom config file
post start --port 25         # Specify port
post start --secure          # Start in TLS mode

# Configuration
post init                   # Create default config file
post config show            # Display current configuration
post config set key=value   # Update configuration

# Monitoring
post status                 # Show server status
post logs                   # View server logs
post logs --live            # Live log streaming
post stats                  # Show server statistics

# User Management
post users list            # List all users
post users add <email>     # Add new user
post users remove <email>  # Remove user
post users quota <email>   # Show/set user quota

# Queue Management
post queue list            # List queued messages
post queue flush           # Process all queued messages
post queue remove <id>     # Remove message from queue

# Security
post tls setup            # Configure TLS certificates
post tls renew            # Renew certificates
post blacklist add <ip>   # Add IP to blacklist
post whitelist add <ip>   # Add IP to whitelist

# Maintenance
post backup              # Create server backup
post restore <file>      # Restore from backup
post cleanup             # Clean old logs/messages

# Advanced
post test             # Run server tests
post benchmark        # Run performance tests
post debug            # Start in debug mode

Configuration

The Mail Server can be configured using a post.config.ts (or post.config.js) file:

// post.config.ts
export default {
  // Server Configuration
  server: {
    name: 'mail.example.com',
    secure: true,
    ports: {
      smtp: 25,
      smtps: 465,
      submission: 587
    }
  },

  // TLS Configuration
  tls: {
    cert: '/path/to/cert.pem',
    key: '/path/to/key.pem',
    domains: ['example.com', 'mail.example.com']
  },

  // Authentication
  auth: {
    methods: ['PLAIN', 'LOGIN'],
    database: 'sqlite://users.db'
  },

  // Storage
  storage: {
    type: 'disk',
    path: '/var/mail',
    quota: '1GB'
  },

  // Security
  security: {
    rateLimit: {
      window: '1h',
      max: 1000
    },
    spamProtection: true,
    dnsbl: ['zen.spamhaus.org']
  },

  // Logging
  logging: {
    level: 'info',
    file: '/var/log/post.log',
    format: 'json'
  }
}

Then run:

post start

To learn more, head over to the documentation.

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! We also publish them on our website. And thank you, Spatie

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• Andris Reinman (Author of nodemailer & smtp-server)
• Ralph Slooten (Author of mailtrap)
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙