mux

mux — ɳSelf documentation.

Mux Plugin

AI-powered email and webhook pipeline with priority routing and dead-letter queue. Pro plugin.

Requires: Basic license tier or higher. nself license set nself_pro_...

Install

nself license set nself_pro_xxxxx...
nself plugin install mux

What It Does

Routes incoming emails and webhook events through an AI classification pipeline. Assigns priority scores, routes messages to handlers based on rules, and auto-replies using configurable templates. Failed deliveries land in a dead-letter queue for manual review. Uses the ai plugin for classification and intent detection.

Dependencies

Requires Redis (REDIS_ENABLED=true). Optionally uses the ai plugin for AI classification.

Configuration

Env Var	Default	Description
`MUX_PORT`	`3711`	Mux service port
`MUX_IMAP_HOST`	none	IMAP server for email ingestion
`MUX_IMAP_USER`	none	IMAP username
`MUX_IMAP_PASS`	none	IMAP password
`MUX_SMTP_HOST`	none	SMTP server for auto-replies
`MUX_AI_ENABLED`	`true`	Use AI plugin for classification
`MUX_DLQ_RETENTION`	`30`	Days to retain failed messages

Ports

Port	Purpose
3711	Mux REST API and webhook receiver

Database Tables

6 tables added to your Postgres database:

np_mux_messages: ingested messages
np_mux_routes: routing rules
np_mux_handlers: message handlers
np_mux_replies: auto-reply templates
np_mux_dlq: dead-letter queue
np_mux_audit: processing audit log

Nginx Routes

Route	Target
`/mux/webhook`	Incoming webhook receiver
`/mux/`	Mux management API

Stateful Workflows

Multi-step email workflows with persisted state. Set MUX_WORKFLOWS_ENABLED=true to activate.

Define a YAML state machine (place under rules/workflows/) and reference it from a mux rule:

id: support-ticket
description: Support ticket lifecycle
initial: awaiting_reply
ttl: 30d

states:
  awaiting_reply:
    timeout: 2d
    on_enter:
      - type: email
        params:
          to: "{sender}"
          template: support-ack
    transitions:
      - event: reply_received
        target: resolved
      - event: timeout
        target: follow_up_sent
        actions:
          - type: email
            params:
              to: "{sender}"
              template: support-follow-up

  follow_up_sent:
    timeout: 5d
    transitions:
      - event: reply_received
        target: resolved
      - event: timeout
        target: escalated

  resolved:
    terminal: true

  escalated:
    terminal: true
    on_enter:
      - type: notify
        params:
          channel: slack
          message: "Ticket {thread_id} escalated"

Three example workflows ship with the plugin:

support-ticket: acknowledgement, follow-up, escalation
trial-onboarding: welcome, day-3 tip, day-7 upgrade nudge
subscription-renewal: 14-day reminder, 7-day final, lapse notification

Workflow CLI Commands

nself mux workflows list
nself mux workflows status <workflow_id> <thread_id>
nself mux workflows inject <workflow_id> <thread_id> <event>
nself mux workflows cancel <workflow_id> <thread_id>

Workflow Config

Env Var	Default	Description
`MUX_WORKFLOWS_ENABLED`	`false`	Opt-in feature flag
`MUX_WORKFLOW_CRON_INTERVAL`	`15m`	Timeout cron frequency
`MUX_WORKFLOW_FOLLOW_UP_POLL_INTERVAL`	`1m`	Follow-up queue poll frequency
`MUX_WORKFLOW_DEFAULT_TTL`	`720h`	Instance TTL (30 days)

Workflow Database Tables

Four tables are added by the workflow engine:

np_mux_workflows: workflow definitions
np_mux_workflow_instances: per-thread state
np_mux_workflow_events: audit log
np_mux_workflow_followups: scheduled follow-up queue