Skip to content

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

1 star

Watchers

0 watching

Forks

Sponsor this project

 

Packages

 
 
 

Contributors

Languages