Introduction

Give your agent an email inbox

Commune gives AI agents real email addresses. Your agent can send emails, receive replies, extract structured data from inbound messages, and track deliverability. Everything runs through a single API, SDKs for TypeScript and Python, or an MCP server for Claude/Cursor/Windsurf.

Quickstart

Get your agent connected in minutes.

TypeScript

npm install commune-ai

Python

pip install commune-mail

MCP Server

Claude Desktop, Cursor, Windsurf

REST API

Any language via HTTP

Source available

The entire platform is on GitHub: backend API, SDKs, MCP server, and dashboard. Licensed under BSL 1.1 (converts to Apache 2.0 after 4 years). See the contributing guide for details.

Ultra-quick start

Send your first email in under 30 seconds.

npm install commune-ai

pip install commune-mail

# Add to your Claude/Cursor/Windsurf config:
# command: "uvx", args: ["commune-mcp"]

import { CommuneClient } from 'commune-ai';

const commune = new CommuneClient({ apiKey: 'comm_...' });

// Create an inbox (domain auto-assigned)
const inbox = await commune.inboxes.create({
  localPart: 'support',
});

// Send an email
await commune.messages.send({
  to: 'user@example.com',
  subject: 'Hello from my agent',
  text: 'Your AI agent is now connected to email.',
});

from commune import CommuneClient

client = CommuneClient(api_key="comm_...")

# Create an inbox
inbox = client.inboxes.create(local_part="support")

# Send an email
client.messages.send(
    to="user@example.com",
    subject="Hello from my agent",
    text="Your AI agent is now connected to email.",
)

# Create an inbox
curl -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{"local_part": "support"}'

# Send an email
curl -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello from my agent",
    "text": "Your AI agent is now connected to email."
  }'

That’s it. Your agent now has an email address and can send messages.

What happens to every email

Commune sits between your agent and the outside world. Every email passes through security, validation, and enrichment before it reaches the other side.

Outbound

Your Agent
  │
  ▼
Commune API
  │
  ├─ Rate limiting (per-second + daily caps)
  ├─ Burst detection (blocks abnormal spikes)
  ├─ Content validation (outbound spam/phishing check)
  ├─ Sending health gate (pauses if bounce/complaint rates are critical)
  ├─ Warmup gate (gradual volume increase for new inboxes)
  ├─ Email validation (MX records, syntax, disposable domain detection)
  ├─ Suppression check (skips previously bounced/complained addresses)
  ├─ Per-inbox + per-key daily limit enforcement
  │
  ▼
DKIM-signed delivery ──→ Recipient's inbox
  │
  ▼
Delivery tracking (sent → delivered / bounced / complained)
  │
  ▼
Metrics + suppression list auto-updated

Rate-limited, validated, and checked against suppression lists before anything leaves. After delivery, Commune tracks the outcome: bounced addresses get suppressed, complaint rates are monitored, sending pauses if thresholds are breached.

Inbound

Sender's email
  │
  ▼
Commune receives on your inbox address
  │
  ├─ Full email parsing (headers, body, HTML, plain text)
  ├─ Thread resolution (routing token → DB lookup → SMTP headers → new thread)
  ├─ Attachment extraction + storage
  ├─ Attachment scanning (antivirus + heuristic threat detection)
  ├─ Spam scoring (header analysis, content patterns, sender reputation)
  ├─ Prompt injection detection (AI-targeted attack analysis)
  ├─ Structured data extraction (your JSON schema → LLM → structured output)
  ├─ Encryption at rest (AES-256-GCM for content + metadata)
  │
  ▼
Stored in Commune (threads, messages, attachments, metadata)
  │
  ▼
Webhook POST to your server
  ├─ Full parsed message
  ├─ Extracted structured data
  ├─ Security context (spam score, prompt injection risk level)
  ├─ Attachment metadata
  │
  ▼
Your agent processes + replies (back through the outbound pipeline)

By the time an email reaches your webhook, it’s been parsed, threaded, scanned for threats and prompt injection, scored for spam, and extracted against your schema. Your agent gets a clean payload ready to act on.

Core concepts

Inboxes

Each agent gets one or more inboxes. An inbox is an email address like support@yourdomain.com that can send and receive email.

Threads

Related emails are automatically grouped into threads. Your agent can list threads, read messages, set status, add tags, and assign threads.

Domains

Use Commune’s shared domain to get started instantly, or add a custom domain with full DKIM/SPF/DMARC authentication.

Webhooks

Get notified instantly when emails arrive. Webhooks deliver the full parsed email, extracted data, and security context to your server.

SDKs

	Install
TypeScript	`npm install commune-ai`
Python	`pip install commune-mail`
MCP (Claude, Cursor, Windsurf)	`uvx commune-mcp`
REST API	Any HTTP client with a Bearer token

Every feature works through all four. The docs show examples for each.

Next steps

Get API Key

Create your API key and start sending emails immediately.

Quickstart

Build a complete email agent in 5 minutes — send, receive, extract data, and handle attachments.

Authentication

Understand API authentication and security best practices.

SDKs

Install and configure the SDK for your language.

Security

Learn how Commune handles DKIM, encryption, spam prevention, and more.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

Give your agent an email inbox

Quickstart

TypeScript

Python

MCP Server

REST API

Source available

Ultra-quick start

What happens to every email

Outbound

Inbound

Core concepts

Inboxes

Threads

Domains

Webhooks

SDKs

Next steps

Get API Key

Quickstart

Authentication

SDKs

Security

​Give your agent an email inbox

​Quickstart

TypeScript

Python

MCP Server

REST API

​Source available

​Ultra-quick start

​What happens to every email

​Outbound

​Inbound

​Core concepts

Inboxes

Threads

Domains

Webhooks

​SDKs

​Next steps

Get API Key

Quickstart

Authentication

SDKs

Security

Give your agent an email inbox

Quickstart

Source available

Ultra-quick start

What happens to every email

Outbound

Inbound

Core concepts

SDKs

Next steps