gmail

Gmail

メールの管理、検索、整理を行うために Gmail を操作します。

インストール

依存関係：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

セットアップの確認

インストール後、スキルが正しく設定されていることを確認します。

$SKILL_DIR/scripts/gmail.py check

次の項目が確認されます。

• Python の依存関係（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 認証設定
• Gmail API への接続

不足している項目がある場合、確認コマンドにセットアップ手順が表示されます。

認証

Gmail の認証には OAuth 2.0 を使用します。セットアップの詳しい手順については、次を参照してください。

1. GCP プロジェクトのセットアップガイド - プロジェクトを作成し、Gmail API を有効にします
2. Google OAuth のセットアップガイド - 認証情報を設定します

クイックスタート

1. ~/.config/agent-skills/google.yaml を作成します。

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. $SKILL_DIR/scripts/gmail.py check を実行して OAuth フローを開始し、セットアップを確認します。

スコープまたは認証エラーが発生した場合は、OAuth のトラブルシューティングガイドを参照してください。

コマンド

各コマンドの読み取り／書き込みの分類については、permissions.md を参照してください。

check

設定と接続を確認します。

$SKILL_DIR/scripts/gmail.py check

次の項目を検証します。

• Python の依存関係がインストールされていること
• 認証が設定されていること
• Gmail API に接続できること
• メールアドレスとメールボックスの統計情報が表示されること

auth setup

カスタム OAuth フロー用の OAuth 2.0 クライアント認証情報を保存します。

$SKILL_DIR/scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

認証情報は ~/.config/agent-skills/gmail.yaml に保存されます。

auth reset

保存済みの OAuth トークンを消去します。次に認証が必要なコマンドを実行すると、自動的に再認証が開始されます。

$SKILL_DIR/scripts/gmail.py auth reset

スコープまたは認証エラーが発生した場合に使用します。

auth status

API 呼び出しを行わずに、現在の OAuth トークン情報を表示します。

$SKILL_DIR/scripts/gmail.py auth status

トークンが保存されているか、許可されたスコープ、リフレッシュトークンの有無、トークンの有効期限、クライアント ID が表示されます。

messages list

クエリに一致するメッセージを一覧表示します。

# List recent messages
$SKILL_DIR/scripts/gmail.py messages list

# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected]" --max-results 20

引数：

• --query：Gmail の検索クエリ（省略可）
• --max-results：結果の最大件数（デフォルト：10）

検索クエリの例：

Gmail 検索構文の詳しい説明については、gmail-queries.md を参照してください。

よく使うクエリ：

• is:unread - 未読メッセージ
• from:[email protected] - 送信者からのメッセージ
• subject:meeting - 件名にキーワードを含むメッセージ
• has:attachment - 添付ファイルのあるメッセージ
• after:2024/01/01 - 指定日以降のメッセージ
• label:important - ラベルが付いたメッセージ

messages get

ID でメッセージを取得します。

# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal

引数：

• message_id：メッセージ ID（必須）
• --format：メッセージ形式（full、minimal、raw、metadata）- デフォルト：full

messages mark-read

UNREAD ラベルを削除して、1 件以上のメッセージを既読にします。

# Mark a single message
$SKILL_DIR/scripts/gmail.py messages mark-read MESSAGE_ID

# Mark multiple messages
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 MSG2 MSG3

# Mark all unread messages from a sender
$SKILL_DIR/scripts/gmail.py messages mark-read --query "is:unread from:[email protected]"

# Combine IDs and query
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 --query "is:unread label:updates"

引数：

• message_ids：1 つ以上のメッセージ ID（--query を使用する場合は省略可）
• --query：既読にするメッセージを検索するための Gmail 検索クエリ
• --max-results：--query で検索して既読にするメッセージの最大件数（デフォルト：100）

threads get

すべてのメッセージを時系列順に表示した、会話スレッド全体を取得します。Google Groups からのメッセージの場合は、d/msgid 形式の URL を使用した共有可能なパーマリンクも含まれます。

# Get full thread
$SKILL_DIR/scripts/gmail.py threads get THREAD_ID

引数：

• thread_id：スレッド ID（必須）

send

メールメッセージを送信します。

# Send simple email
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Hello" \
  --body "This is the message body"

# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc [email protected] \
  --bcc [email protected]

# Send from a markdown file with frontmatter
$SKILL_DIR/scripts/gmail.py send --from-file update.md

# Send from file with CLI overrides
$SKILL_DIR/scripts/gmail.py send --from-file update.md --to [email protected]

# Reply to a message in-thread
$SKILL_DIR/scripts/gmail.py send --reply-to MESSAGE_ID --body "Thanks, got it."

引数：

