vaemail

VaEmail — 面向 AI Agent 的电子邮件基础设施

适用于 VaEmail 的 MCP 服务和 CLI。让 Agent 能够 发送电子邮件、验证发信域名、跟踪投递情况并诊断 送达率问题，无需人工查看仪表板。

欧洲基础设施：服务器位于德国，通过 Amazon SES Europe 发送邮件。

安装

# Claude Code
claude mcp add vaemail --env VAEMAIL_API_KEY=swm_your_key -- npx -y vaemail mcp

# Any MCP client
npx -y vaemail mcp

或者使用配置块：

{
  "mcpServers": {
    "vaemail": {
      "command": "npx",
      "args": ["-y", "vaemail", "mcp"],
      "env": { "VAEMAIL_API_KEY": "swm_your_key" }
    }
  }
}

GET /api/v1/me 会识别租户、密钥前缀、作用域和 mode，但不会返回密钥。联系人操作接受租户内唯一的 external_reference，用于 CRM 标识符和插入或更新操作。

集成测试请使用沙盒 API 密钥：读取操作正常执行，而每项写入都会在始终回滚的事务中验证。不会生成任何行、任务、电子邮件、SMS、webhook 或出站 HTTP 调用，也不会存储幂等键。沙盒写入响应会在 JSON 对象中包含 X-VaEmail-Sandbox: 1 和 sandbox: true。沙盒响应绝不能作为电子邮件已送达的证据。

检查是否已正确配置：

npx vaemail init

工具

工具	功能
vaemail_preparer_envoi	准备新闻简报草稿，解析邮件列表，可选择发送测试邮件，并返回摘要和一次性确认令牌。绝不会发送或安排发送。
vaemail_confirmer_envoi	在获得明确的人工确认后，使用令牌执行已安排或立即发送的新闻简报。此操作具有破坏性。
vaemail_ou_en_est_ma_campagne	用简明语句说明营销活动进度：已安排、发送中、已发送、打开次数、点击次数。
vaemail_qui_est_abonne	按文件夹列出订阅者数量，或列出某个地址所在的邮件列表及其状态。
vaemail_importer_contacts	将联系人添加到邮件列表（若不存在则创建）。绝不会重新订阅已取消订阅的地址。
vaemail_capabilities	查看服务支持的功能。无需 API 密钥。
vaemail_send_email	将事务性电子邮件加入队列并返回其 ID。
vaemail_validate_email	试运行：检查邮件是否会发出，以及哪些因素会阻止发送。
vaemail_get_message	查看一封邮件的投递状态和所有事件。
vaemail_list_messages	查看最近的邮件，可按状态、标签或收件人筛选。
vaemail_list_domains	查看发信域名及实时 SPF、DKIM 和 DMARC 状态。
vaemail_create_domain	声明一个域名，并返回要发布的 DNS 记录。
vaemail_verify_domain	重新读取 DNS，并报告已验证的内容。
vaemail_dns_requirements	查看已声明域名仍需配置的记录。
vaemail_diagnose_deliverability	诊断邮件送达不佳的原因，并提供解决问题的操作。
vaemail_list_bounces	查看已被排除在发送之外的地址及原因。
vaemail_get_usage	查看配额、密钥的每日上限以及剩余量。
vaemail_get_audit_log	查看此密钥执行过的操作，以便准确报告。

vaemail_confirmer_envoi 和 vaemail_send_email 均标记为 destructiveHint: true：向外部发送邮件无法撤销。新闻简报确认保护适用于立即发送；草稿和已安排的营销活动仍保持原有行为。

旨在防止的问题

Agent 的失败方式与人不同。它会重试，不会查看仪表板，还会根据 200 报告成功。API 围绕这一点设计：

• 发送请求已受理，不代表已送达。 vaemail_send_email 返回 202 和一个 ID。只有 vaemail_get_message 才能说明邮件的最终状态。工具描述中明确说明了这一点，因此 Agent 不会宣称邮件已送达，而它其实无从知晓。
• 重试不会造成重复发送。 传入 idempotency_key，重复调用会在 24 小时内重放首次响应，而不是再次发送。
• 错误会说明该怎么做。 每个失败都会包含稳定的 code、是否可重试，以及纠正措施和执行该操作的端点。
• 密钥权限有上限。 包括作用域、每日发送上限、每封邮件的收件人数量上限，以及发件人域名允许列表。Agent 的操作不会超出密钥权限。
• 每次调用都会记录日志。 使用了哪个密钥、执行了哪个操作、传入了哪些参数、结果是什么——不包括邮件正文。自主运行，但有据可查。
• 需要人工操作的步骤会明确标出。 发布 DNS 记录就是其中之一。如果记录的值仍包含占位符，则会标记为 publishable: false，因为发布它会破坏域名的身份验证。

