NornWeave

"Laws they made there, and life allotted / To the sons of men, and set their fates."
- Voluspa (The Prophecy of the Seeress), Poetic Edda, Stanza 20

Open-source, self-hosted Inbox-as-a-Service API for AI Agents

Standard email APIs are stateless and built for transactional sending. NornWeave adds a stateful layer (Inboxes, Threads, History) and an intelligent layer (Markdown parsing, Semantic Search) to make email consumable by LLMs via REST or MCP.

In Norse mythology, the Norns (Urdr, Verdandi, and Skuld) dwell at the base of Yggdrasil, the World Tree. They weave the tapestry of fate for all beings. Similarly, NornWeave:

• Takes raw "water" (incoming email data streams)
• Weaves disconnected messages into coherent Threads (the Tapestry)
• Nourishes AI Agents with clean, structured context

• Virtual Inboxes: Create email addresses for your AI agents
• Webhook Ingestion: Receive emails from Mailgun, SES, SendGrid, Resend
• IMAP/SMTP: Poll existing mailboxes (IMAP) and send via SMTP for any provider or self-hosted server
• Persistent Storage: SQLite (default) or PostgreSQL with abstracted storage adapters
• Email Sending: Send replies through your configured provider

• Content Parsing: HTML to clean Markdown, cruft removal
• Threading: Automatic conversation grouping via email headers
• Thread Summarization: LLM-generated thread summaries (OpenAI, Anthropic, Gemini) for list views and token savings
• MCP Server: Connect directly to Claude, Cursor, and other MCP clients
• Attachment Processing: Extract text from PDFs and documents

• Semantic Search: Vector embeddings with pgvector
• Real-time Webhooks: Get notified of new messages
• Rate Limiting: Protect against runaway agents
• Multi-Tenancy: Organizations and projects

Try NornWeave with no config: demo mode gives you a local sandbox and a pre-configured inbox.

pip install nornweave[mcp]
nornweave api --demo

API: http://localhost:8000. Open /docs, call GET /v1/inboxes to get the demo inbox id, then use MCP (nornweave mcp) to send and list messages. When you're ready for real email, set a provider and domain (see below).

# Base (SQLite, Mailgun/SES/SendGrid/Resend)
pip install nornweave

# With IMAP/SMTP support
pip install nornweave[smtpimap]

# With PostgreSQL
pip install nornweave[postgres]

# With MCP server (recommended for agents)
pip install nornweave[mcp]

# Full
pip install nornweave[all]

Create a .env file and set your provider and domain:

# .env — for inbox creation with a real provider
EMAIL_PROVIDER=mailgun   # or ses, sendgrid, resend, imap-smtp
EMAIL_DOMAIN=mail.yourdomain.com
# ... plus provider-specific keys (see .env.example)

See Configuration for all settings.

nornweave api

Data is stored in ./nornweave.db (SQLite default).

# Clone the repository
git clone https://github.com/DataCovey/nornweave.git
cd nornweave

# Copy environment configuration and set EMAIL_DOMAIN + provider keys (see above)
cp .env.example .env

# Start the stack
docker compose up -d

# Run migrations (PostgreSQL only — SQLite tables are created automatically)
docker compose exec api alembic upgrade head

# Clone the repository
git clone https://github.com/DataCovey/nornweave.git
cd nornweave

# Install dependencies
make install-dev

# Copy environment configuration and set EMAIL_DOMAIN + provider keys (see above)
cp .env.example .env

# Run migrations (PostgreSQL only — SQLite tables are created automatically)
# make migrate

# Start the development server
make dev

curl -X POST http://localhost:8000/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Agent", "email_username": "support"}'

curl http://localhost:8000/v1/threads/th_123

Response (LLM-optimized):

{
  "id": "th_123",
  "subject": "Re: Pricing Question",
  "messages": [
    { "role": "user", "author": "bob@gmail.com", "content": "How much is it?", "timestamp": "..." },
    { "role": "assistant", "author": "agent@myco.com", "content": "$20/mo", "timestamp": "..." }
  ]
}

curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "ibx_555",
    "reply_to_thread_id": "th_123",
    "to": ["client@gmail.com"],
    "subject": "Re: Pricing Question",
    "body": "Thanks for your interest! Our pricing starts at $20/mo."
  }'

NornWeave exposes an MCP server for direct integration with Claude, Cursor, and other MCP-compatible clients.

pip install nornweave[mcp]

{
  "mcpServers": {
    "nornweave": {
      "command": "nornweave",
      "args": ["mcp"],
      "env": {
        "NORNWEAVE_API_URL": "http://localhost:8000"
      }
    }
  }
}

NornWeave uses a thematic architecture inspired by Norse mythology:

• Getting Started Guide
• API Reference
• Architecture Overview
• Provider Setup Guides

This is a monorepo:

We welcome contributions! Please see our Contributing Guide for details.

NornWeave is open-source software licensed under the Apache 2.0 License.

_{Image: "Nornorna spinner odet tradar vid Yggdrasil" by L. B. Hansen
Public Domain}