認証とセットアップ
Gmailの統合には、Google Cloud Platformを通じたOAuth 2.0認証が必要です。組織は、Google Cloud Consoleでプロジェクトを作成し、Gmail APIを有効化し、OAuth同意画面を設定する必要があります。この統合は、個人のGmailアカウントとGoogle Workspace（旧G Suite）エンタープライズアカウントの両方をサポートしています。認証トークンは安全に保存され、継続的なアクセスを維持するために自動的に更新されます。必要なAPIスコープ
- gmail.readonly: メールと設定への読み取り専用アクセスです。
- gmail.send: ユーザーに代わってメールを送信します。
- gmail.compose: 下書きメールを作成および管理します。
- gmail.modify: メールの読み取り、作成、送信、変更へのフルアクセスです。
- gmail.labels: メールラベルとカテゴリを管理します。
利用可能な操作
すべての必要な権限を設定すると、ツールキットは以下の操作を可能にします。メール管理
- Search Emails: Gmailクエリ構文（from:、to:、subject:、has:attachment、is:unreadなど）を使用した高度な検索を行います。
- Get Email Content: ヘッダー、本文（プレーンテキスト/HTML）、添付ファイルリストを含む完全なメールを取得します。
- Send Email: 複数の受信者、CC/BCC、添付ファイル、HTMLコンテンツを指定して新しいメールを作成および送信します。
- Reply to Email: 会話履歴とスレッドを維持して、既存のスレッドに返信します。
- Forward Email: オプションの追加コメント付きでメッセージを他の受信者に転送します。
- Get Attachments: 処理または保存のためにメール添付ファイルをダウンロードします。
- Delete Email: メールをごみ箱に移動するか、ごみ箱から完全に削除します。
- Archive Email: 「すべてのメール」に保持したまま受信トレイから削除します。
- Mark as Spam:望ましくないメールを報告し、迷惑メールフォルダに移動します。
- Mark as Important/Starred: 容易に取得できるように重要なメールにフラグを付けます。
下書き管理
- Create Draft: 送信せずにメールの作成内容を下書きとして保存します。
- Update Draft: 既存の下書きのコンテンツ、受信者、または添付ファイルを変更します。
- Send Draft: 以前に作成した下書きメールを送信します。
- List Drafts: 保存されたすべての下書きメールを表示します。
- Delete Draft: 下書きフォルダから下書きメールを削除します。
ラベル操作
- List Labels: システムラベルとカスタムラベルを含む利用可能なすべてのラベルを取得します。
- Create Label: メール整理用のカスタムラベルを作成します。
- Apply Label: メールに1つまたは複数のラベルを追加します。
- Remove Label: メールからラベルを削除します。
- Rename Label: より良い整理のためにラベル名を変更します。
- Delete Label: カスタムラベルを削除します（メールはそのまま保持されます）。
スレッド操作
- Get Thread: すべてのメッセージを含む会話スレッド全体を取得します。
- List Threads: 検索条件に基づいて会話スレッドを照会します。
- Modify Thread: スレッド内のすべてのメールに一括操作を適用します。
ステータス管理
- Mark as Read: 1件または複数のメールの既読ステータスを更新します。
- Mark as Unread: 後で確認できるようにメールを未読としてフラグ付けします。
- Trash Email: メールをごみ箱フォルダに移動します。
- Untrash Email: ごみ箱からメールを受信トレイに復元します。
設定オプション
- Query Filters: 検索用のデフォルトフィルタを設定します（例：過去30日のみ検索）。
- Max Results: クエリごとに取得するメールの最大件数を設定します（デフォルト50、最大500）。
- Include Spam/Trash: 検索に迷惑メールとごみ箱フォルダを含めるかどうか。
- Attachment Handling: ダウンロードする添付ファイルのサイズ制限とウイルススキャンを設定します。
- Default Labels: エージェントが送信するメールに自動的にラベルを適用します。
- Thread Mode: 返信の自動スレッド groupingを有効/無効にします。
ユースケース
- インテリジェントなインボックス管理: コンテンツ分析に基づいて、受信メールを自動的に分類、ラベル付け、優先順位付けします。
- リード抽出: メールをスキャンして連絡先情報を抽出し、CRMシステムに投入します。
- 自動返信: ナレッジベースの知識を使用して、一般的な問い合わせへの文脈に応じた応答を生成します。
- メール監視: 特定のキーワードや送信者を監視し、ワークフローや通知をトリガーします。
- ニュースレター管理: プロモーションメールを自動的に整理、要約、または配信停止します。
- カスタマーサポート: コンテンツ分類に基づいてサポートメールを適切なチームに振り分けます。
- 経費追跡: メールから領収書を抽出し、添付ファイルを処理して、会計システムに記録します。
- ミーティング調整: 招待メールを解析し、カレンダーシステムと同期します。
ベストプラクティス
- Gmailクエリ構文の使用: 正確なメールフィルタリング高度な検索演算子を活用してください。
- バッチ操作: APIコールを削減するために、単一の操作で複数のメールを処理してください。
- APIクォータの遵守: Gmail APIには日次クォータ制限があります（Google Workspaceは1日10億クォータユニット）。
- 指数バックオフの実装: リトライロジックでレート制限を適切に処理してください。
- スレッドセーフな返信: 会話コンテキストを維持するために、返信時は常にスレッドIDを使用してください。
- ラベルの整理: 自動分類用に明確なラベル階層を作成してください。
APIクォータの考慮事項
Gmail APIは、異なる操作に異なるコストがかかるクォータシステムを使用しています。一般的なコスト：メール送信（100ユニット）、メッセージ取得（5ユニット）、メッセージ一覧表示（1ユニット）。Google Cloud Consoleで使用状況を監視し、制限に達するのを防いでください。大量のアプリケーションには、Googleを通じてクォータ増加をリクエストしてください。よくある問題と対処法
- クォータを超過しました: キャッシュとバッチ操作を実装してAPIコールを削減してください。必要に応じてクォータ増加をリクエストしてください。
- Invalid Grantエラー: トークンが期限切れまたは取り消されました。OAuthフローでユーザーを再認証してください。
- 権限が不足しています: OAuth同意時にすべての必要なスコープがリクエストされていることを確認してください。
- 添付ファイルのダウンロード失敗: 大きな添付ファイルはタイムアウトする可能性があります。5MB以上のファイルにはストリーミングダウンロードを使用してください。