sendgrid-global-email-stats

SendGrid 全球电子邮件统计数据

从 SendGrid Stats API 获取全局电子邮件统计数据。

用途

此技能通过调用 GET /v3/stats，用于读取 SendGrid 电子邮件活动的汇总指标。

输入：

• start_date，格式为 YYYY-MM-DD
• 可选的 end_date，格式为 YYYY-MM-DD
• 可选的聚合级别：day、week 或 month
• 可选的 limit 和 offset
• SendGrid API 密钥，来自 --api-key、SENDGRID_API_KEY 或本地保存的 SendGrid 密钥

输出：

• 默认返回原始 SendGrid JSON 统计数据
• 提供 --output 时，可选择保存为 JSON 文件
• 使用 --dry-run 时，返回请求元数据

这是只读统计查询，不会发送电子邮件，也不会查询单封邮件的 Email Logs。

此技能所需内容

• start_date
• SendGrid API 密钥，通常为 SENDGRID_API_KEY
• curl
• bash
• python3

API 密钥的解析顺序：

1. 当前运行使用的 --api-key
2. SENDGRID_API_KEY
3. 本地保存的密钥 ~/.config/sendgrid-send-email/api_key

保存的密钥路径有意与 sendgrid-send-email 保持一致，因此配置过 SendGrid 发送技能的用户可以重复使用同一个密钥。如果没有可用的 API 密钥，且脚本以交互方式运行，则提示一次并将其保存到本地，供后续运行使用。如果在非交互式运行中没有可用的 API 密钥，请引导用户阅读 SendGrid 集成指南：https://frevana.gitbook.io/frevana-docs/email-integrations/sendgrid-integration。

用户可以使用以下命令更新保存的 API 密钥：

bash <skill-path>/scripts/retrieve_global_email_stats.sh --api-key "SG..." --save-api-key

也可以使用以下命令清除：

bash <skill-path>/scripts/retrieve_global_email_stats.sh --clear-api-key

执行顺序

1. 提取 start_date、可选的 end_date、可选的 aggregated_by、可选的分页参数、可选的 on_behalf_of 和可选的区域。
2. 优先使用 scripts/retrieve_global_email_stats.sh，而非临时编写 curl 命令。
3. 如果用户想在调用 SendGrid 前检查 URL，请使用 --dry-run。
4. 让脚本使用 --api-key、SENDGRID_API_KEY 或本地保存的密钥。
5. 在 Agent 的非交互式运行中，如果所有受支持来源均缺少 API 密钥，则立即失败。
6. 根据用户的要求，返回原始 JSON 负载，或汇总 requests、processed、delivered、bounces、opens、unique_opens、clicks、unique_clicks、spam_reports 和 unsubscribes 等指标。

命令

获取每日统计数据

bash <skill-path>/scripts/retrieve_global_email_stats.sh \
  --start-date "2026-06-01" \
  --end-date "2026-06-30" \
  --aggregated-by day

获取每月统计数据

bash <skill-path>/scripts/retrieve_global_email_stats.sh \
  --start-date "2026-01-01" \
  --end-date "2026-06-30" \
  --aggregated-by month

父账户查询子用户数据

bash <skill-path>/scripts/retrieve_global_email_stats.sh \
  --start-date "2026-06-01" \
  --end-date "2026-06-30" \
  --on-behalf-of "subuser-username"

对于客户账户，请传递完整的标头值，例如：

--on-behalf-of "account-id 123456"

试运行请求元数据

bash <skill-path>/scripts/retrieve_global_email_stats.sh \
  --start-date "2026-06-01" \
  --aggregated-by week \
  --dry-run

固定请求格式

脚本会向以下地址发送 GET 请求：

• 全局区域：https://api.sendgrid.com/v3/stats
• EU 区域：https://api.eu.sendgrid.com/v3/stats

支持的查询参数：

• start_date；必填，格式为 YYYY-MM-DD
• end_date；可选，格式为 YYYY-MM-DD，省略时默认为 SendGrid 中的当天日期
• aggregated_by；可选，可取 day、week、month 之一
• limit；可选，整数
• offset；可选，整数

支持的标头：

• Authorization: Bearer <SENDGRID_API_KEY>
• 可选的 on-behalf-of: <subuser-username> 或 on-behalf-of: account-id <account-id>

不要臆造或传递不受支持的查询参数。

脚本选项

• --start-date YYYY-MM-DD；获取统计数据时必填
• --end-date YYYY-MM-DD；可选
• --aggregated-by day|week|month；可选
• --limit N；可选，正整数
• --offset N；可选，非负整数
• --on-behalf-of VALUE；可选的 SendGrid 父账户标头值
• --region global|eu；默认为 global
• --api-key KEY，用于一次性覆盖
• --save-api-key，将 --api-key 的值保存下来，供后续运行使用
• --configure-api-key，提示输入密钥并保存
• --clear-api-key，删除本地保存的密钥
• --output PATH，保存 JSON
• --dry-run，打印请求元数据，但不调用 SendGrid

注意事项

• 切勿在用户可见的输出中回显或存储 API 密钥。
• 脚本可以将 API 密钥以文件权限 600 保存到本地 ~/.config/sendgrid-send-email/api_key；切勿将密钥值打印给用户。
• 用户想更新已保存的密钥时，使用 --api-key <key> --save-api-key 或 --configure-api-key。用户想移除密钥时，使用 --clear-api-key。
• start_date 和 end_date 必须采用 YYYY-MM-DD 格式。
• aggregated_by 必须是 day、week 或 month。
• 类别统计数据的可用期限有明确记录，为 13 个月；但此全局统计数据端点用于查询账户级全局统计数据，而非类别统计数据。
• 主账户可使用 --on-behalf-of，通过主账户 API 密钥查询子用户或客户账户。
• 如果 --api-key、SENDGRID_API_KEY 和本地保存的密钥都缺失，请告知用户阅读 https://frevana.gitbook.io/frevana-docs/email-integrations/sendgrid-integration，了解所需配置。
• 如果用户在聊天中分享了 API 密钥，建议他们更换该密钥。

示例提示词

中文

• “查一下 SendGrid 这个月每天的全局邮件统计”
• “用 SendGrid Stats API 查询 2026-06 的 delivered 和 bounces”
• “帮我 dry-run 一下 GET /v3/stats 的请求”

英文

• “查询 2026 年 6 月的 SendGrid 全局邮件统计”
• “获取 2026-06-01 至 2026-06-30 的每日 SendGrid 统计数据”
• “查看今年每月的 SendGrid 全局邮件统计”