Scalable. Reliable. Extensible

Open-source plugin-based notification orchestration engine for developers who value control

Features • Architecture • API Server • Quick Start • Dashboard • Website • Documentation

---

SimpleNS is a self-hosted notification orchestration engine that manages delivery workflows—retries, scheduling, crash recovery, and scaling—while delegating the actual sending to plugins. Build your own providers or use community plugins to support any channel: Email, SMS, WhatsApp, Push, and beyond.

---

Why SimpleNS?

❌ The Problem	✅ How SimpleNS Solves It
Locked into a single notification provider	Plugin architecture — swap providers without code changes
Notifications fail silently	Exponential backoff retries with configurable limits
Crashes leave messages stuck	Crash recovery service detects & rescues orphaned notifications
Single point of failure	Horizontally scalable workers and processors
Complex scheduling logic	Built-in scheduled delivery with Redis-backed queues
Different APIs for each channel	Unified API for all notification channels

---

Key Features

• 🔌 Plugin-Based Delivery — Delegate sending to any provider plugin
• 🔄 Exponential Backoff Retries — Automatic retry with increasing delays
• 🛡️ Crash Recovery — Detect and rescue orphaned notifications
• ⏰ Scheduled Delivery — Queue notifications for future delivery
• 📈 Horizontal Scaling — Scale processors independently per channel
• 📡 Multi-Channel Support — Email, WhatsApp, SMS, Push via plugins
• 🚦 Rate Limiting — Per-provider token bucket algorithm
• 🔔 Webhook Callbacks — Real-time delivery status updates
• 📊 Admin Dashboard — Monitor, search, and retry notifications
• 🔔 Admin Alert Channels — Receive system health alerts via Discord, Telegram, and more
• 📝 Notification Templates — Create, edit, and manage reusable notification templates with live preview
• 🤖 MCP Server — Native Model Context Protocol server for AI agent integration
• 📋 Observability — Centralized logging with Grafana + Loki

---

AI Agent Integration (MCP)

SimpleNS includes a native Model Context Protocol (MCP) server (@simplens/mcp) that allows AI assistants like Github Copilot (VS code), Antigravity and OpenAI Codex to interact directly with your notification infrastructure.

AI agents can securely connect to your SimpleNS instance to:

• Send Notifications — Dispatch individual or batch notifications using templates or inline content
• Explore Schemas — Dynamically discover available channels, providers, and required payload fields
• Monitor Health — Check system alerts and investigate failed deliveries
• Retry Failed Events — Programmatically identify and retry failed notification events

Running the MCP Server

Start the server without installation:

# Run in streamable-http mode
npx -y @simplens/mcp

# Run in stdio mode
npx -y @simlpens/mcp --stdio

(Supports both streamable-http and stdio transports)

Read the documentation here to get started with SimpleNS MCP

---

Architecture

Component	Description
API Server	Central REST API engine providing ingestion, notification history, templates, alerts, metrics, and plugin schemas
Background Worker	Polls outbox, publishes to Kafka, consumes status updates
Unified Processor	Plugin-based notification delivery with rate limiting
Delayed Processor	Handles scheduled notifications via Redis ZSET queue
Recovery Service	Detects stuck notifications and reschedules them
Admin Dashboard	Decoupled Next.js client UI that interfaces exclusively through the API Server

Decoupled API-First Architecture

SimpleNS is built around a strictly decoupled, API-first model:

• Self-Sufficient API Server: The API Server is the single source of truth for all notification operations, database persistence (MongoDB), outbox streaming (Kafka), analytics, and plugin metadata. It can run 100% headless in production without the dashboard.
• Thin Dashboard Client: The Next.js Admin Dashboard holds no backend business logic or direct database connections. Every user action—querying events, editing templates, resolving alerts, and configuring channels—is dispatched directly to the API Server via standard REST endpoints.
• Client Agnostic: Because all capabilities are exposed via the API Server, you can drive SimpleNS through the official dashboard, your own custom internal tools, automation scripts (via our Bruno API Collection), or AI agents (via the native MCP server).

Plugin System

SimpleNS Core handles orchestration, plugins handle delivery.

Plugins can be installed directly from the dashboard, via API and MCP server

Building Custom Plugins