• --to：受信者のメールアドレス（--from-file または --reply-to を指定する場合を除き必須）
• --subject：メールの件名（--from-file または --reply-to を指定する場合を除き必須）
• --body：メール本文（--from-file を指定する場合を除き必須）
• --from-file：YAML フロントマターを含む Markdown ファイル（以下の形式を参照）
• --cc：CC の受信者（カンマ区切り）
• --bcc：BCC の受信者（カンマ区切り）
• --reply-to：返信するメッセージ ID（スレッド内で送信し、宛先と件名を自動入力します）

CLI フラグはフロントマターの値より優先されます。--from-file を使用すると、Markdown 本文は HTML に変換され、multipart/alternative（HTML とプレーンテキストのフォールバック）として送信されます。

Markdown ファイルの形式：

---
to: [email protected]
cc: [email protected]
bcc: [email protected]
subject: Weekly Update
---

# Status Update

Here's what happened this week:

- **Feature A** shipped to production
- Fixed the [login bug](https://jira.example.com/DEMO-123)

| Task | Status |
|------|--------|
| Deploy | Done |

drafts list

下書きメッセージを一覧表示します。

# List drafts
$SKILL_DIR/scripts/gmail.py drafts list

# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20

引数：

• --max-results：結果の最大数（デフォルト：10）

drafts create

メールの下書きを作成します。

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Draft Subject" \
  --body "This is a draft message"

# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc [email protected]

# Create a reply draft in-thread
$SKILL_DIR/scripts/gmail.py drafts create --reply-to MESSAGE_ID --body "I'll look into this."

# Create draft from a markdown file
$SKILL_DIR/scripts/gmail.py drafts create --from-file update.md

引数：

• --to：受信者のメールアドレス（--from-file を指定する場合を除き必須）
• --subject：メールの件名（--from-file を指定する場合を除き必須）
• --body：メール本文（--from-file を指定する場合を除き必須）
• --from-file：YAML フロントマターを含む Markdown ファイル（send と同じ形式）
• --cc：CC の受信者（カンマ区切り）
• --bcc：BCC の受信者（カンマ区切り）

drafts send

下書きメッセージを送信します。

# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

引数：

• draft_id：送信する下書きの ID（必須）

labels list

Gmail のすべてのラベルを一覧表示します。

# List labels
$SKILL_DIR/scripts/gmail.py labels list

labels create

新しいラベルを作成します。

# Create label
$SKILL_DIR/scripts/gmail.py labels create "Project X"

引数：

• name：ラベル名（必須）

例

セットアップを確認する

$SKILL_DIR/scripts/gmail.py check

未読メールを検索する

$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

送信者からのメールを検索する

$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected]" --max-results 5

簡単なメールを送信する

$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Quick Question" \
  --body "Do you have time for a meeting tomorrow?"

下書きを作成して送信する

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Weekly Update" \
  --body "Here's this week's update..."

# List drafts to get the ID
$SKILL_DIR/scripts/gmail.py drafts list

# Send the draft
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

ラベルで整理する

# Create a label
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"

# List all labels
$SKILL_DIR/scripts/gmail.py labels list

高度な検索

# Find emails with attachments from last week
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"

# Find important emails from specific sender
$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected] is:important"

# Find emails in a conversation
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"

Gmail 検索クエリ構文

よく使われる検索演算子：

演算子	説明	例
from:	送信者のメールアドレス	from:[email protected]
to:	受信者のメールアドレス	to:[email protected]
subject:	件名に含まれる語句	subject:meeting
label:	ラベルが付いている	label:important
has:attachment	添付ファイルがある	has:attachment
is:unread	未読メッセージ	is:unread
is:starred	スター付きメッセージ	is:starred
after:	指定日より後	after:2024/01/01
before:	指定日より前	before:2024/12/31
newer_than:	指定期間より新しい	newer_than:7d
older_than:	指定期間より古い	older_than:30d

演算子はスペース（暗黙の AND）または OR で組み合わせます。

# AND (implicit)
from:[email protected] subject:meeting

# OR
from:[email protected] OR from:[email protected]

# Grouping with parentheses
(from:[email protected] OR from:[email protected]) subject:meeting

詳細については、gmail-queries.md を参照してください。

エラー処理

認証エラーとスコープエラーは再試行できません。 コマンドが認証エラー、不十分なスコープのエラー、または権限拒否エラー（終了コード 1）で失敗した場合は、処理を停止してユーザーに知らせてください。自動で再試行したり、問題を解決しようとしたりしないでください。これらのエラーにはユーザーの操作（ブラウザーを使用した OAuth 同意）が必要です。ユーザーにはOAuth トラブルシューティングガイドを案内してください。

再試行可能なエラー：レート制限（HTTP 429）や一時的なサーバーエラー（HTTP 5xx）は、少し待ってから再試行すると成功する場合があります。それ以外のエラーはすべてユーザーに報告してください。

モデルに関するガイダンス

このスキルは、構造化された入出力を必要とする API 呼び出しを行います。標準的な機能を備えたモデルを推奨します。