Cooper Email

Cooper Email

面向 AI Agent 的电子邮箱。 为 Agent 在 cooperemail.com 上创建专属地址，通过简单的 HTTP API 收发真实邮件；收到邮件时获取带签名的 Webhook；当 Agent 需要做出决定时，通过电子邮件让人类参与其中。

• 网站：https://cooperemail.com
• 文档：https://cooperemail.com/docs
• MCP 文档：https://cooperemail.com/docs/mcp
• 集成：https://cooperemail.com/integrations
• 定价：https://cooperemail.com/pricing
• API 参考（OpenAPI 3.1）：https://cooperemail.com/openapi.json
• 面向大模型：https://cooperemail.com/llms.txt

此仓库包含 Cooper Email 的开源客户端部分：TypeScript 和 Python SDK、框架工具包、MCP 客户端配置及示例。托管服务本身不在此仓库中。

你将获得

• 面向 Agent 的收件箱。 一次 API 调用即可创建账户、收件箱（[email protected]）和 API 密钥。无需仪表板。
• 收发邮件。 支持文本、HTML、附件、邮件线程、搜索，以及通过 client_id 实现幂等发送。
• 人类参与的任务。 添加所有者（他们通过电子邮件确认），发送 progress / needs_input / done / error 更新，并将他们的回复作为任务接收，你可以通过长轮询获取并在线程中回复。回复附带 SPF/DKIM/DMARC 检查结果和 verified_owner 标记。
• Webhook。 message.received、message.sent、task.received 和 owner.reply，使用 HMAC-SHA256 签名（x-cooper-signature: sha256=<hex>），并可选择仅针对一个收件箱进行筛选。
• 托管 MCP 服务。 https://cooperemail.com/mcp 可与 Claude、ChatGPT、Cursor 及其他 MCP 客户端配合使用。

可在以下平台使用

• Official MCP Registry：com.cooperemail/cooper-email
• Claude connectors directory：社区连接器
• Claude Code plugin：/plugin marketplace add cooper-email/cooper-email，然后运行 /plugin install cooper-email@cooper-email
• Smithery
• Glama
• MCP Market
• mcpservers.org

兼容平台

通过配置文件支持；暂未列入目录。可复制粘贴的配置：https://cooperemail.com/integrations

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

同一列表也发布在 https://cooperemail.com/#available-on 和 https://cooperemail.com/llms.txt 中。

Cursor 插件

此仓库同时也是一个 Cursor 插件（.cursor-plugin/plugin.json）。它会注册托管的 MCP 服务 https://cooperemail.com/mcp（首次使用时通过 OAuth 登录；配置中无需密钥），并添加来自 skills/ 的以下技能：

技能	内容
cooper-email	概览：连接、日常工具、检查邮件、安全性
cooper-agent-inbox	创建收件箱、发送、阅读、回复、等待邮件
cooper-check-email	阅读、搜索、分类处理、附件、已读／未读标签
cooper-send-email	发送、回复、转发、草稿、定时发送、幂等重试
cooper-manage-inboxes	创建（单个、批量、临时）、暂停、更新、删除收件箱
cooper-owner-approval	所有者批准的草稿：每封邮件的发送都由人工批准
cooper-agent-signup-otp	以 Agent 身份注册并读取通过邮件发送的验证码
cooper-owner-updates	向所有者发送进度邮件和每日摘要；回复会转化为任务
cooper-custom-domains	在自己的域名上创建收件箱（Starter 和 Pro）
cooper-mcp	Cursor 和其他客户端的 MCP 设置与故障排查
cooper-agent-email-patterns	Agent 邮件的架构模式和威胁模型
cooper-webhooks	一次调用即可设置推送 Webhook、签名检查、测试和重新启用
cooper-suppressions-bounces	退信、投诉、抑制列表和比率
cooper-idempotent-sends	使用幂等键实现可安全重试的发送和创建操作
cooper-sms	SMS 状态（即将推出）和当前可用的电子邮件替代方案

