- Go
- SMTP
- Docker
- Next.js
- REST API
About
Deadletter is a small, self-contained SMTP sink designed for local development and testing. Instead of sending emails to real SMTP providers, applications send them to Deadletter. Every message is captured exactly once as a raw .eml file plus immutable metadata, and indexed in memory so it can be inspected, replayed, and observed through a simple HTTP API or web UI.
The filesystem is the source of truth. In-memory state exists only to support fast inspection, derived metrics, timelines, and replay counters. Deadletter is intentionally minimal: no external dependencies, no fake inboxes, and no risk of accidentally delivering emails to real users.
Features
- SMTP Capture
- Captures every email sent to port 1025 as a raw .eml file with immutable JSON metadata. Zero config, zero risk.
- Web UI
- A clean, developer-focused web interface at port 8025 for browsing captured emails, viewing headers, body content, and metadata.
- Email Replay
- Re-send any captured email to a real SMTP server for testing forwarding rules, templates, and delivery pipelines.
- REST API
- Full HTTP API for listing, inspecting, exporting, and replaying emails. Integrates with any CI/CD pipeline or testing framework.
- CLI Tool
- A lightweight CLI (deadletterctl) for scripting against the HTTP API. List, show, replay, and export emails from the terminal.
- Retention Policy
- Configurable retention in minutes controls how long messages are kept. Cleanup can be triggered manually or runs automatically.
Getting Started
Docker
docker run -d \
--name deadletter \
-p 1025:1025 \
-p 8025:8025 \
-v "$PWD/data:/data" \
peixotomdb/deadletter:latest- SMTP
- localhost:1025
- HTTP
- localhost:8025
API Reference
| Method | Path | Description |
|---|---|---|
| GET | /health | Overall state, version, uptime, metrics |
| GET | /emails | List email metadata (newest first) |
| GET | /emails/{id} | Single email metadata |
| GET | /emails/{id}/raw | Raw .eml file |
| GET | /config/replay | Read replay configuration |
| PUT | /config/replay | Update replay config |
| POST | /replay | Re-send a captured email |
| GET | /events | SSE stream with notifications |
CLI
deadletterctl
# list all emails
go run ./cmd/deadletterctl list
# inspect metadata
go run ./cmd/deadletterctl show <id>
# replay / export
go run ./cmd/deadletterctl replay <id>
go run ./cmd/deadletterctl export <id> eml
go run ./cmd/deadletterctl export <id> json