Routing Rules

Routes define how inbound emails are matched and where they're delivered. Each route connects a recipient pattern to a webhook URL.

Create a Route

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"
  }'

Pattern Types

Exact Match

Matches a single email address:

{
  "recipient_pattern": "[email protected]",
  "webhook_url": "https://yourapp.com/support"
}

Only [email protected] triggers this route.

Wildcard

Matches any recipient on a domain:

{
  "recipient_pattern": "*@yourdomain.com",
  "webhook_url": "https://yourapp.com/catchall"
}

Matches [email protected], [email protected], etc.

Plus-Addressing

MXHook automatically strips plus tags before matching. An email to [email protected] matches a route for [email protected].

This is useful for categorization without creating new routes:

• [email protected] → matches [email protected]
• [email protected] → matches [email protected]

The full original address (with the plus tag) is still included in the webhook payload.

Route Priority

Routes are evaluated in priority order. The first matching route wins. More specific patterns (exact match) should have higher priority than catch-all patterns (wildcard).

Webhook Secret

The webhook_secret field is optional. When set, MXHook signs every payload with HMAC-SHA256 and includes the signature in the X-MXHook-Signature header. See Webhook Verification for details.

List Routes

curl http://localhost:8080/routes \
  -H "X-API-Key: your-api-key"

Delete a Route

curl -X DELETE http://localhost:8080/routes/r-1710806400 \
  -H "X-API-Key: your-api-key"

Enterprise: Advanced Routing

With the enterprise edition, you get additional routing capabilities:

• Regex patterns — match recipients with regular expressions (e.g., ^ticket-\[email protected]$)
• Header conditions — route based on email header values (e.g., route based on X-Priority or List-Id)

See Advanced Routing for details.