email

トランザクションメール運用（SendGrid）

このスキルは、Twilio SendGrid を通じたトランザクションメールの送信と、配信に関する問題（バウンス、迷惑メールの苦情、署名付きイベント Webhook）の診断に使用します。これは、1 つのベンダー（SendGrid）を対象とするツールスキルです。マーケティングキャンペーン、テンプレートビルダー、その他のプロバイダーは対象外です。このスキルは、アプリケーションがトリガーするメールの運用サイクル（送信、配信確認、イベントの真正性検証）を担当します。

運用上の契約

1. 変更を加える前に、読み取り専用で調査します。 バウンスや迷惑メールの報告など、配信可能性に関するシグナルは自由に確認できます。付属の email-cli スクリプトによる読み取りでは、何も書き込みません。
2. 実行前に対象、範囲、ロールバック方法を確認します。 メールを送信すると、組織名義のメッセージが受信者の受信トレイに届きます。そのため、受信者、送信者、内容を明示した人間による指示に加え、email-cli を使った --dry-run によるプレビューと --yes による確認が必要です。配信済みメールを確実に「取り消す」方法はありません。
3. 読み取りの範囲を守ります。 抑制リストの表示件数は --limit で制限し、タスクに必要な範囲を超えてページを取得しないでください。
4. Webhook を信頼する前に検証します。 SendGrid の署名付きイベント Webhook はすべてのリクエストに署名します。イベントデータに基づいて処理する前に、ECDSA 署名とタイムスタンプを検証してください。Webhook エンドポイントを検証しないままにすると、偽造された配信イベントやバウンスイベントを受け入れてしまいます。
5. 証拠の共有は必要最小限にします。 メッセージの短いプレビューとメールアドレスのみを引用し、API キー、メッセージ本文全体、抑制リストをチャットに貼り付けないでください。
6. 指示なしに未検証のアドレスや実際のユーザーへメールを送信しないでください。 配信可能性の調査目的での読み取りは安全ですが、送信は常に確認を必須とします。

email-cli スクリプト

scripts/email-cli は SendGrid v3 API 用のエージェント向け、標準ライブラリのみを使用する CLI です。サードパーティの暗号ライブラリに依存しない、自己完結型の ECDSA P-256 署名検証機能を備えています。

email/scripts/email-cli --help                              # no key or network needed
email/scripts/email-cli --json --limit 20 deliverability bounces
email/scripts/email-cli --json --limit 20 deliverability spam-reports
email/scripts/email-cli send --to [email protected] --from [email protected] \
  --subject "Password reset" --body "..." --dry-run          # preview only
email/scripts/email-cli send --to [email protected] --from [email protected] \
  --subject "Password reset" --body "..." --yes              # confirmed send
email/scripts/email-cli webhook verify --body-file body.json \
  --signature "MEUC..." --timestamp 1712345678 --public-key-file public-key.pem

終了コード：0 は成功、1 は API エラーまたは検証失敗、2 は使用方法のエラーです。送信にはガードが設けられています。--dry-run または --yes が指定されていない場合、スクリプトは終了コード 1 で拒否し、API を呼び出しません。読み取り件数は --limit（既定値 20、最大 100）で制限されます。

運用サイクル

1. 配信に関する質問の範囲を定めます：送信（変更）でしょうか、それとも配信可能性の調査（読み取り）でしょうか。送信者、受信者、内容を確認します。
2. 範囲を限定して読み取ります：deliverability bounces と deliverability spam-reports を実行し、誰に届かなかったか、その理由を確認します。
3. シグナルをトリアージします：証拠を原因に対応付けます（ハードバウンス → 不正なアドレスまたは入力ミス、迷惑メールの苦情 → 内容または頻度の問題、抑制リスト → 過去のバウンス）。SendGrid のイベント Webhook ペイロードから配信イベントやバウンスイベントを確認します。その際、署名を検証してから確認してください。
4. 確認を得て実行します：人間から送信の指示があった場合に限り、--dry-run でプレビューし、--yes で確定します。
5. 検証します：送信レスポンス（x-message-id）を確認し、その後、配信イベントの Webhook や API の証拠から配信を確認します。確認せずに成功と判断しないでください。

トランザクションメールの送信

• メッセージを作成します：検証済みの送信者（from）、1 人以上の宛先（to）、subject、プレーンテキストの body、必要に応じて html 本文を指定します。SendGrid では、送信元アドレスがアカウントで検証済みの送信者 ID である必要があります。
• 送信前にプレビューします：--dry-run は送信元、宛先、件名、本文のプレビューを正確に表示し、API を呼び出しません。--yes は確認後に POST /v3/mail/send を実行します。このエンドポイントは x-message-id ヘッダーとともに 202 Accepted を返します。
• 秘密情報やトークンをメールで送信しないでください。 メールは情報漏えいの経路です。パスワードリセットリンクは問題ありませんが、認証情報そのものは送信しないでください。
• SendGrid が返す 202 は受け付けられたことを示すものであり、配信を意味するものではありません。成功と判断する前に、イベント Webhook またはアクティビティフィードで配信を確認してください。

