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 ([email protected]), 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/:

Skill	What it covers
cooper-email	Overview: connect, everyday tools, checking mail, safety
cooper-agent-inbox	Create an inbox, send, read, reply, wait for mail
cooper-check-email	Read, search, triage, attachments, read/unread labels
cooper-send-email	Send, reply, forward, drafts, scheduled send, idempotent retries
cooper-manage-inboxes	Create (single, batch, temporary), pause, update, delete inboxes
cooper-owner-approval	Owner-approved drafts: a human approves each send by email
cooper-agent-signup-otp	Sign up as the agent and read the emailed verification code
cooper-owner-updates	Progress emails and daily digests to an owner; replies become tasks
cooper-custom-domains	Inboxes on your own domain (Starter and Pro)
cooper-mcp	MCP setup and troubleshooting for Cursor and other clients
cooper-agent-email-patterns	Architecture patterns and threat model for agent email
cooper-webhooks	One-call push webhooks, signature checks, test and re-enable
cooper-suppressions-bounces	Bounces, complaints, the suppression list, and rates
cooper-idempotent-sends	Retry-safe sends and creates with idempotency keys
cooper-sms	SMS status (coming soon) and the email alternatives today

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

Package	Language	Install	Source
cooper-email	TypeScript / JavaScript SDK	npm install cooper-email	packages/cooper-email
cooper-email	Python	pip install cooper-email	packages/cooper-email-python
cooper-email-langchain	TypeScript	npm install cooper-email-langchain	packages/langchain
cooper-email-langchain	Python	pip install cooper-email-langchain	packages/langchain-py
cooper-email-ai (Vercel AI SDK)	TypeScript	npm install cooper-email-ai	packages/ai
cooper-email-mastra	TypeScript	npm install cooper-email-mastra	packages/mastra
cooper-email-anthropic	TypeScript	npm install cooper-email-anthropic	packages/anthropic
cooper-email-anthropic	Python	pip install cooper-email-anthropic	packages/anthropic-py
cooper-email-openai-agents	TypeScript	npm install cooper-email-openai-agents	packages/openai-agents
cooper-email-openai-agents	Python	pip install cooper-email-openai-agents	packages/openai-agents-py
cooper-email-llamaindex	Python	pip install cooper-email-llamaindex	packages/llamaindex
cooper-email-crewai	Python	pip install cooper-email-crewai	packages/crewai
n8n-nodes-cooper-email	n8n community node	npm install n8n-nodes-cooper-email	packages/n8n-nodes-cooper-email
cooper-email-openapi	OpenAPI 3.1 (Zapier, Make)	npm install cooper-email-openapi	packages/openapi

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: ["[email protected]"],
  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: "[email protected]" }); // 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=["[email protected]"],
        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"], "[email protected]")
    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 [email protected].

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 [email protected].

License

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