nornweave-api

NornWeave API

NornWeave is a self-hosted, open-source Inbox-as-a-Service API for AI agents. It provides a stateful email layer (Inboxes, Threads, History) and an intelligent layer (Markdown parsing, Semantic Search) optimized for LLMs.

Installation

# Python client
pip install nornweave-client

Setup

from nornweave_client import NornWeave

# Sync client
client = NornWeave(base_url="http://localhost:8000")

# Or async client
from nornweave_client import AsyncNornWeave
client = AsyncNornWeave(base_url="http://localhost:8000")

Inboxes

Create scalable inboxes on-demand. Each inbox has a unique email address based on your configured domain.

# Create inbox with username and display name
inbox = client.inboxes.create(
    name="Support",
    email_username="support"
)
# Result: [email protected]

# List all inboxes (paginated)
for inbox in client.inboxes.list():
    print(inbox.email_address)

# Get inbox by ID
inbox = client.inboxes.get(inbox_id="inbox-uuid")

# Delete inbox
client.inboxes.delete(inbox_id="inbox-uuid")

Async Usage

# Create inbox
inbox = await client.inboxes.create(
    name="Support",
    email_username="support"
)

# List inboxes with async iteration
async for inbox in client.inboxes.list():
    print(inbox.email_address)

# Get and delete
inbox = await client.inboxes.get(inbox_id="inbox-uuid")
await client.inboxes.delete(inbox_id="inbox-uuid")

Messages

Send and retrieve messages. NornWeave automatically converts content to Markdown for LLM consumption.

# Send message (body is Markdown)
response = client.messages.send(
    inbox_id="inbox-uuid",
    to=["[email protected]"],
    subject="Hello from my AI agent",
    body="# Welcome\n\nThis is a **markdown** email."
)
print(f"Message ID: {response.id}, Status: {response.status}")

# Reply to existing thread
response = client.messages.send(
    inbox_id="inbox-uuid",
    to=["[email protected]"],
    subject="Re: Hello",
    body="Thanks for your message!",
    reply_to_thread_id="thread-uuid"
)

# List messages for an inbox (paginated)
for message in client.messages.list(inbox_id="inbox-uuid"):
    print(f"[{message.direction}] {message.content_clean[:100]}")

# Get single message by ID
message = client.messages.get(message_id="message-uuid")
print(message.content_clean)  # LLM-ready markdown content