Trap servers for capturing and inspecting SMTP emails and HTTP requests. Built for testing Probitas and other client implementations.
| Image | Protocol | Default Port | Status |
|---|---|---|---|
ghcr.io/probitas-test/trap-smtp |
SMTP | 8080 (Web) / 2525 (SMTP) | |
ghcr.io/probitas-test/trap-webhook |
HTTP | 8080 |
| Server | Web UI / API | Protocol Endpoint |
|---|---|---|
| trap-smtp | http://localhost:18091 |
localhost:12525 |
| trap-webhook | http://localhost:18090 |
(same as Web UI) |
# Start all servers
docker compose up -d
# Test trap-webhook: Send a request
curl -X POST http://localhost:18090/webhook/test \
-H "Content-Type: application/json" \
-d '{"message": "hello"}'
# View captured requests
curl http://localhost:18090/api/entries
# Test trap-smtp: Send an email
echo -e "Subject: Test\n\nHello World" | \
curl smtp://localhost:12525 \
--mail-from sender@example.com \
--mail-rcpt recipient@example.com \
--upload-file -
# View captured emails
curl http://localhost:18091/api/entries
# Stop all servers
docker compose down| Variable | Description | Default |
|---|---|---|
HOST |
Bind address | 0.0.0.0 |
WEB_PORT |
HTTP API port | 8080 |
SMTP_PORT |
SMTP server port | 2525 |
MAX_ENTRIES |
Maximum entries to keep | 1000 |
ENTRY_TTL |
Entry TTL in seconds | 3600 |
SMTP_DOMAIN |
SMTP domain name | localhost |
SMTP_MAX_SIZE |
Maximum message size in bytes | 10485760 |
ALLOW_INSECURE |
Allow insecure SMTP connections | true |
| Variable | Description | Default |
|---|---|---|
HOST |
Bind address | 0.0.0.0 |
PORT |
HTTP API port | 8080 |
MAX_ENTRIES |
Maximum entries to keep | 1000 |
ENTRY_TTL |
Entry TTL in seconds | 3600 |
Servers also support .env file for configuration.
All servers are designed for testing purposes:
- Stateful storage - Captured entries are stored in-memory with configurable TTL
- Web UI - Built-in web interface for viewing captured entries
- REST API - JSON API for programmatic access
- Server-Sent Events - Real-time updates via SSE
- No rate limits - Test high-throughput scenarios
- Minimal images - Built on scratch, ~10-20MB each
Both servers provide the following endpoints:
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Web UI |
/doc |
GET | API documentation (Markdown) |
/api/entries |
GET | List all entries (newest first) |
/api/entries/{id} |
GET | Get specific entry |
/api/entries/{id} |
DELETE | Delete specific entry |
/api/entries |
DELETE | Clear all entries |
/api/stats |
GET | Store statistics |
/api/count |
GET | Count entries matching filter |
/api/await |
GET | Wait for entries matching filter |
/api/events |
GET | Server-Sent Events stream |
/health |
GET | Health check |
GET /api/entries supports query parameters for filtering:
| Parameter | Description | trap-smtp | trap-webhook |
|---|---|---|---|
from |
Contains match on sender | ✓ | |
from_regex |
Regex match on sender | ✓ | |
to |
Contains match on any recipient | ✓ | |
to_regex |
Regex match on any recipient | ✓ | |
subject |
Contains match on subject | ✓ | |
subject_regex |
Regex match on subject | ✓ | |
method |
Exact match on HTTP method | ✓ | |
path |
Contains match on request path | ✓ | |
path_regex |
Regex match on request path | ✓ | |
query |
Contains match on query string | ✓ | |
query_regex |
Regex match on query string | ✓ | |
body |
Contains match on body | ✓ | ✓ |
body_regex |
Regex match on body | ✓ | ✓ |
jsonpath |
JSONPath expression for body | ✓ | ✓ |
jsonpath_value |
Expected value at JSONPath | ✓ | ✓ |
content_type |
Contains match on Content-Type | ✓ | |
content_type_regex |
Regex match on Content-Type | ✓ | |
header |
Header name to check | ✓ | ✓ |
header_value |
Header value contains match | ✓ | ✓ |
host |
Contains match on Host header | ✓ | |
host_regex |
Regex match on Host header | ✓ | |
since |
ReceivedAt after (RFC3339) | ✓ | ✓ |
until |
ReceivedAt before (RFC3339) | ✓ | ✓ |
limit |
Maximum number of results | ✓ | ✓ |
offset |
Skip first N results | ✓ | ✓ |
| Endpoint | Method | Description |
|---|---|---|
/api/entries/{id}/raw |
GET | Get raw email (RFC 822) |
| Endpoint | Method | Description |
|---|---|---|
/webhook/* |
ANY | Accept request on any sub-path |
- trap-smtp - SMTP trap server
- trap-webhook - Webhook trap server
Uses Nix Flakes for development environment management.
# Enter development environment
nix develop
# Or use direnv for automatic activation
echo "use flake" > .envrc
direnv allowRequires just command runner (included in Nix environment).
# Show available commands
just
# Run linter on all packages
just lint
# Run tests on all packages
just test
# Build all packages
just build
# Format all code (Go + Markdown/JSON/YAML)
just fmt
# Build and run Docker images
docker compose up --build