https://github.com/btafoya/mailsandbox
MailSandbox is a fast, zero-dependency email testing tool & API with a web UI, SMTP server, Postmark API emulation, and MCP server for AI-assisted debugging.
https://github.com/btafoya/mailsandbox
Last synced: about 2 months ago
JSON representation
MailSandbox is a fast, zero-dependency email testing tool & API with a web UI, SMTP server, Postmark API emulation, and MCP server for AI-assisted debugging.
- Host: GitHub
- URL: https://github.com/btafoya/mailsandbox
- Owner: btafoya
- License: mit
- Created: 2025-09-09T18:35:04.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-09-15T04:06:11.000Z (3 months ago)
- Last Synced: 2025-09-25T18:05:56.409Z (2 months ago)
- Language: Go
- Homepage:
- Size: 3.7 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
- awesome-mcp-servers - **MailSandbox** - MailSandbox (a fork of Mailpit) is a fast, zero-dependency email testing tool & API with a web UI, SMTP server, Postmark API emulation, and MCP server for AI-assisted debugging. `api` `web` `http` `ai` `git` (📦 Other)
- awesome-mcp-servers - MailSandbox - MailSandbox (a fork of Mailpit) is a fast, zero-dependency email testing tool & API with a web UI, SMTP server, Postmark API emulation, and MCP server for AI-assisted debugging. (Official Servers)
README
# MailSandbox — email testing & simulation for developers
> **Fork of [Mailpit](https://github.com/axllent/mailpit)** adding Postmark API emulation and an MCP server for AI-assisted debugging.
> Inspired by and grateful to the original work on **Mailpit** and **MailHog**. See [Credits](#credits--acknowledgements).
[](https://opensource.org/licenses/MIT)
[](https://golang.org/)
[](https://www.docker.com/)
[](https://github.com/btafoya/mailsandbox/actions/workflows/build-docker-edge.yml)
[](https://github.com/btafoya/mailsandbox/actions/workflows/build-docker.yml)
[](https://github.com/btafoya/mailsandbox/actions/workflows/codeql-analysis.yml)
[](https://github.com/btafoya/mailsandbox/actions/workflows/tests-rqlite.yml)
[](https://github.com/btafoya/mailsandbox/actions/workflows/release-build.yml)
Repository •
Installation •
Usage •
Postmark API •
MCP Server
---
**MailSandbox** is a small, fast, low-memory, zero-dependency, multi-platform **email testing tool & API** for developers.
It provides an SMTP server, modern web interface, REST API, Postmark API emulation, and an MCP server for AI-powered workflows.
---
## Features
- 🚀 **Lightweight** — single static binary or multi-arch Docker image
- 🌐 **Modern Web UI** — view HTML, source, headers, attachments, search & filter
- 📬 **SMTP & POP3 servers** — STARTTLS/SSL/TLS, authentication, forwarding, relaying
- 🔍 **Testing tools** — HTML check, link check, spam score, screenshots, mobile preview
- 🏷 **Tagging & filtering** — manual or automated (incl. plus addressing)
- ⚡ **Performance** — 100–200 emails/sec, automatic pruning (default 500 emails)
- 🧪 **Chaos mode** — inject SMTP errors to test resilience
- 🔔 **Integrations** — webhooks, browser notifications, `List-Unsubscribe` validation
- 🆕 **Postmark API emulation** — drop-in replacement for Postmark during development
- 🤖 **MCP server** — AI assistants (e.g., Claude Code) can list, search, and analyze messages
---
## Installation
The web UI runs on `http://0.0.0.0:8025` and SMTP on `0.0.0.0:1025`.
### Script (Linux & macOS)
```bash
sudo sh < <(curl -sL https://raw.githubusercontent.com/btafoya/mailsandbox/main/install.sh)
```
### Static binary
Download from [releases](https://github.com/btafoya/mailsandbox/releases/latest), rename to `mailsandbox`, and add to `$PATH`.
### Docker
```bash
docker run -d --name mailsandbox -p 8025:8025 -p 1025:1025 btafoya/mailsandbox
```
---
## Usage
List options:
```bash
mailsandbox -h
```
## Postmark API Emulation
Enable Postmark API emulation:
```bash
mailsandbox --postmark-api --postmark-token "your-secret-token"
```
Environment variables:
```bash
export MP_POSTMARK_API=true
export MP_POSTMARK_TOKEN=your-secret-token
mailsandbox
```
**Example: Node.js**
```js
const postmark = require("postmark");
const client = new postmark.ServerClient("your-secret-token");
client.apiUrl = "http://localhost:8025";
client.sendEmail({ From:"a@x.com", To:"b@y.com", Subject:"Test", TextBody:"Hello" });
```
Endpoints:
- `POST /email`
- `POST /email/batch`
- `POST /email/withTemplate`
---
## MCP Server for AI Assistants
Enable MCP server:
```bash
mailsandbox --mcp-server --mcp-transport stdio
```
Environment variables:
```bash
export MP_MCP_SERVER=true
export MP_MCP_TRANSPORT=stdio
```
### Docker with MCP
```bash
docker build -t mailsandbox-with-mcp .
docker run -d --name mailsandbox -p 127.0.0.1:8025:8025 -p 1025:1025 -e MP_MCP_SERVER=true -e MP_MCP_TRANSPORT=stdio -e MP_POSTMARK_API=true -e MP_POSTMARK_TOKEN=dev-token-123 mailsandbox-with-mcp
```
### MCP tools
- `list_messages` — list/filter emails
- `get_message` — retrieve full message
- `search_messages` — advanced search
- `analyze_message` — HTML, links, spam scoring
---
## Migration Guide
- Binary name renamed `mailsandbox`; create a symlink if you prefer `mailpit`.
- Default ports unchanged: HTTP `8025`, SMTP `1025`.
- APIs: REST API unchanged; Postmark & MCP are opt-in.
- Docker: use forked image for MCP/Postmark features.
---
## Credits & Acknowledgements
- **[Mailpit](https://github.com/axllent/mailpit)** — by Axel Lenferna de la Motte and contributors. Original project and active development.
- **[MailHog](https://github.com/mailhog/MailHog)** — the original inspiration for mainer email testing tools.
- **[MailSandbox](https://github.com/btafoya/mailsandbox)** — maintained by Brian Tafoya, adding Postmark API emulation and MCP server support.
---
## License
MailSandbox inherits the upstream license from Mailpit. See `LICENSE` for details.
## Star History
[](https://www.star-history.com/#btafoya/mailsandbox&Date)