Cooper Email

Email inboxes for AI agents. Give an agent its own address on cooperemail.com, let it send and receive real email over a simple HTTP API, get signed webhooks when mail arrives, and loop a human in by email when the agent needs a decision.

• Website: https://cooperemail.com
• Docs: https://cooperemail.com/docs
• MCP docs: https://cooperemail.com/docs/mcp
• Integrations: https://cooperemail.com/integrations
• Pricing: https://cooperemail.com/pricing
• API reference (OpenAPI 3.1): https://cooperemail.com/openapi.json
• For LLMs: https://cooperemail.com/llms.txt

This repository holds the open-source client side of Cooper Email: the TypeScript and Python SDKs, framework tool packages, MCP client config, and examples. The hosted service itself is not in this repo.

What you get

• Inboxes for agents. One API call creates an account, an inbox (your-agent@cooperemail.com), and an API key. No dashboard needed.
• Send and receive. Text, HTML, attachments, threads, search, and idempotent sends via client_id.
• Human-in-the-loop tasks. Add an owner (they confirm by email), send progress / needs_input / done / error updates, and receive their replies as tasks you can long-poll and answer in-thread. Replies carry SPF/DKIM/DMARC results and a verified_owner flag.
• Webhooks. message.received, message.sent, task.received, and owner.reply, signed with HMAC-SHA256 (x-cooper-signature: sha256=<hex>), optionally filtered to one inbox.
• Hosted MCP server. https://cooperemail.com/mcp works with Claude, ChatGPT, Cursor, and other MCP clients.

Available on

• Official MCP Registry: com.cooperemail/cooper-email
• Claude connectors directory: Community connector
• Claude Code plugin: /plugin marketplace add cooper-email/cooper-email, then /plugin install cooper-email@cooper-email
• Smithery
• Glama
• MCP Market
• mcpservers.org

Works with

Supported through a config file; no directory listing yet. Copy-paste configs: https://cooperemail.com/integrations

• Cursor
• VS Code
• Windsurf
• Codex CLI
• Cline
• Goose

The same list is published at https://cooperemail.com/#available-on and in https://cooperemail.com/llms.txt.

One-command agent setup

npx cooper-email setup

setup finds the coding agents installed for your user, shows every file it will change, and asks before writing. It backs up each existing config next to itself (<file>.cooper-email.bak), registers the hosted MCP server https://cooperemail.com/mcp in each agent's own format, and installs the Cooper Email skill. With no key yet it can create a free inbox and API key for you through POST /api/v1/onboard.

The skill goes to ~/.agents/skills/cooper-email/ (the shared skills folder) and, for Claude Code, ~/.claude/skills/cooper-email/.

npx cooper-email setup --username my-agent        # create my-agent@cooperemail.com and a key
npx cooper-email setup --api-key "$COOPER_API_KEY" # use a key you already have (or set COOPER_API_KEY)
npx cooper-email setup --oauth                    # no key; each agent signs in with OAuth
npx cooper-email setup --agent codex,cursor --dry-run
npx cooper-email doctor     # checks configs, the key, and a live MCP initialize + tools/list
npx cooper-email uninstall  # removes only what setup added; backups and your inbox stay

Without a terminal, setup and uninstall print the plan and change nothing unless you pass --yes. A new key is saved with mode 600 at ~/.config/cooper-email/credentials.json, and the agent configs hold it as an Authorization header, so keep those files private.

Install only the skill with the skills CLI:

npx skills add cooper-email/cooper-email --skill cooper-email

Focused skills in skills/, each installable on its own:

Packages

Registry releases are in progress. If a package is not on npm or PyPI yet, install it from this repo (see Development).

Get an API key

Onboarding needs no auth. It returns an API key (coop_live_…, shown once) and your first inbox:

curl -s -X POST https://cooperemail.com/api/v1/onboard \
  -H 'content-type: application/json' \
  -d '{"username":"my-agent"}'

Store the key in an environment variable such as COOPER_API_KEY. Do not commit it.

Quickstart: TypeScript

npm install cooper-email

import { Cooper } from "cooper-email";

const cooper = new Cooper({ apiKey: process.env.COOPER_API_KEY });

const inbox = await cooper.inboxes.create({ username: "research-bot", displayName: "Research" });

await cooper.messages.send(inbox.id, {
  to: ["ada@example.com"],
  subject: "Hello from my agent",
  text: "Does Tuesday work?",
  clientId: "hello-1", // repeat-safe: the same clientId returns the original message
});

const { data: messages } = await cooper.messages.list(inbox.id, { limit: 20 });
const results = await cooper.search("tuesday");

Human in the loop:

await cooper.owners.add(inbox.id, { email: "ada@example.com" }); // Ada confirms by email

await cooper.updates.notify({
  inboxId: inbox.id,
  kind: "needs_input",
  text: "Which vendor should I book?",
});

