MailStub

A lightweight email testing tool for developers. Catch and view test emails in a clean interface without sending to real inboxes.

Features

• 📧 Organized Projects - Separate emails by project for easy management
• 👥 Multiple Users - Create test users and send to different recipients
• 🎨 Clean Interface - Beautiful UI with dark mode support
• 🚀 Simple Setup - Start testing emails in minutes
• 💾 Local Storage - All data stored locally in SQLite
• 🔌 Easy Integration - Simple client library for sending test emails

Installation

Install MailStub globally via npm:

npm install -g mailstub

Or using your preferred package manager:

# pnpm
pnpm add -g mailstub

# yarn
yarn global add mailstub

Quick Start

1. Start the MailStub server

mailstub start

The server will start on http://localhost:8000 by default.

2. Create a project and user

Open your browser to http://localhost:8000 and:

1. Create your first project (e.g., "My App")
2. Add a test user with an email address (e.g., "[email protected]")
3. Copy your project ID from the UI

3. Install the client in your application

npm install mailstub-client

Or using your preferred package manager:

# pnpm
pnpm add mailstub-client

# yarn
yarn add mailstub-client

4. Send test emails from your app

import { client } from 'mailstub-client';

await client.send('p_your-project-id', {
  sender: '[email protected]',
  receiver: '[email protected]',
  subject: 'Welcome to My App!',
  body: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
});

Check the MailStub UI to see your test email!

Development vs Production

Create an abstraction layer to easily switch between MailStub for development and real email services for production:

import { client as mailstubClient } from 'mailstub-client';
import sendgrid from '@sendgrid/mail';

sendgrid.setApiKey(process.env.SENDGRID_API_KEY || '');

export async function sendEmail({ to, from, subject, html }) {
  if (process.env.NODE_ENV === 'production') {
    // Production: Use real email service
    await sendgrid.send({ to, from, subject, html });
  } else {
    // Development: Catch emails in MailStub
    await mailstubClient.send(process.env.MAILSTUB_PROJECT_ID!, {
      sender: from,
      receiver: to,
      subject,
      body: html
    });
  }
}

// Usage anywhere in your app:
await sendEmail({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Welcome to our app!</h1>'
});

This pattern keeps your code clean and makes it easy to switch between testing and production environments.

CLI Options

# Start with default settings
mailstub start

# Use a custom port
mailstub start --port 3000

Available Options

• -p, --port <number> - Port number for the server (default: 8000)
• -V, --version - Output the version number
• -h, --help - Display help information

Client API

client.send(projectId, options)

Send a test email to MailStub.

Parameters:

• projectId (string) - Your project ID (format: p_xxxxx)
• options (object):
  • sender (string) - Full sender email address
  • receiver (string) - Recipient email (must be a user in your project)
  • subject (string) - Email subject line
  • body (string) - Email body (HTML supported)

Returns: Promise with the created message object

Example:

import { client } from 'mailstub-client';

const result = await client.send('p_abc123', {
  sender: '[email protected]',
  receiver: '[email protected]',
  subject: 'Password Reset',
  body: '<p>Click here to reset your password...</p>'
});

console.log(result.message.id); // m_xyz789

Custom Server Port

By default, the client connects to http://localhost:8000. If you're running MailStub on a different port, update the client configuration:

import { createClient } from 'mailstub-client';

// Connect to MailStub running on port 3000
const client = createClient({ port: 3000 });

await client.send('p_abc123', {
  sender: '[email protected]',
  receiver: '[email protected]',
  subject: 'Password Reset',
  body: '<p>Click here to reset your password...</p>'
});

Usage Guidelines

✅ Use MailStub For:

• Local development and testing
• Staging and QA environments
• CI/CD pipeline testing
• Demo environments
• Integration testing without real emails

❌ Don't Use MailStub For:

• Production email delivery
• Real customer communications
• Sensitive or PII data
• Compliance-regulated communications
• High-volume or mission-critical sends

Disclaimer: MailStub is designed exclusively for testing purposes. It does not send real emails or provide delivery guarantees, encryption, or compliance features. For production environments, use a proper transactional email service like SendGrid, Postmark, or AWS SES.

Data Storage

MailStub stores all data in a SQLite database in your home directory:

• Mac/Linux: ~/.mailstub/mailstub.db
• Windows: C:\Users\<YourUsername>\.mailstub\mailstub.db

This database:

• Contains only test email data
• Uses SQLite for efficient querying and storage
• Is created automatically on first run
• Is unencrypted (never store sensitive information)

Security Note: The database should only contain test data. Never use MailStub for production emails or sensitive information.

Troubleshooting

Port already in use

If port 8000 is already in use, specify a different port:

mailstub start --port 3000

Database location

Your database is automatically stored in your home directory (see Data Storage section for the exact path). To view or backup your data, you can use any SQLite browser tool.

Frontend not loading

Make sure you're accessing http://localhost:8000 (or your custom port) in your browser.

License

MIT

Support

• 🐛 Report Issues
• 📖 Documentation

Made with ❤️ for developers who need to test emails without the hassle.