CLI

vaemail init                          # check config, print the MCP snippet
vaemail capabilities                  # what the service can do (no key needed)
vaemail send --to [email protected] --subject Hi --html '<p>Hello</p>'
vaemail status 42                     # delivery status of a message
vaemail domains:add exemple.fr        # declare a domain, print DNS records
vaemail doctor                        # why is my email not arriving?
vaemail usage                         # quota and remaining allowance
vaemail mcp                           # run the MCP server on stdio

在任何命令中添加 --json，即可获取机器可读的输出。

将其用作库

MCP 服务和 CLI 使用的同一客户端也已导出，因此应用程序可以直接调用 VaEmail。无需依赖项。

import { VaEmail } from 'vaemail';

const client = new VaEmail({ apiKey: process.env.VAEMAIL_API_KEY });

await client.send(
  {
    to: '[email protected]',
    subject: 'Your order is on its way',
    html: '<p>Tracking number: 1Z999</p>',
  },
  'order-4711', // idempotency key: safe to replay for 24 hours
);

错误会说明下一步该怎么做，而不只是返回状态码：

try {
  await client.send({ to: '[email protected]' });
} catch (error) {
  error.code;        // DOMAIN_NOT_VERIFIED
  error.retryable;   // false
  error.pourAgent(); // reason, corrective action, whether to retry
}

此外还提供：capabilities()、health()、validate()、getMessage()、 listMessages()、listDomains()、addDomain()、verifyDomain()、 dnsRecords()、diagnoseDeliverability()、listSuppressions()、 removeSuppression()、usage()、auditLogs()。

连接 Stripe

使用 rk_live_ 或 rk_test_ Stripe 受限密钥，并授予 Customers 读取权限和 Webhook Endpoints 写入权限。sk_ 秘密密钥会被拒绝。VaEmail 不会返回任何 Stripe 密钥：连接状态仅显示密钥和 webhook token 的最后四个字符。

REST 路由：

• GET /api/v1/integrations/stripe：读取连接状态；
• POST /api/v1/integrations/stripe：创建或协调 webhook，并传入 {"api_key":"rk_live_..."}，同时使用 settings.write 作用域；
• DELETE /api/v1/integrations/stripe：删除 Stripe webhook，然后删除本地连接。 此操作不可撤销，必须由人工明确确认。

Stripe 会调用 POST /api/v1/webhooks/stripe/{token}。此公共路由会验证 Stripe-Signature，不会接收 VaEmail API 密钥。

支持的事件和自动化触发器：

Stripe 事件	VaEmail 触发器
invoice.payment_failed	stripe_payment_failed（payment_failed）
customer.subscription.created	stripe_subscription_created（subscription_created）
customer.subscription.deleted	stripe_subscription_deleted（subscription_deleted）
checkout.session.completed	stripe_checkout_completed（checkout_completed）

也提供具有相同功能的 Python SDK：pip install vaemail （https://github.com/vaemail/vaemail-python）。

环境变量

变量	含义
VAEMAIL_API_KEY	账户 API 密钥。在仪表板的“API 密钥”下创建。
VAEMAIL_BASE_URL	API 基础 URL。默认为 https://app.vaemail.fr。

另有以下资源

• OpenAPI 规范：https://app.vaemail.fr/openapi.json
• 功能端点：https://app.vaemail.fr/api/v1/capabilities
• Agent 文档：https://vaemail.fr/agents

技能和示例

• Agent 技能（Agent 在首次调用前应遵循的规则）：npx skills add vaemail/skills，源码：https://github.com/vaemail/skills
• curl、Node、Python、Claude Code、Codex、OpenAI Agents、LangChain、CrewAI 和 n8n 的示例：https://github.com/vaemail/examples
• 注册表条目：io.github.vaemail/vaemail（参见 server.json）

依赖项

无。内置 fetch 需要 Node 18+，除此之外别无所需——Agent 自行安装的软件包不应附带一整套依赖树。

许可证

MIT