配信状況の確認

• バウンス（GET /suppression/bounces）：メールがバウンスした宛先と、その理由およびステータスです。ハードバウンス（5.x.x の恒久的なエラー）は無効なアドレスを示します。バウンスが繰り返されると、送信者の評価が下がります。
• スパム報告（GET /suppression/spam_reports）：メールをスパムとして報告した宛先です。苦情が頻繁に寄せられる場合は、コンテンツまたはターゲティングに問題があることを示します。
• 配信状況のトリアージは読み取り専用です。抑制リストと Webhook イベントから原因を調べ、その後、確認を得たうえで次回の送信（変更を伴う操作）のみを変更してください。

Webhook 署名の検証

SendGrid の Signed Event Webhook は、ECDSA 鍵ペアを使って各リクエストに署名します。検証手順は次のとおりです。

1. リクエスト本文の正確な生バイト列を取得します。再エンコードすると署名が無効になります。
2. X-Twilio-Email-Event-Webhook-Timestamp が新しい値であることを確認します（リプレイ攻撃対策。email-cli のデフォルトの有効期間は 300s で、--max-age 0 で無効にできます）。
3. timestamp + raw body（区切り文字なしでバイト列を連結）の SHA-256 を計算し、Webhook の公開鍵に対して ECDSA P-256 署名（X-Twilio-Email-Event-Webhook-Signature、base64 デコードした ASN.1 DER）を検証します。
4. タイムスタンプが古い場合、または署名が検証できない場合は、401 で拒否します。

email-cli webhook verify --body-file body.json --signature <header> --timestamp <header> --public-key-file public-key.pem は、標準ライブラリのみを使った P-256 実装で、この検証をそのまま実行します。公開鍵は Signed Webhook を有効にすると Event Webhook の設定に表示されます。コードに含めず、ファイルとして保存してください。

参照先の使い分け

次の場合に参照	参照先
ソース、更新手順	references/00-source-index.md
API の範囲、Webhook 検証の詳細、配信状況の意味	references/01-sendgrid-operations.md

含まれる成果物

• scripts/email-cli：範囲を限定した標準ライブラリのみの CLI（送信、配信状況のバウンス／スパム報告、自己完結型 ECDSA P-256 による Webhook 検証。--json、--limit に対応。送信は --dry-run／--yes が必要です）。
• tests/test_email_cli.py：スタブ SendGrid API と OpenSSL で生成した ECDSA Webhook テストベクトルを使う、決定的なテスト 15 件（検証機能を独立して照合します）。
• references/：日付付きソースインデックスと SendGrid 運用リファレンス。
• evals/evals.json：エージェント実行の出力品質を評価する 6 件のケース。

検証の境界

主張	最低限必要な証拠
メッセージが受け付けられた	email-cli send --yes が終了コード 0 で終了し、x-message-id を返す
宛先でバウンスが発生した	email-cli deliverability bounces --json に、理由とステータスを含むアドレスが表示される
Webhook が正規のものである	正確な本文／署名／タイムスタンプに対して email-cli webhook verify が verified: true で終了コード 0 を返す
実際に配信された	検証済みの配信 Webhook イベント、またはメッセージが配信済みと示すアクティビティフィード

厳守事項

• 人間からの指示、--dry-run によるプレビュー、--yes による確認なしにメールを送信しないでください。送信済みメールは取り消せず、外部に送信され、受信者の受信トレイに届きます。
• ECDSA 署名とタイムスタンプの検証なしに、受信した Webhook を信頼しないでください。
• --limit を超えて読み取りをページングしないでください。メッセージ本文全体、API キー、抑制リストをチャットに出力しないでください。
• このスキルの対象は SendGrid のトランザクションメールのみです。マーケティングキャンペーン、テンプレートシステム、その他のプロバイダーは対象外です。

使用しない場合

• マーケティングメールまたは一括メールキャンペーン（SendGrid Marketing Campaigns、セグメンテーション、一斉送信）— これは独自のツールを使用する別の製品領域です。
• その他のメールプロバイダー（Postmark、SES、Mailgun、Resend）— それぞれ独自の API があり、このスキルの対象は SendGrid です。
• 組織規模でのメール配信戦略やドメイン評価ポリシーの策定 — これは運用ポリシーに関する作業です。このスキルは SendGrid の機能を操作します。
• アプリケーションへのメール機能の実装（テンプレートのレンダリング、トランザクションフロー）— これはアプリケーション開発です。backend-engineering を参照してください。