sendgrid-global-email-stats

SendGrid の全体メール統計

SendGrid の Stats API から全体のメール統計を取得します。

目的

このスキルは、GET /v3/stats を呼び出してSendGrid のメールアクティビティの集計指標を読み取るためのものです。

入力：

• YYYY-MM-DD 形式の start_date
• 任意の YYYY-MM-DD 形式の end_date
• 任意の集計レベル：day、week、month
• 任意の limit と offset
• --api-key、SENDGRID_API_KEY、またはローカルに保存された SendGrid キーから取得する SendGrid API キー

出力：

• デフォルトでは 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 キーがなく、スクリプトが対話形式で実行されている場合は、1 回だけ入力を求め、今後の実行に備えてローカルに保存します。非対話形式での実行時に 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. 場当たり的な curl よりも scripts/retrieve_global_email_stats.sh を優先します。
3. SendGrid を呼び出す前に URL を確認したい場合は、--dry-run を使用します。
4. スクリプトに --api-key、SENDGRID_API_KEY、またはローカルに保存されたキーを使用させます。
5. 非対話形式のエージェント実行では、サポート対象のすべてのソースに 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 か月の利用可能期間があります。ただし、このグローバル統計エンドポイントはアカウントレベルのグローバル統計用であり、カテゴリ統計用ではありません。
• 親アカウントは、親アカウントの API キーを使って --on-behalf-of を指定すると、サブユーザーまたは顧客アカウントのデータを照会できます。
• --api-key、SENDGRID_API_KEY、ローカルに保存されたキーのすべてがない場合は、必要な設定を取得するために https://frevana.gitbook.io/frevana-docs/email-integrations/sendgrid-integration を読むようユーザーに案内してください。
• ユーザーがチャットで API キーを共有した場合は、キーをローテーションするよう勧めてください。

プロンプト例

中国語

• 「SendGrid の今月の日別グローバルメール統計を確認してください」
• 「SendGrid Stats API を使って 2026-06 の delivered と bounces を照会してください」
• 「GET /v3/stats のリクエストをドライランしてください」

英語

• 「2026 年 6 月の SendGrid グローバルメール統計を取得してください」
• 「2026-06-01 から 2026-06-30 までの日別 SendGrid 統計を取得してください」
• 「今年の月別 SendGrid グローバルメール統計を確認してください」