Ricardo Cabral

Posted on Feb 4

Introducing NornWeave: Giving AI Agents Their Own Email Inbox

#opensource #ai #agents #python

I've been quietly building something for the past few months, and this week I decided to take the leap: NornWeave is now open source and being built in public.

If you're building AI agents that need to communicate via email, I'd love for you to check it out.

The Problem I Kept Running Into

Every time I tried to give an AI agent the ability to read and send email, I hit the same wall. Standard email APIs are built for transactional sending—fire off a welcome email, send a receipt, done. They're stateless by design.

But agents need context. They need to know:

"What did the customer say three messages ago?"
"Is this a new conversation or part of an ongoing thread?"
"What's the actual content without all the HTML cruft and signature blocks?"

I found myself writing the same threading logic, the same HTML-to-text conversion, the same webhook handlers over and over. So I built NornWeave to solve this once and share it with everyone facing the same challenge.

What is NornWeave?

NornWeave is an open-source, self-hosted Inbox-as-a-Service API built specifically for AI agents. It adds two layers on top of raw email:

A Stateful Layer — Virtual inboxes, conversation threads, full message history
An Intelligent Layer — HTML→Markdown parsing, automatic threading, semantic search

Your agents consume email through a clean REST API or directly via MCP (Model Context Protocol) instead of wrestling with raw webhooks and HTML soup.

The Highlights

📬 Virtual Inboxes for Your Agents

Each agent gets its own email address. Create as many as you need:

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

No more sharing a single inbox and filtering by subject line. Each agent owns its conversations.

🧵 Automatic Threading

NornWeave groups related messages into threads automatically using email headers (In-Reply-To, References, Message-ID). When you fetch a thread, you get an LLM-friendly format:

{
  "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": "..." }
  ]
}

No more "parse the email chain and figure out who said what." It's already done.

🧹 Clean Content, No Cruft

Incoming HTML emails get converted to clean Markdown. Signatures, disclaimers, and quoted reply blocks are stripped out. Your agent sees the actual message, not the noise.

🔌 MCP Integration

This is where it gets fun. NornWeave exposes an MCP server that plugs directly into Claude, Cursor, and other MCP-compatible clients:

Tool	What it does
`create_inbox`	Provision a new email address
`send_email`	Send an email (auto-converts Markdown→HTML)
`search_email`	Find relevant messages
`wait_for_reply`	Block until a reply arrives (experimental)

Configure it in your MCP client:

{
  "mcpServers": {
    "nornweave": {
      "command": "nornweave-mcp",
      "args": ["--api-url", "http://localhost:8000"]
    }
  }
}

Now your agent can say "check my inbox" and actually do it.

📧 Works With Your Email Provider

NornWeave supports the providers you're already using:

Provider	Sending	Receiving
Mailgun	✅	✅
AWS SES	✅	✅
SendGrid	✅	✅
Resend	✅	✅

Just configure your webhook URL, and NornWeave handles the rest.

The Architecture (A Little Norse Mythology)

I named the components after Norse mythology because... honestly, I think it's fun, and the metaphor works surprisingly well.

In Norse mythology, the Norns (Urdr, Verdandi, and Skuld) dwell at the base of Yggdrasil, the World Tree, weaving the tapestry of fate. NornWeave does something similar:

Module	Name	Purpose
Storage Layer	Urdr (The Well)	PostgreSQL/SQLite adapters
Ingestion Engine	Verdandi (The Loom)	Webhook processing, HTML→Markdown, threading
Outbound Layer	Skuld (The Prophecy)	Email sending, rate limiting
API Gateway	Yggdrasil	FastAPI routes connecting everything
MCP Resources	Huginn (Thought Raven)	Read operations for AI agents
MCP Tools	Muninn (Memory Raven)	Write operations for AI agents

Raw email streams in like water from the well. The Loom weaves them into coherent threads. Your agents drink from a clean, structured source.

Getting Started

If you want to try it out:

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

# Copy environment config
cp .env.example .env

# Start with Docker
docker compose up -d

# Run migrations
docker compose exec api alembic upgrade head

Or if you prefer local development with uv:

make install-dev
make migrate
make dev

The full documentation is at nornweave.datacovey.com.

What's Next?

I'm building this in public now, so the roadmap is open. Here's what I'm thinking about:

Better attachment handling — PDFs and documents extracted to text for agent consumption
Scheduled sending — "Reply tomorrow at 9am"
Agent handoff patterns — Escalate from bot to human seamlessly
More vector search options — Beyond pgvector

But honestly? I want to hear what you need. If you're building agents that deal with email, what's the hardest part? What would make your life easier? Care to help build it?

NornWeave is licensed under Apache 2.0 and the repo is at github.com/DataCovey/nornweave.

Building in public is a bit scary, but also exciting. I've been heads-down on this for a while, and now I get to see if it resonates with other people solving similar problems.

If you're giving AI agents the ability to communicate via email, I hope NornWeave saves you some of the headaches I ran into. And if it doesn't quite fit your needs yet—tell me why. I'm listening.

Thanks for reading. Happy weaving. 🧶

DEV Community