A rule-based message routing engine for your nself backend — receive email, webhooks, SMS, or Telegram messages, then automatically forward, classify, store, notify, or reply using a YAML pipeline with 17 action types and optional AI classification.
nself-mux is part of the ɳClaw bundle. AI-powered actions (ai_classify, ai_summarize, ai_extract, ai_reply) require nself-ai to also be installed. Set your key with nself license set nself_pro_... before installing.
nself license set nself_pro_...
nself plugin install mux
nself build
nself start| Variable | Required | Default | Description |
|---|---|---|---|
PLUGIN_MUX_RULES_PATH | Yes | — | Path to your mux-rules.yaml rule definitions file |
PLUGIN_MUX_WEBHOOK_SECRET | No | — | HMAC secret for verifying inbound webhook signatures |
PLUGIN_MUX_MAX_RUNS_HISTORY | No | 1000 | How many recent rule execution records to retain in np_mux.runs |
PLUGIN_MUX_DEFAULT_SMTP_FROM | No | — | Default "from" address for forward and reply email actions |
PLUGIN_MUX_TELEGRAM_TOKEN | If using Telegram channel | — | Telegram Bot API token for receiving/sending Telegram messages |
PLUGIN_MUX_TWILIO_ACCOUNT_SID | If using SMS channel | — | Twilio Account SID for SMS inbound/outbound |
PLUGIN_MUX_TWILIO_AUTH_TOKEN | If using SMS channel | — | Twilio Auth Token |
PLUGIN_MUX_TWILIO_FROM_NUMBER | If sending SMS | — | Twilio phone number to send SMS from (E.164 format) |
Define routing rules in mux-rules.yaml and set PLUGIN_MUX_RULES_PATH in your .env:
rules:
- name: forward-support-email
when:
channel: email
to: support@example.com
actions:
- type: forward
to: team@example.com
- type: store
table: support_tickets
- name: notify-on-payment
when:
channel: webhook
source: stripe
event: payment_intent.succeeded
actions:
- type: notify
plugin: nself-notify
user_id: "{{ payload.metadata.user_id }}"
title: "Payment received"
body: "Thank you for your payment of ${{ payload.amount_received / 100 }}"
- name: classify-and-route
when:
channel: email
actions:
- type: ai_classify # requires nself-ai
categories: [support, sales, billing, spam]
- type: forward
to: "{{ classification }}@example.com"| Channel | How messages arrive | Requires |
|---|---|---|
email | Inbound SMTP forwarded to /mux/inbound/email | Mail server webhook config |
webhook | Any HTTP POST to /mux/inbound/webhook/:source | Register URL with the sending service |
telegram | Telegram bot webhook registered via BotFather | PLUGIN_MUX_TELEGRAM_TOKEN |
sms | Twilio SMS webhook to /mux/inbound/sms | Twilio credentials |
custom | POST to /mux/inbound/custom from your application code | Nothing |
| Action type | Description |
|---|---|
forward | Forward message to an email address |
reply | Send a reply to the message sender |
store | Insert message into a PostgreSQL table |
webhook | POST payload to an HTTP endpoint |
notify | Trigger a push notification via nself-notify |
label | Apply a label to a Gmail message (requires nself-google) |
archive | Archive a Gmail message (requires nself-google) |
transform | Apply a Jinja2 template to reshape the payload |
filter | Drop the message (stop processing) if a condition matches |
delay | Pause processing for N seconds before the next action |
log | Write a structured log entry — useful for debugging rules |
set_var | Set a variable available to subsequent actions in the same run |
conditional | Branch to different action sets based on a runtime condition |
ai_classify | Classify message into categories using nself-ai (requires nself-ai) |
ai_summarize | Generate a summary of message content using nself-ai |
ai_extract | Extract structured fields from unstructured text using nself-ai |
ai_reply | Draft and send an AI-generated reply using nself-ai |
| Endpoint | Method | Description |
|---|---|---|
/mux/inbound/email | POST | Receive inbound email (webhook from mail server or SMTP relay) |
/mux/inbound/webhook/:source | POST | Receive a webhook from any named source (e.g., :source=stripe) |
/mux/inbound/sms | POST | Receive inbound SMS from Twilio |
/mux/inbound/custom | POST | Submit a message from your application code |
/mux/rules | GET | List loaded rules with match counts and last-triggered timestamps |
/mux/runs | GET | View recent rule execution history with action outcomes |
/health | GET | Plugin health check |
nself-mux stores all routing activity in the np_mux schema. Hasura auto-tracks these tables for GraphQL access.
| Table | Key Columns | Purpose |
|---|---|---|
np_mux.messages | id, channel, source, from_addr, to_addr, subject, body, raw_payload, received_at | Every inbound message received by any channel |
np_mux.runs | id, message_id, rule_name, matched, actions_executed, duration_ms, error, created_at | Execution record for every rule evaluated against a message |
np_mux.action_outcomes | id, run_id, action_type, status, result, created_at | Per-action result within a run (success, error, skipped) |
np_mux.rule_stats | rule_name, match_count, last_matched_at, error_count | Aggregated stats per rule — updated after each run |
| Event | Trigger | Payload Includes |
|---|---|---|
mux.message.received | Any inbound message arrives | message_id, channel, source |
mux.rule.matched | A rule condition is satisfied | rule_name, message_id, channel |
mux.rule.error | An action within a rule fails | rule_name, action_type, error |
mux.message.unmatched | A message matched no rules | message_id, channel, rules_evaluated |
| Option | Data ownership | AI actions | Self-hosted | Cost |
|---|---|---|---|---|
| nself-mux | Full — Postgres on your VPS | Yes — via nself-ai | Yes | $0.99/mo |
| Zapier | Zapier cloud — no control | Yes via OpenAI step | No | $19.99–$49/mo |
| Make (Integromat) | Make cloud | Yes via AI modules | No | $9–$29/mo |
| n8n (self-hosted) | Your server | Yes via nodes | Yes | Free OSS / $20+/mo cloud |
Check /mux/runs for the last few runs — the matched field and actions_executed show exactly what happened. The log action type is useful for tracing variable values mid-rule during development.
Ensure the webhook source label in the URL (/mux/inbound/webhook/stripe) matches the source: field in your rule's when: block. Source labels are case-sensitive.
Verify nself-ai is installed and running: nself plugin status ai. Check PLUGIN_AI_DEFAULT_PROVIDER is set. The ai_classify action sends a prompt to nself-ai and will fail if nself-ai is unhealthy.
The forward and reply actions use the nself mail service (SMTP). Ensure PLUGIN_MUX_DEFAULT_SMTP_FROM is set to a verified sender address and that your mail service is running (nself service status mail).
nself plugin remove muxnself-claw depends on nself-mux for its email pipeline. Remove nself-claw before removing nself-mux, or use nself plugin remove mux --force.
notify action)Port: 3711 | Bundle: ɳClaw ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.1.0