Cooper Email README

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.

Cursor plugin

This repository is also a Cursor plugin (.cursor-plugin/plugin.json). It registers the hosted MCP server https://cooperemail.com/mcp (OAuth sign-in on first use; no key in the config) and adds these skills from skills/:

To try it locally before it is listed, copy this repository into ~/.cursor/plugins/local/cooper-email and run Developer: Reload Window. To use an API key instead of OAuth, see skills/cooper-mcp.

Connect an agent

The cooper-email npm package is not published yet. Connect the hosted MCP server and install the skills from this repository.

Hosted MCP: https://cooperemail.com/mcp (Streamable HTTP). Sign in with OAuth on first use, or send Authorization: Bearer coop_live_…. Per-client steps are in Connect the hosted MCP server. In Cursor, the plugin above registers that server.

Skills: the guides in skills/, listed in the table above. Install one with the skills CLI:

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

Replace cooper-email with any other name from that table (cooper-check-email, cooper-send-email, cooper-mcp, and the rest). The skill is written to ~/.agents/skills/<name>/ and, for Claude Code, ~/.claude/skills/<name>/.

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

Connect https://cooperemail.com/mcp and use the skills in skills/ (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.