MailRider 📧

Universal SMTP + IMAP mail server for local development

MailRider is a lightweight Docker container that provides SMTP and IMAP servers for local development. It routes ALL email addresses and domains to a single inbox, making it perfect for testing multi-tenant applications and email workflows.

The screenshot is illustrative and may not show every control available in the current Web UI.

✨ Features

• ✅ Universal Routing - Catches ALL email addresses and domains
• ✅ Instant Setup - One command to start via Docker
• ✅ Web UI - Built-in interface for viewing emails
• ✅ Standard Protocols - SMTP (localhost:2587) + IMAP (localhost:1143, container port 143)
• ✅ Data Persistence - Maildir format with volume support
• ✅ Perfect for Testing - Multi-workspace routing, email workflows, notifications
• ✅ Folder Management - Move emails into folders; toast notification confirms each move
• ✅ Bulk Selection - Selected-email counter displayed next to the 'Delete selected' button
• ✅ Dynamic 'Move to…' Menu - Dropdown lists all folders, including newly created empty ones

🚀 Quick Start

Using Docker Run

docker run -d \
  -p 2587:2587 \
  -p 1143:143 \
  -p 8082:8082 \
  -v mailrider-data:/var/mail/mailrider \
  --name mailrider \
  petrfilip/mailrider:latest

Using Docker Compose

version: '3.8'
services:
  mailrider:
    image: petrfilip/mailrider:latest
    ports:
      - "2587:2587"  # SMTP
      - "1143:143"   # IMAP
      - "8082:8082"  # Web UI
    volumes:
      - mailrider-data:/var/mail/mailrider
    restart: unless-stopped
volumes:
  mailrider-data:

Then run:

docker-compose up -d

Access

• Web UI: http://localhost:8082
• SMTP: localhost:2587
• IMAP: localhost:1143 (credentials: inbox@mailrider.local / test)

Send a Test Email

echo -e "From: test@example.com\nTo: user@anydomain.com\nSubject: Test\n\nHello!" | curl --url "smtp://localhost:2587" --mail-from "test@example.com" --mail-rcpt "user@anydomain.com" --upload-file -

All emails sent to any address will appear in the Web UI!

📚 Documentation

• Quick Start Guide - Get started in 3 steps
• API Documentation - HTTP, SMTP, and IMAP APIs
• Full Documentation - Architecture, troubleshooting, and more
• GitHub Pages - Interactive documentation and examples

🔒 Security

All user-supplied data rendered in the Web UI — including email metadata (sender, subject, recipients), folder names, and error messages — is HTML-escaped before being inserted into the DOM to prevent cross-site scripting. Server-side endpoints validate folder names against an allowlist of safe characters and sanitize values before they are written to HTTP response headers. HTML email content is isolated in a sandboxed iframe with its own Content Security Policy, and remote content is blocked by default.

🎯 Use Cases

• Multi-tenant Testing - Test email routing for different workspaces/tenants
• Email Workflows - Debug notification systems and email templates
• Integration Testing - Verify email sending in CI/CD pipelines
• Development - Local email server without external dependencies

🔧 Configuration

Environment variables for customization:

Variable	Default	Description
SMTP_PORT	2587	SMTP server port
WEB_PORT	8082	Web UI port
MAILDIR_BASE	/var/mail/mailrider	Mail storage root inside the container
MAILRIDER_USER	inbox	IMAP username
MAILRIDER_DOMAIN	mailrider.local	Email domain (display only)
LOG_LEVEL	info	Logging level (debug, info, warn, error)
SMTP_DEBUG	false	Enable low-level smtp-server protocol logging when set to true
WEB_AUTH_USER	–	Optional HTTP Basic auth username for the Web UI/API
WEB_AUTH_PASSWORD	–	Optional HTTP Basic auth password for the Web UI/API
MAX_MESSAGE_SIZE	52428800	Max accepted message / EML upload size in bytes (50 MB)
RETENTION_MAX_AGE_DAYS	0	Auto-delete emails older than N days (0 = disabled)
RETENTION_MAX_COUNT	0	Keep only the newest N emails (0 = disabled)
RETENTION_INTERVAL_MS	3600000	How often the retention cleanup runs (ms)

⚠️ MailRider has no authentication and no TLS by design — it is a local development tool. Never expose it to the public internet. When both WEB_AUTH_USER and WEB_AUTH_PASSWORD are set, the Web UI/API requires HTTP Basic auth as a light safeguard for shared dev environments. The example Docker port mappings publish on all host interfaces; bind them to 127.0.0.1 or protect them with a firewall on network-reachable hosts.

🏗️ Building from Source

git clone https://github.com/petrfilip/mailrider.git
cd mailrider
docker build -t mailrider .

🐛 Troubleshooting

Port already in use

# Change ports in docker-compose.yml or docker run command
-p 3587:2587  # Use different host port

Emails not appearing

1. Check container logs: docker logs mailrider
2. Verify SMTP connection: nc -zv localhost 2587
3. Check Web UI: http://localhost:8082

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⭐ Show Your Support

If you find MailRider useful, please consider giving it a star on GitHub!

---

Made with ❤️ for developers who test email workflows