v0.3.0 — search, sms, delivery namespaces

New in 0.3.0

Three new namespaces on CommuneClient (and AsyncCommuneClient):

client.search.threads(query)

Search email threads by subject or content:

results = client.search.threads(query="invoice", inbox_id=inbox_id)
for r in results:
    messages = client.threads.messages(r.thread_id)

client.sms.send(to, body)

Send an SMS alongside email workflows:

result = client.sms.send(to="+15551234567", body="Urgent: check your email")

client.delivery.metrics(inbox_id)

Monitor deliverability health:

metrics = client.delivery.metrics(inbox_id=inbox_id, period="7d")
print(f"Delivery rate: {metrics.delivery_rate:.1f}%")
print(f"Bounce rate: {metrics.bounce_rate:.1f}%")

Also includes client.delivery.suppressions() and client.delivery.events().

New response types

SearchResult, SmsSendResult, DeliveryMetrics, DeliverySuppression, DeliveryEvent

v0.2.1 — Webhook signature fix and rate limit headers

Patch release: webhook signature verification now correctly matches the backend protocol.

Fixes

• verify_signature() updated to match the HMAC-SHA256 protocol used by the Commune backend (timestamp + body concatenation)
• Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) now exposed on API responses

Upgrading

pip install --upgrade commune-mail

No breaking changes. If you were calling verify_signature() manually, update to the new signature.

v0.2.0 — Structured extraction, SMS, and async client

Major capability expansion: per-inbox JSON extraction, SMS support, and a full async client.

New in v0.2.0

Structured extraction (no extra LLM calls)

Define a JSON schema on any inbox and every inbound email is parsed against it automatically — before it reaches your agent. Extract order IDs, urgency levels, issue types, and any field your agent needs:

client.inboxes.update(inbox_id, extraction_schema={
    "type": "object",
    "properties": {
        "issue_type": {"type": "string", "enum": ["billing", "technical", "general"]},
        "urgency": {"type": "string", "enum": ["low", "medium", "high"]},
        "order_id": {"type": "string"},
    }
})
# Every inbound email now has a .extracted field — zero LLM cost

SMS support

Provision a real phone number and send/receive SMS from the same client:

phone = client.phone_numbers.provision()
client.sms.send(to="+14155551234", body="Your order shipped", phone_number_id=phone.id)

Async client

Full async support with AsyncCommuneClient — drop-in replacement for async frameworks:

from commune import AsyncCommuneClient

async with AsyncCommuneClient(api_key="comm_...") as client:
    inbox = await client.inboxes.create(local_part="support")

Use cases unlocked

• Support ticket routing: extract issue_type from inbound email, route to correct agent without an LLM classification call
• SMS escalation: email for async, SMS for urgent — both from the same agent
• Order processing: extract order details from confirmation emails automatically

v0.1.0 — Initial release: programmatic inboxes for Python agents

First public release of commune-mail — the Python SDK for giving AI agents real email inboxes.

What's included

• CommuneClient and AsyncCommuneClient for sync and async workflows
• client.inboxes.create() — provision a real inbox in one line
• client.messages.send() — send email or reply in existing thread
• client.threads.list() and client.threads.messages() — read conversation history
• client.search.threads() — semantic search across inbox history
• Webhook verification with verify_signature()

Why this exists

AI agents need to communicate with the outside world asynchronously. Email is the universal protocol — every system, every user, every tool speaks SMTP. But raw SMTP requires DNS setup, deliverability management, and thread tracking. commune-mail gives your agent a production-grade inbox in one line of code.

Quickstart

pip install commune-mail

from commune import CommuneClient

client = CommuneClient(api_key="comm_...")
inbox = client.inboxes.create(local_part="support")
# → support@agents.commune.email — real, deliverable, webhook-ready

Framework integrations

Works with LangChain, CrewAI, OpenAI Agents SDK, Claude, and any Python agent framework. See the cookbook for examples.