sendgrid-email-log

SendGrid 邮件日志

使用 Email Logs API 检索特定 SendGrid 邮件的活动记录。

用途

此技能用于读取 SendGrid 邮件日志和单封邮件的活动记录。

它有两种查询方式：

• scripts/get_email_log.sh 调用 GET /v3/logs/{sg_message_id} 查询一封特定邮件，并计算 event_summary。如果不知道完整的 sg_message_id，它可以先调用 POST /v3/logs，通过收件人和发送时间解析完整 ID，然后自动调用详情端点。
• scripts/query_email_logs.sh 调用 POST /v3/logs，通过收件人、状态、时间、可选主题、原始查询和模糊匹配的邮件 ID 搜索邮件日志。

输入：

• 用于按 ID 直接查询的 SendGrid 邮件日志完整 sg_message_id，或搜索邮件日志时可用的筛选条件，例如收件人、发件人、发送时间、主题、状态、开始/结束时间、原始查询，以及可选的 Mail Send message_id，用于先搜索再查询详情
• SendGrid API 密钥，可通过 --api-key、SENDGRID_API_KEY 或本地保存的 SendGrid 密钥提供

输出：

• 默认返回原始 SendGrid JSON
• 脚本可选添加 event_summary，其中包含 opened、clicked、delivered、bounced、deferred、dropped、spam_reported 和 unsubscribed 等布尔值
• 当 get_email_log.sh 在获取详情前解析完整 sg_message_id 时，返回 log_resolution
• 直接使用 query_email_logs.sh 和 --message-id 时，返回 matched_messages、matched_count 和 _match_reason
• 提供 --output 时，可选保存 JSON 文件
• 使用 --dry-run 时，返回试运行请求元数据

此查询为只读操作，不会发送邮件，也不会检索账户级汇总统计数据。

此技能需要

• 完整的 sg_message_id，或用于搜索邮件日志的收件人和发送时间条件
• 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/get_email_log.sh --api-key "SG..." --save-api-key

也可以通过以下命令清除密钥：

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

执行顺序

1. 对于按 ID 直接查询，提取完整的 sg_message_id。如果用户只有 Mail Send x-message-id、ID 不完整或不知道 ID，请收集尽可能多的搜索筛选条件（to、from、sent_at、subject、status、start_time、end_time 或原始 query），并让 get_email_log.sh 先解析完整的 sg_message_id。
2. 优先使用 scripts/get_email_log.sh 或 scripts/query_email_logs.sh，而不是临时使用 curl。
3. 如果用户想在调用 SendGrid 前查看 URL，请使用 --dry-run。
4. 让脚本使用 --api-key、SENDGRID_API_KEY 或本地保存的密钥。
5. 在非交互式 Agent 运行中，如果所有受支持来源都缺少 API 密钥，则立即失败。
6. 用户需要时返回原始 JSON；否则，概述 event_summary、匹配的邮件或最近的活动事件。

命令

检查一封邮件

bash <skill-path>/scripts/get_email_log.sh \
  --sg-message-id "abc123.recvd-xxxxxxxx"

检查邮件是否已打开或点击

bash <skill-path>/scripts/get_email_log.sh \
  --sg-message-id "abc123.recvd-xxxxxxxx" \
  --summary-only

按收件人、发送时间和模糊匹配的消息 ID 搜索电子邮件日志

当用户拥有 Mail Send 返回的 x-message-id，但需要先找到电子邮件日志中的 sg_message_id 时使用此方法。get_email_log.sh 使用 to_email 和默认值为 (--sent-at - 5 seconds) 的 sg_message_id_created_at >= 缩小电子邮件日志的搜索范围，可选择添加精确的 subject 筛选条件；随后将返回的 messages[].sg_message_id 与 Mail Send 响应中的 x-message-id 进行模糊匹配，最后通过 GET /v3/logs/{sg_message_id} 获取详细记录。

如果用户不知道任何消息 ID，请省略 --message-id；脚本会在应用所提供的筛选条件后，使用电子邮件日志中返回的第一条消息，因此请传入更多筛选条件以避免结果不明确。

对于动态模板发送，请省略 --subject，因为模板可以定义或覆盖最终的电子邮件主题。

bash <skill-path>/scripts/get_email_log.sh \
  --to "[email protected]" \
  --sent-at "2026-06-15T10:37:21Z" \
  --message-id "abc123..." \
  --limit 100

不提供消息 ID 搜索电子邮件日志，然后获取详细信息

bash <skill-path>/scripts/get_email_log.sh \
  --to "[email protected]" \
  --from "[email protected]" \
  --start-time "2026-06-15T10:00:00Z" \
  --end-time "2026-06-15T11:00:00Z" \
  --subject "Order update" \
  --status delivered \
  --limit 20

使用原始查询搜索电子邮件日志

当用户只需要 POST /v3/logs 的搜索结果，而不需要调用详细信息端点时，使用此底层脚本。

bash <skill-path>/scripts/query_email_logs.sh \
  --query "to_email = '[email protected]' AND status IN ('delivered', 'processed')" \
  --limit 10

父账号查询子用户或客户账号

bash <skill-path>/scripts/get_email_log.sh \
  --sg-message-id "abc123.recvd-xxxxxxxx" \
  --on-behalf-of "subuser-username"

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

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

试运行请求元数据

