用途:该技能用于读取 SendGrid 账户级全局邮件统计,调用 GET /v3/stats 获取聚合指标,不发送邮件,也不查询逐条 Email Logs。
主要能力:支持 start_date(必填,YYYY-MM-DD)、可选 end_date、可选 aggregated_by(day/week/month)、可选 limit 与 offset,以及 --on-behalf-of 查询子用户或客户账户。默认返回原始 JSON,可用 --output 保存文件,用 --dry-run 仅打印请求元数据。可汇总 requests、processed、delivered、bounces、opens、unique_opens、clicks、unique_clicks、spam_reports、unsubscribes 等指标。
使用方式:优先使用 scripts/retrieve_global_email_stats.sh。API 密钥解析顺序为 --api-key、SENDGRID_API_KEY、本地保存的 ~/.config/sendgrid-send-email/api_key。示例:bash <skill-path>/scripts/retrieve_global_email_stats.sh --start-date "2026-06-01" --end-date "2026-06-30" --aggregated-by day。保存密钥:--api-key "SG..." --save-api-key;清除:--clear-api-key。区域可选 global 或 eu,对应 https://api.sendgrid.com/v3/stats 与 https://api.eu.sendgrid.com/v3/stats。
适用场景:按日/周/月查看账户整体投递、打开、点击、退信、退订等趋势,或父账户代查子账户。
限制:需 curl、bash、python3;日期须为 YYYY-MM-DD,aggregated_by 仅限 day/week/month,不要传入不支持的查询参数。密钥缺失且非交互运行时直接失败,并引导阅读 https://frevana.gitbook.io/frevana-docs/email-integrations/sendgrid-integration。密钥不会回显,本地保存权限为 600;若用户在对话中泄露密钥,应建议轮换。该端点为账户级全局统计,不用于分类统计。