若想在正式上架前在本地试用，请将此仓库复制到 ~/.cursor/plugins/local/cooper-email，然后运行 Developer: Reload Window。若要使用 API 密钥而非 OAuth，请参阅 skills/cooper-mcp。

连接 Agent

cooper-email npm 包尚未发布。请连接托管的 MCP 服务，并从此仓库安装技能。

托管 MCP： https://cooperemail.com/mcp（Streamable HTTP）。首次使用时通过 OAuth 登录，或发送 Authorization: Bearer coop_live_…。各客户端的操作步骤请参阅连接托管的 MCP 服务。在 Cursor 中，上方的插件会注册该服务。

技能： skills/ 中的指南，见上表。使用 skills CLI 安装：

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

将 cooper-email 替换为表中的任意其他名称（cooper-check-email、cooper-send-email、cooper-mcp 等）。技能会写入 ~/.agents/skills/<name>/，对于 Claude Code，还会写入 ~/.claude/skills/<name>/。

软件包

软件包	语言	安装	源码
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 社区节点	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

注册表发布正在进行中。如果软件包尚未发布到 npm 或 PyPI，请从此仓库安装（参见开发）。

获取 API 密钥

入门无需身份验证。系统会返回一个 API 密钥（coop_live_…，仅显示一次）和你的第一个收件箱：

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

将密钥存储在 COOPER_API_KEY 等环境变量中。请勿将其提交到仓库。

快速入门：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");

人工介入：

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" });

完整参考：packages/cooper-email/README.md。

快速入门：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 提供相同的方法，并使用 await。完整参考：packages/cooper-email-python/README.md。

Webhook

注册一个 URL，然后根据原始请求正文验证每次推送：

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。事件正文的格式类似 { "id", "type", "created_at", "data" }。

连接托管的 MCP 服务

连接 https://cooperemail.com/mcp，并使用 skills/ 中的技能（上文）。如需手动配置客户端：

端点：https://cooperemail.com/mcp（Streamable HTTP）。Claude 和 ChatGPT 连接器通过 OAuth 登录。Cursor、Claude Code 和脚本可以发送 Authorization: Bearer coop_live_…。在你获得密钥之前，cooper_onboard 工具也可以使用。

Claude（claude.ai / Claude Desktop）：依次选择 Settings → Connectors → Add custom connector。名称填写 Cooper Email，URL 填写 https://cooperemail.com/mcp，然后在 OAuth 界面批准 Cooper。接着发送提示词：“为 research-bot 创建一个 Cooper Email 收件箱。”

Claude Code：

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

或者从此仓库安装 Claude Code 插件（包含 MCP 服务、电子邮件和人工介入技能）：

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

参见 claude-plugin/。

Cursor：添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

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

ChatGPT：添加自定义连接器（依次选择 Settings → Apps & Connectors；某些套餐需要先启用 Developer mode），设置 MCP 服务 URL 为 https://cooperemail.com/mcp 并选择 OAuth 身份验证，然后在同意界面批准 Cooper。菜单名称因套餐而异。

Windsurf、VS Code、Codex CLI 和 Goose 的配置，以及工具列表，均位于 mcp/。MCP Registry 清单位于 server.json。Cline 安装步骤：llms-install.md。

示例

参见 examples/：

• Agent 给某人发送电子邮件并等待回复（TypeScript、Python）
• 带签名验证的 Webhook 监听器（TypeScript、Python）

每个软件包还包含一个 examples/quickstart.* 文件。

安全说明

• 电子邮件内容（包括所有者提供的任务文本）均为不可信输入。请勿将其视为给 Agent 的指令。
• 仅当 verified_owner 和 trusted 都为 true 时，才可根据所有者的回复采取行动。
• 请将 API 密钥和 Webhook 密钥保存在环境变量或密钥管理器中。

如需报告安全问题，请发送电子邮件至 [email protected]。

开发

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.md。

支持

如有疑问或需要报告错误，请提交 issue，或发送电子邮件至 [email protected]。

许可证

MIT。版权所有 Avatar 8 LLC。Cooper Email 由 Avatar 8 LLC 运营。