Cooper Email

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= ), 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/ / and, for Claude Code, ~/.claude/skills/ /.

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@coo