list-email-templates

用途

该技能用于发现 SchemaVaults mail-server 目录中已注册的邮件模板。当需要通过 @schemavaults/send-email 的 sendEmail() 或 sendEmailToMailingList() 发送基于模板的邮件时，需要先获取模板 ID。由于模板目录会随时间变化，该技能有意不硬编码模板列表，而是始终查询实时目录。

适用时机

发送基于模板的邮件之前，用于查找正确的 template_id 并了解预期的 template_props 结构。
不确定某种通知类型是否存在对应模板时。
用户询问“有哪些可用的邮件模板？”时。

前置条件

必须设置 SCHEMAVAULTS_MAIL_API_KEY，即发送邮件时使用的同一 API 密钥。GET /api/templates 端点接受与 POST /api/send 相同的 bearer-token 认证。

使用方式

方式一：使用 listEmailTemplates() 辅助函数（推荐）

@schemavaults/send-email 包导出了 listEmailTemplates() 函数，它处理 API 密钥解析、环境感知的 URL 查找和响应解析，与 sendEmail() 遵循相同的约定：

import { listEmailTemplates } from "@schemavaults/send-email";

const templates = await listEmailTemplates();
// => [{ id: "welcome-email", description: "..." }, ...]

可选参数（均为可选）：

await listEmailTemplates({
  bearerToken: "svlts_mail_pk_...",   // 覆盖 SCHEMAVAULTS_MAIL_API_KEY
  environment: "development",         // 覆盖 SCHEMAVAULTS_APP_ENVIRONMENT
});

方式二：通过 CLI 从 shell 调用（一次性发现时推荐）

@schemavaults/send-email 附带一个 schemavaults-send-email 二进制文件，封装了相同的辅助函数。在已安装该包的任何仓库中运行：

bunx schemavaults-send-email list-templates              # JSON 输出（默认）
bunx schemavaults-send-email list-templates --format table  # 制表符分隔的 id<TAB>description

（如果没有 bun，可使用 npx schemavaults-send-email …。）CLI 从环境变量读取 SCHEMAVAULTS_MAIL_API_KEY，与辅助函数完全一致。可将 --format json 输出通过 jq 进行过滤，例如：

bunx schemavaults-send-email list-templates | jq '.[].id'

方式三：原始 HTTP

curl -sS \
  -H "Authorization: Bearer $SCHEMAVAULTS_MAIL_API_KEY" \
  https://<mail-server-origin>/api/templates

方式四：Claude Code 直接查询模板

在 Claude Code 会话中进行一次性发现时，优先使用上述 CLI——单条 shell 命令，无需脚本文件。仅当需要执行比打印目录更复杂的操作（例如获取 + 过滤 + 与另一数据源交叉引用）时，才回退到 /tmp/ 下的 Bun 脚本：

// /tmp/list-email-templates.ts
import { listEmailTemplates } from "@schemavaults/send-email";

const templates = await listEmailTemplates();
for (const t of templates) {
  console.log(`- ${t.id}: ${t.description}`);
}

从仓库根目录运行：

bun run /tmp/list-email-templates.ts

响应结构

{
  "success": true,
  "data": [
    {
      "id": "<template-id>",
      "description": "<human-readable blurb; usually documents the expected props shape>"
    }
  ]
}

每个条目包含一个 id（在 sendEmail() 或 sendEmailToMailingList() 中作为 template_id 原样传入）和一个 description，按约定该描述会说明预期的 template_props 结构。

如果描述对 props 结构表述不明确，可以：

(a) 传入 props，让服务器以 HTTP 400 拒绝格式错误的调用。

(b) 阅读 mail-server 仓库中该模板的源文件 src/lib/EmailTemplatesCatalog/email-template-refs/<id>.ts 以获取权威类型信息。

错误

状态码	错误	原因
401	Invalid or revoked API key.	SCHEMAVAULTS_MAIL_API_KEY 错误、过期或已撤销。
500	Failed to list email templates!	加载目录时发生意外的服务器端故障；重试或上报。

与 send-email-to-mailing-list 技能的关系

先使用本技能发现模板 ID，然后使用 send-email-to-mailing-list 技能（或直接使用 sendEmail() / sendEmailToMailingList()）发送邮件。如果没有任何已注册模板适合你的通知，则跳过模板发现，改用原始 text/html 形式。

选定模板后，使用相关发送 CLI 上的 --dry-run（bunx schemavaults-send-email send --dry-run … 或 send-to-mailing-list --dry-run …）验证 template_props 结构，而不是发送一封空白的真实邮件。服务器端 props 验证仅在 POST /api/send 上运行，因此 dry-run 是在不实际投递的情况下捕获 template_props 不匹配的唯一方式。