mail-laser

KO | EN

gitlite — search

#javascript #python #react #golang #android #rust #linux #docker #macos #awesome #kubernetes #vue #pytorch #security

(★ 10)

Lightweight server that forwards emails (sender, subject, text, optional HTML) as JSON via POST to a webhook URL. Ideal for email integration with web services & automation. Supports Docker, binaries, source.

mail-laser Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://govcraft.github.io/mail-laser)** 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:

```shell
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](https://www.jetmore.org/john/code/swaks/):

```shell
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:

```json
{
  "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](https://govcraft.github.io/mail-laser/docs/installation).

## 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](https://govcraft.github.io/mail-laser/docs/architecture) page for the full actor-based design.

## Documentation

Visit **[govcraft.github.io/mail-laser](https://govcraft.github.io/mail-laser)** for comprehensive guides:

- [Installation](https://govcraft.github.io/mail-laser/docs/installation) -- Docker, binaries, Nix, or build from source
- [Configuration](https://govcraft.github.io/mail-laser/docs/configuration) -- Environment variables, `.env` files, and defaults
- [Docker deployment](https://govcraft.github.io/mail-laser/docs/docker) -- Compose, Kubernetes, and production setup
- [Webhook delivery](https://govcraft.github.io/mail-laser/docs/webhook-delivery) -- JSON payload format and delivery behavior
- [Webhook signing](https://govcraft.github.io/mail-laser/docs/webhook-signing) -- HMAC-SHA256 verification with Node.js and Python recipes
- [Authorization](https://govcraft.github.io/mail-laser/docs/authorization) -- Cedar policy basics and sender/attachment rules
- [Attachments](https://govcraft.github.io/mail-laser/docs/attachments) -- Inline and S3 delivery modes, size caps, and payload schema
- [DMARC validation](https://govcraft.github.io/mail-laser/docs/dmarc) -- SPF, DKIM, and DMARC modes with rollout guidance
- [API reference](https://govcraft.github.io/mail-laser/docs/api-reference) -- Full payload schema and SMTP command reference
- [Header passthrough](https://govcraft.github.io/mail-laser/docs/header-passthrough) -- Forward custom email headers to your webhook
- [Resilience](https://govcraft.github.io/mail-laser/docs/resilience) -- Retry backoff and circuit breaker details
- [DNS and network setup](https://govcraft.github.io/mail-laser/docs/dns-network-setup) -- MX records, firewalls, and port forwarding
- [Health check](https://govcraft.github.io/mail-laser/docs/health-check) -- Monitoring and orchestration integration
- [Testing](https://govcraft.github.io/mail-laser/docs/testing) -- swaks examples and the built-in test suite
- [Upgrading to v3](https://govcraft.github.io/mail-laser/docs/upgrading-to-v3) -- Breaking changes and migration steps from v2

## Development

```shell
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](https://github.com/testcontainers/testcontainers-rs) 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](https://govcraft.github.io/mail-laser/docs/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](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](https://github.com/sponsors/Govcraft) keeps the work going.

[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-%E2%9D%A4-%23db61a2?logo=GitHub)](https://github.com/sponsors/Govcraft)

mail-laser

mail-laser Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

mail-laser

mail-laser Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README