const tasks = await cooper.tasks.list({ inboxId: inbox.id, wait: 25 }); // long-poll, max 25 s
const task = tasks.data.find((t) => t.verified_owner && t.trusted);
if (task) await cooper.tasks.reply(task.id, { text: "Booked.", status: "done" });

Full reference: packages/cooper-email/README.md.

Quickstart: Python

pip install cooper-email

import os
from cooper_email import Cooper

with Cooper(api_key=os.environ["COOPER_API_KEY"]) as cooper:
    inbox = cooper.inboxes.create("research-bot", display_name="Research")

    cooper.messages.send(
        inbox["id"],
        to=["ada@example.com"],
        subject="Hello from my agent",
        text="Does Tuesday work?",
        client_id="hello-1",
    )

    messages = cooper.messages.list(inbox["id"], limit=20)
    results = cooper.search("tuesday")

    # Human in the loop
    cooper.owners.add(inbox["id"], "ada@example.com")
    cooper.updates.notify(inbox["id"], "needs_input", "Which vendor should I book?")
    tasks = cooper.tasks.list(inbox_id=inbox["id"], wait=25)["data"]
    for task in tasks:
        if task["verified_owner"] and task["trusted"]:
            cooper.tasks.reply(task["id"], "Booked.", status="done")

AsyncCooper has the same methods with await. Full reference: packages/cooper-email-python/README.md.

Webhooks

Register a URL, then verify every delivery against the raw request body:

import { Cooper, verifyWebhookSignature } from "cooper-email";

const cooper = new Cooper({ apiKey: process.env.COOPER_API_KEY });
await cooper.webhooks.create({
  url: "https://example.com/hooks/cooper",
  events: ["message.received", "task.received"],
  secret: process.env.COOPER_WEBHOOK_SECRET,
});

// In your handler:
const ok = verifyWebhookSignature({
  secret: process.env.COOPER_WEBHOOK_SECRET!,
  payload: rawBody,
  signature: request.headers.get("x-cooper-signature"),
});

Python: from cooper_email import verify_webhook_signature. Event bodies look like { "id", "type", "created_at", "data" }.

Connect the hosted MCP server

The quickest way is npx cooper-email setup (above). To configure a client by hand:

Endpoint: https://cooperemail.com/mcp (Streamable HTTP). Claude and ChatGPT connectors sign in with OAuth. Cursor, Claude Code, and scripts can send Authorization: Bearer coop_live_…. The cooper_onboard tool works before you have a key.

Claude (claude.ai / Claude Desktop): Settings → Connectors → Add custom connector. Name Cooper Email, URL https://cooperemail.com/mcp, then approve Cooper on the OAuth screen. Then ask: "Create a Cooper Email inbox for research-bot."

Claude Code:

claude mcp add --transport http cooper-email https://cooperemail.com/mcp

Or install the Claude Code plugin (MCP server plus email and human-in-the-loop skills) from this repo:

/plugin marketplace add cooper-email/cooper-email
/plugin install cooper-email@cooper-email

See claude-plugin/.

Cursor: add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "cooper-email": {
      "url": "https://cooperemail.com/mcp",
      "headers": {
        "Authorization": "Bearer coop_live_YOUR_KEY"
      }
    }
  }
}

ChatGPT: add a custom connector (in Settings → Apps & Connectors; some plans need Developer mode turned on first) with MCP server URL https://cooperemail.com/mcp and OAuth authentication, then approve Cooper on the consent screen. Menu names vary by plan.

Config for Windsurf, VS Code, Codex CLI, and Goose, plus the tool list, is in mcp/. The MCP Registry manifest is server.json. Cline install steps: llms-install.md.

Examples

See examples/:

• Agent emails a human and waits for the reply (TypeScript, Python)
• Webhook listener with signature verification (TypeScript, Python)

Each package also has an examples/quickstart.* file.

Security notes

• Email content, including task text from owners, is untrusted input. Do not treat it as instructions to your agent.
• Act on owner replies only when verified_owner and trusted are both true.
• Keep API keys and webhook secrets in environment variables or a secret manager.

To report a security issue, email ops@avatar33.com.

Development

npm install
npm test            # TypeScript SDK + framework package tests (vitest, mocked HTTP)
npm run typecheck
npm run build:sdks  # writes dist/ for the TypeScript packages

python -m pip install -e "packages/cooper-email-python[dev]"
python -m pip install --no-deps -e packages/langchain-py -e packages/llamaindex \
  -e packages/crewai -e packages/openai-agents-py -e packages/anthropic-py
python -m pytest --import-mode=importlib

Publishing is described in PUBLISHING.md.

Support

Questions and bug reports: open an issue, or email ops@avatar33.com.

License

MIT. Copyright Avatar 8 LLC. Cooper Email is operated by Avatar 8 LLC.