Ricardo CabralI'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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
I'm building this in public now, so the roadmap is open. Here's what I'm thinking about:
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. 🧶