The @simplens/create-simplens-plugin CLI scaffolds a plugin project:

npx @simplens/create-simplens-plugin

This generates the boilerplate so you only write the delivery logic:

import { SimpleNSProvider, ProviderManifest } from '@simplens/sdk';

class MyProvider implements SimpleNSProvider {
  readonly manifest: ProviderManifest = {
    name: 'my-provider',
    channel: 'email',
    requiredCredentials: ['API_KEY'],
    // ...
  };
  
  async send(notification) {
    // Your delivery logic
    return { success: true, messageId: 'msg-123' };
  }
}

---

Quick Start

Prerequisites

• Docker and Docker Compose

Installation

Get SimpleNS running in under a minute with a single command:

Linux:

curl -fsSL https://simplens.in/api/install/linux | bash

Windows (PowerShell as Administrator):

irm https://simplens.in/api/install/windows | iex

npm:

npx @simplens/onboard

The installer will automatically pull Docker images, configure your environment, set up plugin configuration, and start all services.

Verify Installation

curl http://localhost:3000/api/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Send Your First Notification

Using the Dashboard (recommended):

1. Open http://localhost:3002
2. At startup, it lets you to create an admin account, install official and community plugins, setup their corresponding providers and credentials. Then go to dashboard home and create an API key for the external services to access the SimpleNS API server.
3. Navigate to Send, select a channel/provider, fill in the fields, and click Send Notification

Using cURL:

curl -X POST http://localhost:3000/api/notification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-API-KEY>" \
  -d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "55283667-1f58-467d-86a1-47f7f0e059f2",
    "channel": ["mock"],
    "recipient": {
      "user_id": "user123"
    },
    "content": {
      "mock": {
        "message": "Hello from SimpleNS!"
      }
    }
  }'

Tip: Each provider's recipient and content schemas can vary. Use the Payload Studio in the admin dashboard to get the exact schema.

Check Notification Status

1. Go to Events page in the dashboard
2. Search for your notification by ID
3. Check status: pending → processing → delivered

Accessing Services

Service	URL	Description
API Server	http://localhost:3000	Notification API
Admin Dashboard	http://localhost:3002	Monitoring & management
Grafana	http://localhost:3001	Log visualization

For production deployments, see the Self-Hosting Guide which covers distributed deployments, cloud infrastructure integration, and security hardening.

---

API-First Architecture & Routes

SimpleNS provides a comprehensive, authenticated REST API that powers both external clients and the Admin Dashboard. Because the core engine is decoupled from the UI, every action possible in the dashboard can be automated or integrated via REST endpoints.

📖 Interactive API Collection: A complete Bruno collection is available in /api-docs with preconfigured environments and sample requests for all endpoints.

---

Admin Dashboard

The Admin Dashboard is an independent Next.js application built strictly as a thin presentation client:

• 💡 Zero Backend Implementations: The dashboard contains no database access, worker logic, or business rules. It depends entirely on the SimpleNS Core API Server.
• 🔌 API Driven: Every action—from rendering stats to triggering retries and saving templates—dispatches directly to the REST API routes.
• 🏢 Headless Ready: Because the dashboard is fully decoupled, you can operate SimpleNS headless in backend environments, deploy custom frontends, or interact via CI/CD and AI tools without running the dashboard.

Key Dashboard Features:

• Dashboard Home — Status overview powered by /api/dashboard/stats
• Channel Cards — Visual status for each configured delivery channel
• Events Explorer — Paginated event table with live filtering via /api/notifications
• Failed Events — Dedicated view with one-click retries via /api/notifications/:id/retry
• Alerts — System health and orphaned recovery alerts via /api/alerts
• Analytics — 24h, 7d, and 30d time-series trends via /api/dashboard/trends
• Plugins — Manage official, community and custom plugins, setup providers with credentials and setup channel routing with an array of fallback providers
• Payload Studio — Interactive schema explorer for constructing valid payloads
• Admin Alert Channels — Live test and configure Discord/Telegram alerts via /api/admin-channels
• Notification Templates — Full lifecycle management and live preview via /api/templates
• API Key - Create and manage multiple API keys, track their usage and so on

---

License

MIT License — see LICENSE for details.

---

_{Built with ❤️ for developers who need reliable notifications}