AssistantMail AI Agent 技能

能力概述

该技能为 AI 代理提供一种统一的方式，用于发现 AssistantMail 的端点信息，并通过 MCP 直接获取邮箱/邮件数据。

关键访问模型

• 仅知晓一个邮箱地址（例如 agent-b1e4643c@assistant-mail.ai）并不意味着可访问对应邮箱。
• 后端邮件 API 使用 mailboxId（UUID 类型路径参数）作为密钥，而非邮箱地址。
• 邮箱操作的授权基于账户所有权（即要求 mailbox.accountId === auth.accountId）。

这对 AI 代理意味着：

• 邮箱地址仅用作路由标识，而非认证凭据或密钥。
• 客户端在调用邮箱相关接口时，必须传入正确的 mailboxId。
• 仍需提供有效的 API 密钥或 Cognito JWT 进行身份验证。

代理初始化流程（必需）

1. 人类所有者在 assistant-mail.ai 上完成注册或登录。[了解更多](#)
2. 人类所有者通过 POST /v1/api-keys 创建一个 API 密钥。
3. 人类所有者将返回的 amk_... 密钥安全地传递给代理运行时环境。
4. 代理通过 GET /v1/mailboxes 列出可用邮箱，并保存目标 mailboxId。
5. 代理在后续的发送、列表查询、获取、用量统计等操作中均使用该 mailboxId。

注意事项：

• API 密钥仅在创建时显示一次，不可再次查看。
• API 密钥管理接口仅可通过面向人类用户的 Web 应用访问。
• API 密钥认证支持两种方式：x-api-key: amk_... 或 Authorization: Bearer amk_...。

MCP 连接配置

• 命令：assistantmail-mcp
• 环境变量：
  • ASSISTANT_MAIL_API_BASE_URL（可选，默认为 https://api.assistant-mail.ai）
  • ASSISTANT_MAIL_API_KEY（可选，值为 amk_...；当工具调用未显式传入 apiKey 输入时，将自动使用该环境变量）
• 可用工具列表：
  • assistantmail_health
  • assistantmail_get_me
  • assistantmail_get_inbound_policy
  • assistantmail_update_inbound_policy
  • assistantmail_list_mailboxes
  • assistantmail_create_mailbox
  • assistantmail_get_mailbox
  • assistantmail_update_mailbox
  • assistantmail_delete_mailbox
  • assistantmail_list_messages
  • assistantmail_get_message
  • assistantmail_send_email
  • assistantmail_reply_message —— 回复代理已收到的一封邮件；自动处理邮件线程（In-Reply-To、References 字段）。
  • assistantmail_delete_messages
  • assistantmail_get_usage
  • assistantmail_list_recipients
  • assistantmail_add_recipient
  • assistantmail_remove_recipient
  • assistantmail_send_email_reference
  • assistantmail_list_messages_reference
  • assistantmail_get_message_reference
  • assistantmail_get_usage_reference

上述直接调用工具覆盖了 AI 代理预期调用的所有基于 API 密钥的操作端点。

OpenClaw

在 OpenClaw 的技能/MCP 注册表中注册 MCP 命令 assistantmail-mcp 即可启用本技能。

Claude

通过添加一条 MCP 服务器条目，启动 assistantmail-mcp 即可使用本技能。

OpenAI

通过配置一个 MCP 连接器，使其启动 assistantmail-mcp 并暴露上述工具，即可使用本技能。

直接 MCP 调用（无需手动拼接 URL）

{
  "tool": "assistantmail_list_mailboxes",
  "input": {
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_get_mailbox",
  "input": {
    "mailboxId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_list_messages",
  "input": {
    "mailboxId": "",
    "limit": 50,
    "since": "2026-01-01T00:00:00.000Z",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_get_message",
  "input": {
    "mailboxId": "",
    "messageId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_send_email",
  "input": {
    "mailboxId": "",
    "to": "recipient@example.com",
    "subject": "Hello",
    "text": "Hi there",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_reply_message",
  "input": {
    "mailboxId": "",
    "messageId": "",
    "text": "Thanks for your email!",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_get_usage",
  "input": {
    "mailboxId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_list_recipients",
  "input": {
    "apiKey": "amk_..."
  }
}

若 MCP 服务器环境中已设置 ASSISTANT_MAIL_API_KEY，则可在工具输入中省略 apiKey 字段。