Skip to content

Trap servers for capturing and inspecting SMTP emails and HTTP requests. Built for testing Probitas and other client implementations.

License

Notifications You must be signed in to change notification settings

probitas-test/trap-servers

Repository files navigation

Trap Servers

Build trap-smtp Build trap-webhook

Trap servers for capturing and inspecting SMTP emails and HTTP requests. Built for testing Probitas and other client implementations.

Images

Image Protocol Default Port Status
ghcr.io/probitas-test/trap-smtp SMTP 8080 (Web) / 2525 (SMTP) Docker
ghcr.io/probitas-test/trap-webhook HTTP 8080 Docker

URLs (Docker Compose)

Server Web UI / API Protocol Endpoint
trap-smtp http://localhost:18091 localhost:12525
trap-webhook http://localhost:18090 (same as Web UI)

Quick Start

# 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

Environment Variables

trap-smtp

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

trap-webhook

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.

Features

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

API Endpoints

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

Filtering

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

trap-smtp specific

Endpoint Method Description
/api/entries/{id}/raw GET Get raw email (RFC 822)

trap-webhook specific

Endpoint Method Description
/webhook/* ANY Accept request on any sub-path

Documentation

Development

Prerequisites

Uses Nix Flakes for development environment management.

# Enter development environment
nix develop

# Or use direnv for automatic activation
echo "use flake" > .envrc
direnv allow

Commands

Requires 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

About

Trap servers for capturing and inspecting SMTP emails and HTTP requests. Built for testing Probitas and other client implementations.

Resources

License

Code of conduct

Stars

Watchers

Forks

Sponsor this project

 

Packages

 
 
 

Languages