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": "support@yourdomain.com",
  "webhook_url": "https://yourapp.com/support"
}

Only support@yourdomain.com triggers this route.

Wildcard

Matches any recipient on a domain:

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

Matches alice@yourdomain.com, bob@yourdomain.com, etc.

Plus-Addressing

MXHook automatically strips plus tags before matching. An email to user+tag@yourdomain.com matches a route for user@yourdomain.com.

This is useful for categorization without creating new routes:

• support+billing@yourdomain.com → matches support@yourdomain.com
• support+bug@yourdomain.com → matches support@yourdomain.com

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-\d+@yourdomain.com$)
• Header conditions — route based on email header values (e.g., route based on X-Priority or List-Id)

See Advanced Routing for details.