gmail-automation

Rube MCP による Gmail の自動化

Rube MCP を介して、Composio の Gmail ツールキットで Gmail の操作を自動化します。

ツールキットのドキュメント：composio.dev/toolkits/gmail

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• ツールキット gmail で RUBE_MANAGE_CONNECTIONS を使用して、Gmail に接続済みであること
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出すこと

セットアップ

Rube MCP を入手する：クライアントの設定で https://rube.app/mcp を MCP サーバーとして追加します。API キーは不要です。エンドポイントを追加するだけで動作します。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確かめます
2. ツールキット gmail を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って Google OAuth を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

主なワークフロー

1. メールを送信する

使用する状況：ユーザーが新しいメールの作成と送信を希望している場合

ツールの呼び出し順序：

1. GMAIL_SEARCH_PEOPLE - 連絡先名からメールアドレスを特定します［任意］
2. GMAIL_SEND_EMAIL - メールを送信します［必須］

主なパラメーター：

• recipient_email：メールアドレス、または自分宛ての場合は 'me'
• subject：メールの件名
• body：メールの本文（プレーンテキストまたは HTML）
• is_html：本文に HTML マークアップが含まれる場合は true にする必要があります
• cc/bcc：メールアドレスの配列
• attachment：前のダウンロードで取得した {s3key, mimetype, name} を含むオブジェクト

注意点：

• recipient_email、cc、bcc のいずれかが少なくとも 1 つ必要です
• subject または body のいずれかが少なくとも 1 つ必要です
• 添付ファイルの mimetype には '/' が含まれている必要があります（例：'application/pdf'。'pdf' は不可）
• base64 エンコード後のメッセージサイズの上限は約 25MB です
• from_email を使用できるのは、Gmail の「名前を付けてメールを送信」設定で確認済みのエイリアスに限られます

2. スレッドに返信する

使用する状況：ユーザーが既存のメールのやり取りへの返信を希望している場合

ツールの呼び出し順序：

1. GMAIL_FETCH_EMAILS - 返信するメールまたはスレッドを見つけます［前提条件］
2. GMAIL_REPLY_TO_THREAD - スレッド内で返信を送信します［必須］

主なパラメーター：

• thread_id：FETCH_EMAILS から取得した 16 進文字列（例：'169eefc8138e68ca'）
• message_body：返信の本文
• recipient_email：返信先のメールアドレス
• is_html：HTML コンテンツの場合は true に設定します

注意点：

• thread_id は 16 進文字列である必要があります。'msg-f:' などのプレフィックスは自動的に削除されます
• 従来の Gmail ウェブ UI の ID（例：'FMfcgz...'）には対応していません
• 件名は元のスレッドから引き継がれます。件名を設定すると、代わりに新しいスレッドが作成されます
• スレッド内で返信するには、件名のパラメーターを含めないでください

3. メールを検索して絞り込む

使用する状況：ユーザーが送信者、件名、日付、ラベルなどで特定のメールを見つけたい場合

ツールの呼び出し順序：

1. GMAIL_FETCH_EMAILS - Gmail のクエリ構文で検索します［必須］
2. GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID - 選択した検索結果のメッセージ詳細を取得します［任意］

主なパラメーター：

• query：Gmail の検索構文（from:、to:、subject:、is:unread、has:attachment、after:YYYY/MM/DD、before:YYYY/MM/DD）
• max_results：1 ページあたり 1～500 件のメッセージ
• label_ids：'INBOX'、'UNREAD' などのシステム ID
• include_payload：メッセージの全文を取得するには true に設定します
• ids_only：メッセージ ID のみを取得するには true に設定します
• page_token：ページネーションに使用します（nextPageToken から取得）

注意点：

• 1 ページあたり最大約 500 件が返されます。nextPageToken がなくなるまで、page_token を使って次のページに進んでください
• resultSizeEstimate は概算であり、正確な件数ではありません
• 状態の指定には 'is:' を使用します（is:unread、is:snoozed、is:starred）
• 'label:' はユーザーが作成したラベルにのみ使用してください
• よくある間違い：'label:snoozed' は誤りです。'is:snoozed' を使用してください
• 広範な検索で include_payload=true を指定すると、応答が非常に大きくなります。デフォルトではメタデータを取得してください
• カスタムラベルにはラベル名ではなくラベル ID（例：'Label_123'）が必要です

