Authentication

API keys

Every request needs an API key. Keys are scoped to your organization and start with comm_. Create one in the dashboard. It’s shown once, so copy it immediately. Pass it as a Bearer token:

Authorization: Bearer comm_your_api_key_here

import { CommuneClient } from 'commune-ai';

const commune = new CommuneClient({
  apiKey: process.env.COMMUNE_API_KEY,
});

from commune import CommuneClient

client = CommuneClient(api_key="comm_...")
# Or set the COMMUNE_API_KEY environment variable
client = CommuneClient()  # reads from env automatically

{
  "mcpServers": {
    "commune": {
      "command": "uvx",
      "args": ["commune-mcp"],
      "env": {
        "COMMUNE_API_KEY": "comm_..."
      }
    }
  }
}

curl https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer comm_..."

Base URL

https://api.commune.email

If you are migrating from older setups, you can still override the base URL via COMMUNE_BASE_URL.

Permissions

API keys can be configured with granular permissions:

Permission	Description
`messages:read`	List and read messages, threads, delivery events
`messages:write`	Send emails, manage thread metadata
`inboxes:read`	List and read inboxes
`inboxes:write`	Create, update, and delete inboxes
`domains:read`	List and read domains, DNS records, DMARC reports
`domains:write`	Create domains, trigger verification
`attachments:read`	Read attachment metadata and download URLs
`attachments:write`	Upload attachments
`threads:read`	List threads, read thread metadata
`threads:write`	Update thread status, tags, assignment
`admin`	Full access to all resources
`data:delete`	Create and confirm data deletion requests

Key limits

You can set per-key limits (max inboxes, max emails/day) independently from your plan’s org-level limits.

Response format

Success

{
  "data": {
    // ... response payload
  }
}

Error

{
  "error": "Human-readable error message"
}

Pagination

List endpoints use cursor-based pagination:

{
  "data": [ ... ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMi...",
  "has_more": true
}

Pass next_cursor as the cursor query parameter to fetch the next page.

Response codes

Code	Description
`200`	Success
`201`	Created (new resource)
`400`	Bad request — check parameters
`401`	Missing or invalid API key
`403`	Insufficient permissions or quota exceeded
`404`	Resource not found
`409`	Conflict (e.g., duplicate resource)
`413`	Payload too large (attachment size limit)
`429`	Rate limit exceeded
`500`	Server error

x402 wallet auth

Don’t want an API key? Your agent can pay per call with USDC instead. Create an x402 client with your own signer and pass it to the SDK. Every API call is paid via the x402 protocol.

// You create the x402 client with your own signer — we never see your key
const x402 = new x402Client();
registerExactEvmScheme(x402, { signer: privateKeyToAccount(process.env.WALLET_KEY) });
const commune = new CommuneClient({ wallet: x402 });

from x402 import x402Client
from x402.mechanisms.evm.exact import ExactEvmScheme
from eth_account import Account

x402 = x402Client()
x402.register("eip155:*", ExactEvmScheme(signer=Account.from_key(os.environ["WALLET_KEY"])))
client = CommuneClient(wallet=x402)

No signup, no subscription. Your wallet address becomes your org identity. See the full x402 guide for setup, pricing, and networks.

Security best practices

Never expose your API key in client-side code, public repositories, or browser JavaScript. Always use environment variables.

Store API keys in environment variables (COMMUNE_API_KEY)
Use the minimum permissions necessary for each key
Rotate keys periodically through the dashboard
Set inbox and email limits on keys used by automated systems
Use separate keys for development and production

What’s next?

Quickstart

Build a complete email agent in 5 minutes.

Inboxes

Create and manage email addresses for your agents.

Rate Limits

Understand per-second and daily sending limits.

Agent Auth

Autonomous Ed25519 authentication without human provisioning.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

API keys

Base URL

Permissions

Key limits

Response format

Success

Error

Response codes

x402 wallet auth

Security best practices

What’s next?

Quickstart

Inboxes

Rate Limits

Agent Auth

​API keys

​Base URL

​Permissions

​Key limits

​Response format

​Success

​Error

​Pagination

​Response codes

​x402 wallet auth

​Security best practices

​What’s next?

Quickstart

Inboxes

Rate Limits

Agent Auth

API keys

Base URL

Permissions

Key limits

Response format

Success

Error

Pagination

Response codes

x402 wallet auth

Security best practices

What’s next?