Quick Start

Get MXHook running locally in under 5 minutes using Docker Compose.

Prerequisites

• Docker and Docker Compose installed
• A terminal

Start MXHook

Clone the repository and start the services:

git clone https://github.com/mxhook/mxhook.git
cd mxhook
docker compose up

This starts:

• SMTP server on port 2525
• REST API on port 8080
• PostgreSQL on port 5432

Create a Domain

Register the domain you want to receive email on:

curl -X POST http://localhost:8080/domains \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"name": "yourdomain.com"}'

{
  "id": "d-1710806400",
  "name": "yourdomain.com",
  "created_at": "2025-03-19T00:00:00Z"
}

Create a Route

Define where emails should be delivered:

curl -X POST http://localhost:8080/routes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "domain": "yourdomain.com",
    "recipient_pattern": "*@yourdomain.com",
    "webhook_url": "https://yourapp.com/webhook",
    "webhook_secret": "your-signing-secret"
  }'

The wildcard pattern *@yourdomain.com catches all recipients on that domain.

Send a Test Email

Use Python's built-in SMTP library to send a test message:

import smtplib
from email.mime.text import MIMEText

msg = MIMEText('Hello from MXHook!')
msg['Subject'] = 'Test Email'
msg['From'] = 'sender@example.com'
msg['To'] = 'test@yourdomain.com'

with smtplib.SMTP('localhost', 2525) as s:
    s.sendmail('sender@example.com', ['test@yourdomain.com'], msg.as_string())

Receive the Webhook

MXHook parses the email and POSTs a JSON payload to your webhook URL:

{
  "message_id": "<unique-id@example.com>",
  "from": "sender@example.com",
  "to": ["test@yourdomain.com"],
  "subject": "Test Email",
  "text_body": "Hello from MXHook!",
  "html_body": "",
  "headers": {
    "From": "sender@example.com",
    "To": "test@yourdomain.com",
    "Subject": "Test Email",
    "Date": "Wed, 19 Mar 2025 00:00:00 +0000"
  },
  "attachments": []
}

The request includes an X-MXHook-Signature header for verification.

Next Steps

• Configure MX records to receive real email
• Set up routing rules for advanced matching
• Verify webhooks in your application
• Deploy to production with Docker