4. ラベルを管理する

使用するタイミング：ユーザーがラベルの作成、変更、整理を希望する場合

ツールの実行順序：

1. GMAIL_LIST_LABELS - IDを確認し、競合を検出するためにすべてのラベルを一覧表示します [必須]
2. GMAIL_CREATE_LABEL - 新しいラベルを作成します [任意]
3. GMAIL_PATCH_LABEL - ラベル名、色、表示設定を変更します [任意]
4. GMAIL_DELETE_LABEL - ユーザーが作成したラベルを削除します（元に戻せません） [任意]

主なパラメーター：

• label_name：最大225文字、カンマは使用できません。階層化には「/」を使用します（例：'Work/Projects'）
• background_color/text_color：Gmailの定義済みパレットにある16進数の値
• id：PATCH/DELETE操作に使用するラベルID

注意点：

• 名前が空、重複、または予約済み（INBOX、SPAM、CATEGORY_*）の場合、400/409エラーが発生します
• 色の指定には、Gmailの定義済みパレットにある102個の16進数値を使用する必要があります
• DELETEは完全に削除され、すべてのメッセージからラベルが取り除かれます
• システムラベル（INBOX、SENT、DRAFTなど）は削除できません

5. メッセージにラベルを適用／削除する

使用するタイミング：ユーザーがメールへのラベル付け、アーカイブ、既読／未読の設定を希望する場合

ツールの実行順序：

1. GMAIL_LIST_LABELS - カスタムラベルのIDを取得します [前提条件]
2. GMAIL_FETCH_EMAILS - 対象のメッセージを検索します [前提条件]
3. GMAIL_BATCH_MODIFY_MESSAGES - ラベルを一括で追加／削除します（最大1000件） [必須]
4. GMAIL_ADD_LABEL_TO_EMAIL - 1件のメッセージのラベルを変更します [代替手段]

主なパラメーター：

• messageIds：メッセージIDの配列（最大1000件）
• addLabelIds：追加するラベルIDの配列
• removeLabelIds：削除するラベルIDの配列
• message_id：単一操作に使用する15～16文字の16進数文字列

注意点：

• BATCH呼び出しあたりのmessageIdsは最大1000件です。これを超える場合は分割してください
• 'UPDATES'ではなく'CATEGORY_UPDATES'を使用してください。カテゴリラベルには完全なプレフィックスが必要です
• SENT、DRAFT、CHATは変更できません。追加も削除もできません
• 既読にするには'UNREAD'を削除します。アーカイブするには'INBOX'を削除します
• message_idは15～16文字の16進数である必要があります。UUIDやウェブUIのIDは使用できません

6. 下書きと添付ファイルを扱う

使用するタイミング：ユーザーが、添付ファイルを含む場合も含め、メールの下書きの作成、編集、送信を希望する場合

ツールの実行順序：

1. GMAIL_CREATE_EMAIL_DRAFT - 新しい下書きを作成します [必須]
2. GMAIL_UPDATE_DRAFT - 下書きの内容を編集します [任意]
3. GMAIL_LIST_DRAFTS - 既存の下書きを一覧表示します [任意]
4. GMAIL_SEND_DRAFT - 下書きを送信します（ユーザーの明示的な承認が必要です） [任意]
5. GMAIL_GET_ATTACHMENT - 既存のメッセージから添付ファイルをダウンロードします [任意]

主なパラメーター：

• recipient_email：下書きの宛先
• subject：下書きの件名（返信の下書きでスレッドを維持するには省略します）
• body：下書きの内容
• is_html：HTMLコンテンツの場合はtrueに設定します
• attachment：{s3key, mimetype, name}を含むオブジェクト
• thread_id：返信の下書き用（スレッドを維持するには件名を空のままにします）

注意点：

• レスポンスにはdata.id（draft_id）とdata.message.idの両方が含まれます。下書きの操作にはdata.idを使用してください
• スレッドへの返信の下書きで件名を設定すると、代わりに新しいスレッドが作成されます
• 添付ファイルは約25MBまでです。base64のオーバーヘッドにより、上限に近いファイルは上限を超えることがあります
• UPDATE_DRAFTは内容全体を置き換え、部分更新はしません。維持したいフィールドもすべて含めてください
• 下書きを一括作成するとHTTP 429が発生します。指数バックオフを使用してください

よく使われるパターン