bash <skill-path>/scripts/get_email_log.sh \
  --sg-message-id "abc123.recvd-xxxxxxxx" \
  --dry-run

固定请求格式

按 ID 查询活动记录时，脚本会向以下地址发送 GET 请求：

• 全球区域：https://api.sendgrid.com/v3/logs/{sg_message_id}
• 欧盟区域：https://api.eu.sendgrid.com/v3/logs/{sg_message_id}

支持的标头：

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

请勿臆造查询参数。此端点通过 URL 路径按 ID 读取一条消息。

搜索查询时，脚本会向以下地址发送 POST 请求：

• 全球区域：https://api.sendgrid.com/v3/logs
• 欧盟区域：https://api.eu.sendgrid.com/v3/logs

支持的请求体字段：

• query
• limit
• 可选的 subusers

请勿在电子邮件日志查询中使用 custom_args.business_id。请使用收件人、可选的主题、--sent-at 和消息 ID 模糊匹配，或传入账号支持的原始 --query。

脚本选项

• --sg-message-id ID；完整的 SendGrid Email Logs ID，用于直接检索活动记录
• --to EMAIL；用于解析完整 sg_message_id 的收件人邮箱
• --from EMAIL；用于解析完整 sg_message_id 的发件人邮箱
• --sent-at ISO_TIME；用于解析完整 sg_message_id 的发送／排队时间下限
• --message-id ID；可选的 Mail Send x-message-id，用于解析时进行模糊匹配
• --subject SUBJECT；解析时可选的精确主题筛选条件
• --status STATUS；可选的状态筛选条件，可重复指定或用逗号分隔
• --start-time ISO_TIME；解析搜索时可选的时间下限
• --end-time ISO_TIME；解析搜索时可选的时间上限
• --query QUERY；用于解析搜索的原始 SendGrid Email Logs 查询字符串，会覆盖生成的筛选条件
• --sent-at-lookback-seconds N；默认值为 5，允许范围为 0-300
• --limit N；解析时的搜索结果数量上限，默认值为 100，允许范围为 1-1000
• --on-behalf-of VALUE；可选的 SendGrid 主账户标头值
• --subuser ID；用于 POST /v3/logs 搜索的可选数字型 SendGrid 子用户 ID，可重复指定或用逗号分隔
• --region global|eu；默认值为 global
• --api-key KEY 用于一次性覆盖
• --save-api-key 用于保存 --api-key 的值，供以后运行使用
• --configure-api-key 用于提示输入并保存密钥
• --clear-api-key 用于移除本地保存的密钥
• --output PATH 用于保存 JSON
• --summary-only 仅打印计算得出的事件摘要
• --dry-run 打印请求元数据，但不调用 SendGrid

scripts/query_email_logs.sh 支持：

• --query QUERY；原始 SendGrid Email Logs 查询字符串
• --status STATUS；可重复指定或用逗号分隔
• --to EMAIL
• --sent-at ISO_TIME
• --sent-at-lookback-seconds N；默认值为 5，允许范围为 0-300
• --message-id ID；对返回的 sg_message_id 进行模糊匹配
• --subject SUBJECT
• --start-time ISO_TIME
• --end-time ISO_TIME
• --limit N；默认值为 10，允许范围为 1-1000
• --subuser ID
• 通用选项：--region、--api-key、--save-api-key、--configure-api-key、--clear-api-key、--output 和 --dry-run

说明

• 切勿在用户可见的输出中回显或存储 API 密钥。
• 脚本可以将 API 密钥保存在本地的 ~/.config/sendgrid-send-email/api_key，文件权限为 600；切勿将密钥值打印给用户。
• 用户想要更新已保存的密钥时，使用 --api-key <key> --save-api-key 或 --configure-api-key。用户想要移除密钥时，使用 --clear-api-key。
• 如果用户只有 Mail Send x-message-id，发送结果可能无法满足 GET /v3/logs/{sg_message_id} 的查询需求。优先使用 scripts/get_email_log.sh --to ... --sent-at ... --message-id ...，让脚本先通过 POST /v3/logs 解析完整的 Email Logs sg_message_id，再获取详情。
• 如果用户不知道任何消息 ID，使用带多个筛选条件的 scripts/get_email_log.sh，例如 --to、--from、--start-time、--end-time、--subject 和 --status；脚本会选取第一条匹配的 Email Logs 消息，因此请使用范围较窄的筛选条件。
• 如果 query_email_logs.sh 未返回数据或未找到模糊匹配的 sg_message_id，请引导用户前往 https://app.sendgrid.com/email_logs 手动查看。
• 如果 --api-key、SENDGRID_API_KEY 和本地保存的密钥均缺失，请告知用户阅读 https://frevana.gitbook.io/frevana-docs/email-integrations/sendgrid-integration，以获取所需配置。
• 如果用户在聊天中分享了 API 密钥，请建议其更换密钥。

示例提示词

中文

• “查一下这封 SendGrid 邮件有没有打开或点击，sg_message_id 是……”
• “获取这个 SendGrid message id 的事件时间线”
• “看下这封邮件是否已送达／打开／点击”

英文

• “检查这封 SendGrid 邮件是否被打开或点击”
• “获取此 sg_message_id 对应的 SendGrid Email Logs 活动记录”
• “获取这封 SendGrid 邮件的事件时间线”