Introducing NornWeave: Giving AI Agents Their Own Email Inbox

# opensource# ai# python# agents
Introducing NornWeave: Giving AI Agents Their Own Email InboxRicardo Cabral

I've been quietly building something for the past few months, and this week I decided to take the...

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:

  1. A Stateful Layer — Virtual inboxes, conversation threads, full message history
  2. 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"}'
Enter fullscreen mode Exit fullscreen mode

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": "..." }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Or if you prefer local development with uv:

make install-dev
make migrate
make dev
Enter fullscreen mode Exit fullscreen mode

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. 🧶