commune-cookbook

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/commune-mail/)
[![npm](https://img.shields.io/badge/npm-commune--ai-red)](https://www.npmjs.com/package/commune-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![LangChain](https://img.shields.io/badge/LangChain-compatible-green)](langchain/)
[![CrewAI](https://img.shields.io/badge/CrewAI-compatible-orange)](crewai/)
[![MCP](https://img.shields.io/badge/MCP-server-purple)](mcp-server/)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-skills-orange)](openclaw-email-quickstart/)

# Email for AI Agents

**Give your AI agent a real email address. Production-ready examples for LangChain, CrewAI, OpenAI Agents SDK, Claude, MCP, OpenClaw, and agent-to-agent networks. Powered by [Commune](https://commune.email).**

---

## Agent Identity

Email is the identity layer for agents. A human has `name@gmail.com` as their internet identity. An agent gets `agent-name@commune.email` — a permanent address that survives process restarts, framework changes, and infrastructure migrations.

```python
# One line — your agent has an identity on the internet
inbox = commune.inboxes.create(local_part="my-agent")
print(inbox.address)  # → my-agent@org.commune.email
```

This address is yours. It can receive email from any human or any other agent. It has a thread history that persists across sessions. It can be searched semantically. It can forward structured data to your webhook in real time. It is the single stable reference point for your agent in the world.

---

## What you get in 60 seconds

```python
# Python — give your agent an email address
from commune import CommuneClient
commune = CommuneClient(api_key="comm_...")
inbox = commune.inboxes.create(local_part="support")
print(inbox.address)  # → support@yourdomain.commune.email
```

```typescript
// TypeScript — give your agent an email address
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
const inbox = await commune.inboxes.create({ localPart: 'support' });
console.log(inbox.address); // → support@yourdomain.commune.email
```

That's a real, deliverable inbox. Your agent can now send replies, search its thread history semantically, extract structured data from inbound mail, and receive webhook events — all with two lines of code.

---

## OpenClaw

> **OpenClaw users:** install the Commune email skill in 30 seconds. Your agent gets a real inbox it can use from WhatsApp, Telegram, or wherever it lives.

```bash
git clone https://github.com/commune-dev/commune-openclaw-email-quickstart
cd commune-openclaw-email-quickstart
bash install.sh
```

The installer copies the skill into `~/.openclaw/workspace/skills/`:
- **`commune-email`** — send, receive, search, and manage email threads

Once installed, your agent understands natural-language commands like "check my email" and "reply to that thread about the contract."

[→ Dedicated repo with use cases](https://github.com/commune-dev/commune-openclaw-email-quickstart)

---

## Agent-to-Agent Communication

Agents communicate through Commune the same way humans do — by sending each other email. Every agent gets an address. Addresses are permanent. Threads preserve the full task chain.

```python
# Each agent is an email address
orchestrator = commune.inboxes.create(local_part="orchestrator")
researcher   = commune.inboxes.create(local_part="researcher")

# Send a task
task = commune.messages.send(
    to=researcher.address,          # researcher@org.commune.email
    subject="Research task",
    text="Compare Postgres hosting pricing: Neon, Supabase, Railway.",
    inbox_id=orchestrator.id,
    idempotency_key="research-001", # safe to retry
)

# Researcher replies in the same thread — full context preserved
commune.messages.send(
    to=orchestrator.address,
    subject="Re: Research task",
    text=result,
    inbox_id=researcher.id,
    thread_id=task.thread_id,       # binds reply to task
)

# Orchestrator reads the full chain
messages = commune.threads.messages(task.thread_id)
# messages[0] = task, messages[1] = result, messages[n] = any follow-up
```

No shared database. No coordination layer. The thread IS the task context.

[→ Full A2A examples with typed task delegation, semantic deduplication, and agent mesh patterns](agent-to-agent/)

---

## Examples

| Example | [LangChain](langchain/) | [CrewAI](crewai/) | [OpenAI Agents](openai-agents/) | [Claude](claude/) | [MCP](mcp-server/) | [TypeScript](typescript/) | [A2A](agent-to-agent/) |
|---------|:---------:|:------:|:-------------:|:------:|:---:|:----------:|:---:|
| Customer Support Agent | [✅](langchain/) | [✅](crewai/) | [✅](openai-agents/) | [✅](claude/) | [✅](mcp-server/) | [✅](typescript/) | — |
| Lead Outreach | [✅](langchain/) | [✅](crewai/) | — | [✅](claude/) | — | — | — |
| Multi-Agent Coordination | — | [✅](crewai/) | — | — | — | [✅](typescript/) | [✅](agent-to-agent/) |
| Structured Extraction | — | — | — | [✅](claude/) | [✅](mcp-server/) | — | — |
| Webhook Handler | — | — | — | — | — | [✅](typescript/) | — |
| Task Delegation | — | — | — | — | — | — | [✅](agent-to-agent/) |

---

## Why email for agents?

Most agent frameworks are great at reasoning — but stop short when it comes to communicating with the outside world asynchronously. Email fills that gap:

- **Agents are async by nature.** A task might take minutes or hours. Email is the right protocol for async handoffs — your agent sends, the user replies when ready, the thread stays intact.
- **Email is the universal protocol.** Every system on the planet speaks SMTP. Your agent can talk to any user, any tool, any service — no integration required.
- **Threading keeps context.** `In-Reply-To` and `References` headers (RFC 5322) tie every message to its thread. Your agent never loses the conversation history.
- **Agent-to-agent is next.** Agents will increasingly communicate with other agents — delegating tasks, routing results, building mesh networks. Email is the right protocol: async, persistent, addressable, universally supported.

### What Commune adds on top of bare SMTP

| Feature | What it means for your agent |
|---------|-------------------------------|
| **Vector search across threads** | `commune.search.threads({ query })` — find relevant past conversations with semantic similarity, not keyword matching |
| **Structured JSON extraction** | Define a JSON schema per inbox; every inbound email is parsed into structured data automatically |
| **Idempotent sends** | Pass an `idempotency_key` and your agent gets a `202` immediately — Commune deduplicates sends within a 24-hour window, so retries never produce duplicate messages |
| **Guaranteed webhook delivery** | 8 retries with exponential backoff and a circuit breaker — your agent's handler will receive every event even through transient failures |
| **Per-inbox task schemas** | Configure what a "task email" looks like — Commune extracts typed fields before your webhook fires |

---

## Architecture

```mermaid
flowchart LR
    subgraph Agents["AI Agents"]
        A1["Agent A\norchestrator@org.commune.email"]
        A2["Agent B\nresearcher@org.commune.email"]
        A3["LangChain / CrewAI\nOpenAI / Claude / MCP"]
    end
    subgraph Commune["Commune Platform"]
        B[Inbox] --> C[Email Threading]
        C --> D[Vector Search]
        C --> E[JSON Extraction]
        C --> F[Webhook Delivery]
    end
    Human["User / External\nEmail Client"] <-->|"email"| Commune
    A1 <-->|"task delegation"| A2
    Agents <-->|"Commune SDK\ncommune-ai / commune-mail"| Commune
    F -->|"webhook\n(HMAC signed)"| Agents
```

---

## Quick start

**1. Install the SDK**

```bash
# Python
pip install commune-mail

# TypeScript / Node
npm install commune-ai
```

**2. Get your API key**

Sign up at [commune.email](https://commune.email) — free tier included, no credit card required.

**3. Pick an example 

[truncated…]