Introduction
MXHook is an open-source inbound email webhook platform. It runs an SMTP server that accepts incoming email, parses the content, and delivers structured JSON payloads to your application via webhooks.
Why MXHook?
Most applications that need to process inbound email rely on third-party services like Mailgun Routes, SendGrid Inbound Parse, or Postmark Inbound. These work, but they come with trade-offs:
- Data leaves your network — email content is processed on someone else's infrastructure
- Vendor lock-in — your routing logic lives in a third-party dashboard
- Cost scales with volume — pricing is per-message, which adds up fast
- Limited control — retry behavior, routing rules, and payload format are dictated by the provider
MXHook gives you the same capabilities on your own infrastructure.
How It Works
Incoming Email → SMTP Server → Parse → Route → Webhook POST
↓ ↓
PostgreSQL Your Application- Receive — MXHook runs an SMTP server. Point your domain's MX records at it.
- Parse — Incoming email is parsed into structured data: headers, body (text and HTML), attachments, and metadata.
- Route — The routing engine matches the recipient against your configured rules to determine the destination webhook.
- Deliver — A JSON payload is POSTed to your webhook URL, signed with HMAC-SHA256 for verification.
Key Features
| Feature | Description |
|---|---|
| SMTP Server | RFC 5321 compliant, configurable limits |
| Email Parsing | Headers, text/HTML body, attachments via enmime |
| Pattern Routing | Exact match, wildcard, plus-addressing |
| Webhook Delivery | JSON payloads with exponential backoff retry |
| HMAC Signing | Per-route X-MXHook-Signature header |
| Dead Letter Queue | Captures failed deliveries for inspection |
| Message Replay | Re-deliver any message on demand |
| REST API | Manage domains, routes, and messages programmatically |
| CLI | Full command-line interface for operations |
| Raw Storage | .eml files preserved for compliance and auditing |
Enterprise Features
MXHook's enterprise edition (licensed under BSL 1.1, converting to Apache 2.0 after 2 years) adds:
- Regex recipient patterns — match recipients with regular expressions
- Header-based conditions — route based on email header values
Next Steps
- Quick Start — get MXHook running in under 5 minutes
- Concepts — understand domains, routes, and the message lifecycle
- API Reference — manage everything programmatically