IDの解決

ラベル名 → ラベルID：

1. Call GMAIL_LIST_LABELS
2. Find label by name in response
3. Extract id field (e.g., 'Label_123')

連絡先名 → メールアドレス：

1. Call GMAIL_SEARCH_PEOPLE with query=contact_name
2. Extract emailAddresses from response

検索結果からスレッドIDを取得：

1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
2. Extract threadId (15-16 char hex string)

ページネーション

• 1ページあたりのmax_resultsを最大500に設定します
• レスポンスにnextPageTokenが含まれているか確認します
• 次のリクエストでは、トークンをpage_tokenとして渡します
• nextPageTokenが存在しないか、空文字列になるまで続けます
• resultSizeEstimateは概算であり、正確な値ではありません

Gmail の検索構文

演算子：

• from:[email protected] - 送信者からのメール
• to:[email protected] - 宛先へのメール
• subject:"exact phrase" - 件名に完全一致するフレーズを含むメール
• is:unread - 未読メッセージ
• is:starred - スター付きメッセージ
• is:snoozed - スヌーズ中のメッセージ
• has:attachment - 添付ファイルがあるメール
• after:2024/01/01 - 指定日以降（YYYY/MM/DD）
• before:2024/12/31 - 指定日より前
• label:custom_label - ユーザーが作成したラベル（ラベル ID を使用）
• in:sent - 送信済みフォルダー内
• category:primary - メインカテゴリ

結合子：

• AND - 両方の条件（デフォルト）
• OR - いずれかの条件
• NOT - 条件を除外
• () - 条件をグループ化

例：

• from:[email protected] is:unread - 上司からの未読メール
• subject:invoice has:attachment after:2024/01/01 - 今年の添付ファイル付き請求書
• (from:alice OR from:bob) is:starred - Alice または Bob からのスター付きメール

既知の落とし穴

ID 形式：

• カスタムラベルの操作には、表示名ではなくラベル ID（例：'Label_123'）が必要です
• 名前を ID に解決するには、必ず最初に LIST_LABELS を呼び出してください
• メッセージ ID は 15～16 文字の 16 進数文字列です
• UUID、Web UI の ID、または 'thread-f:' プレフィックスは使用しないでください

検索構文：

• 状態（未読、スヌーズ中、スター付き）には 'is:' を使用してください
• 'label:' はユーザーが作成したラベルにのみ使用してください
• システムラベルには 'is:' または 'in:' を使用してください（例：'is:sent'、'in:inbox'）

レート制限：

• BATCH_MODIFY_MESSAGES は 1 回の呼び出しにつき最大 1000 件のメッセージを処理します
• 頻繁に使用すると 403/429 のレート制限が発生します
• 一括操作では指数バックオフを実装してください

レスポンスの解析：

• レスポンスデータは data_preview または data.messages の下にネストされている場合があります
• フォールバックを用意して堅牢に解析してください
• タイムスタンプ messageTimestamp は、末尾に 'Z' が付いた RFC3339 形式です
• 必要に応じて、解析前に '+00:00' に正規化してください

添付ファイル：

• 以前のダウンロードで取得した添付ファイルの s3key は期限切れになる場合があります
• 取得後は速やかに使用してください
• Mimetype には '/' 区切り文字が必要です

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
メールを送信	GMAIL_SEND_EMAIL	recipient_email, subject, body, is_html
スレッドに返信	GMAIL_REPLY_TO_THREAD	thread_id, message_body, recipient_email
メールを検索	GMAIL_FETCH_EMAILS	query, max_results, label_ids, page_token
メッセージの詳細を取得	GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	message_id
ラベルを一覧表示	GMAIL_LIST_LABELS	(none)
ラベルを作成	GMAIL_CREATE_LABEL	label_name, background_color, text_color
ラベルを一括変更	GMAIL_BATCH_MODIFY_MESSAGES	messageIds, addLabelIds, removeLabelIds
下書きを作成	GMAIL_CREATE_EMAIL_DRAFT	recipient_email, subject, body, thread_id
下書きを送信	GMAIL_SEND_DRAFT	draft_id
添付ファイルを取得	GMAIL_GET_ATTACHMENT	message_id, attachment_id
連絡先を検索	GMAIL_SEARCH_PEOPLE	query
プロフィールを取得	GMAIL_GET_PROFILE	(none)

---

Composio により提供