sendgrid-email-log

SendGrid メールログ

Email Logs API を使用して、特定の SendGrid メッセージのアクティビティを取得します。

目的

このスキルは、SendGrid Email Logs とメッセージごとのアクティビティを読み取るためのものです。

検索方法は 2 つあります。

• 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 を呼び出し、宛先、ステータス、時刻、任意の件名、raw query、およびあいまい一致によるメッセージ ID 検索で Email Logs を検索します。

入力：

• ID による直接検索には SendGrid Email Logs の完全な sg_message_id、または検索してから詳細を取得する方法には、宛先、送信者、送信時刻、件名、ステータス、開始／終了時刻、raw query、任意の Mail Send message_id など、役立つ Email Logs の検索フィルター
• --api-key、SENDGRID_API_KEY、またはローカルに保存された SendGrid キーから取得する SendGrid API キー

出力：

• デフォルトでは 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、または Email Logs の宛先と送信時刻の検索条件
• 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、または raw query）をできるだけ多く集め、まず get_email_log.sh で完全な sg_message_id を特定します。
2. 個別の curl コマンドよりも、scripts/get_email_log.sh または scripts/query_email_logs.sh を優先して使用します。
3. SendGrid を呼び出す前に URL を確認したい場合は、--dry-run を使用します。
4. --api-key、SENDGRID_API_KEY、またはローカルに保存されたキーをスクリプトに使用させます。
5. 非対話形式のエージェント実行では、サポートされているすべての場所に API キーがない場合、すぐに失敗させます。
6. 指定があれば生の JSON を返し、それ以外の場合は event_summary、一致したメッセージ、または最近のアクティビティイベントを要約します。

コマンド

1 件のメッセージを確認する

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 をユーザーが持っていて、まず Email Logs の sg_message_id を特定する必要がある場合に使用します。get_email_log.sh は、デフォルトで to_email と sg_message_id_created_at >= (--sent-at - 5 seconds) を使って Email Logs を絞り込み、必要に応じて完全一致の subject フィルターを追加します。次に、返された messages[].sg_message_id を Mail Send の応答の x-message-id とあいまい照合し、その後 GET /v3/logs/{sg_message_id} で詳細レコードを取得します。

ユーザーがメッセージ ID を知らない場合は、--message-id を省略します。スクリプトは指定されたフィルターを適用した後、最初に返された Email Logs のメッセージを使用するため、曖昧さを避けるにはフィルターを追加してください。

動的テンプレートを使って送信する場合は、テンプレートで最終的なメールの件名を定義または上書きできるため、--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 を指定せずに Email Logs を検索してから、詳細を取得する

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

生のクエリで Email Logs を検索する

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}
• EU リージョン：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 で 1 件のメッセージを読み取ります。

検索では、スクリプトは次の宛先に POST リクエストを送信します。

• グローバルリージョン：https://api.sendgrid.com/v3/logs
• EU リージョン：https://api.eu.sendgrid.com/v3/logs

サポートされるボディフィールド：

• query
• limit
• 任意の subusers

Email Logs のクエリには 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キーをファイル権限600で~/.config/sendgrid-send-email/api_keyにローカル保存できます。キーの値をユーザーに表示しないでください。
• 保存済みのキーを更新する場合は、ユーザーに--api-key <key> --save-api-keyまたは--configure-api-keyを使用してもらいます。削除する場合は--clear-api-keyを使用します。
• ユーザーがMail Sendのx-message-idしか持っていない場合、送信結果だけではGET /v3/logs/{sg_message_id}に必要な情報が不足している可能性があります。スクリプトが最初にPOST /v3/logsで完全なEmail Logs sg_message_idを特定してから詳細を取得するよう、scripts/get_email_log.sh --to ... --sent-at ... --message-id ...の使用を推奨してください。
• ユーザーがメッセージIDを知らない場合は、--to、--from、--start-time、--end-time、--subject、--statusなど複数のフィルターを指定してscripts/get_email_log.shを使用します。スクリプトは最初に一致した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のイベントタイムラインを取得して」
• 「このメールがdelivered／opened／clickedになったか見て」

英語

• 「このSendGridメールが開封またはクリックされたか確認して」
• 「このsg_message_idのSendGrid Email Logsアクティビティを取得して」
• 「このSendGridメッセージのイベントタイムラインを取得して」