MailLaser

Turn incoming emails into webhook calls -- no mail server required.

MailLaser is a lightweight SMTP server that receives emails and instantly forwards them as JSON payloads to any HTTP endpoint. Connect email to Slack, Discord, Zapier, or your own API with a single Docker command and two environment variables.

• Zero complexity -- No mailbox, no storage, no email parsing libraries in your app. MailLaser handles SMTP and delivers clean JSON.
• Deploy in minutes -- One Docker command or a single binary. Configure with two required environment variables and you are running.
• Authenticated senders -- Optional SPF, DKIM, and DMARC validation rejects spoofed mail at the SMTP layer or annotates the payload with the authentication outcome.
• Policy-based authorization -- Cedar policies decide which senders may reach which recipients and which attachments are permitted, all in a declarative policy file.
• Attachment pass-through -- Deliver attachments inline as base64 in the JSON payload or upload them to an S3-compatible bucket (AWS, MinIO, R2, Wasabi) and include the URL.
• Signed webhooks -- Optional HMAC-SHA256 request signing lets your endpoint verify each payload came from MailLaser and was not modified in transit.
• Built-in resilience -- Automatic retries with exponential backoff and a circuit breaker protect your webhook from cascading failures.
• Lightweight -- A statically linked Rust binary around 17 MB on a scratch Docker image. No runtime dependencies.

Read the full documentation for installation options, configuration reference, webhook payload details, and production deployment guides.

Quick start

Start MailLaser with Docker. Replace the two -e values with your target email address and webhook URL:

docker run -d \
  --name mail-laser \
  -p 2525:2525 \
  -p 8080:8080 \
  -e MAIL_LASER_TARGET_EMAILS="alerts@example.com" \
  -e MAIL_LASER_WEBHOOK_URL="https://your-api.com/webhook" \
  ghcr.io/govcraft/mail-laser:3

Send a test email with swaks:

swaks \
  --to alerts@example.com \
  --from test@sender.com \
  --server localhost:2525 \
  --header "Subject: Test from swaks" \
  --body "Hello from MailLaser!"

Your webhook receives a JSON POST:

{
  "sender": "test@sender.com",
  "recipient": "alerts@example.com",
  "subject": "Test from swaks",
  "body": "Hello from MailLaser!"
}

Other installation methods (pre-compiled binaries, Nix, building from source) are covered in the Installation guide.

How it works

1. Listen -- Accept SMTP connections on port 2525 (configurable), with a per-IP connection cap that bounds noisy clients.
2. Authenticate -- Optionally run SPF, DKIM, and DMARC checks against the sender. Enforce mode rejects spoofed mail with 550 5.7.1; monitor mode annotates the payload with the outcome for downstream consumers.
3. Authorize -- Evaluate a Cedar policy against the sender, the recipient, and each attachment. Denials reject the transaction at end-of-DATA.
4. Parse -- Extract sender, recipient, subject, plain text body, optional HTML body, headers, and MIME attachments.
5. Forward -- POST the payload as JSON to your webhook, optionally HMAC-signed. Attachments ride inline or upload to S3 first. Automatic retries and a circuit breaker protect the endpoint.

A separate health check server on port 8080 responds to GET /health for monitoring integration. See the Architecture page for the full actor-based design.

Documentation

Visit govcraft.github.io/mail-laser for comprehensive guides:

• Installation -- Docker, binaries, Nix, or build from source
• Configuration -- Environment variables, .env files, and defaults
• Docker deployment -- Compose, Kubernetes, and production setup
• Webhook delivery -- JSON payload format and delivery behavior
• Webhook signing -- HMAC-SHA256 verification with Node.js and Python recipes
• Authorization -- Cedar policy basics and sender/attachment rules
• Attachments -- Inline and S3 delivery modes, size caps, and payload schema
• DMARC validation -- SPF, DKIM, and DMARC modes with rollout guidance
• API reference -- Full payload schema and SMTP command reference
• Header passthrough -- Forward custom email headers to your webhook
• Resilience -- Retry backoff and circuit breaker details
• DNS and network setup -- MX records, firewalls, and port forwarding
• Health check -- Monitoring and orchestration integration
• Testing -- swaks examples and the built-in test suite
• Upgrading to v3 -- Breaking changes and migration steps from v2

Development

cargo build           # Debug build
cargo test --lib      # Unit tests (no Docker needed)
cargo test            # Full suite (integration tests require Docker)
cargo build --release # Optimized release build

Integration tests under tests/ use testcontainers to spin up MockServer and MinIO. A running Docker daemon is required. The first run pulls the MinIO image (~150 MB); allow ~30s extra.

See Architecture for the module structure and design decisions.

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. Push to your branch and open a pull request

License

MIT -- see LICENSE for details.

Sponsor

Govcraft is a one-person shop -- no corporate backing, no investors, just me building useful tools. If this project helps you, sponsoring keeps the work going.