Introducing NornWeave: Giving AI Agents Their Own Email Inbox

Source: Dev.to

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:

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 are converted to clean Markdown. Signatures, disclaimers, and quoted reply blocks are stripped out, so your agent sees only the actual message.

🔌 MCP Integration

NornWeave exposes an MCP server that plugs directly into Claude, Cursor, and other MCP‑compatible clients.

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

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

The Architecture (A Little Norse Mythology)

I named the components after Norse mythology because it’s fun and the metaphor works surprisingly well.

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

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

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 9 am”
• 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? Feel free to help shape the project.

NornWeave is licensed under Apache 2.0 and the repo is at .

GitHub repository

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