Gmail Skill

Full CRUD Gmail management for AI agents. Search, read, compose, reply, forward, and manage messages.

Features

• Search: Advanced filtering using Gmail query syntax (from, to, subjects, labels, date ranges).

• Read: Fetch full message body, headers, and metadata.

• Thread: Read entire conversation threads.

• Draft: Create draft emails for the user to review.

• Send: Send emails directly.

• Reply: Reply to the sender of a message.

• Reply All: Reply to all recipients (sender + To + Cc, minus self).

• Forward: Forward a message with attribution header to new recipients.

• Trash / Untrash: Move messages to/from the trash.

• Labels: List labels. Add/remove labels on messages.

• Attachments: List and download message attachments.

Prerequisites

• Google Cloud Project with Gmail API enabled.

• OAuth 2.0 Credentials — either gcloud ADC or credentials.json .

Setup

⚡ Quick Setup (Recommended)

Set up Gmail, Calendar, and Contacts all at once:

uv run ~/.agents/skills/gmail/scripts/setup_workspace.py

Manual Setup

Using gcloud ADC:

gcloud auth application-default login
--scopes https://mail.google.com/,https://www.googleapis.com/auth/cloud-platform

Then verify:

uv run skills/gmail/scripts/gmail.py verify

Alternative (credentials.json):

• Place credentials.json in ~/.gmail_credentials/ .

• Run uv run skills/gmail/scripts/gmail.py setup

Usage

Search for Emails

Find unread emails from Obi-Wan

uv run skills/gmail/scripts/gmail.py search --query "from:obiwan@jedi.org is:unread"

Find emails with attachments about Death Star plans

uv run skills/gmail/scripts/gmail.py search --query "has:attachment subject:plans" --limit 5

Read a Single Message (Full Body)

uv run skills/gmail/scripts/gmail.py read --id "18e..."

Read an Entire Thread

uv run skills/gmail/scripts/gmail.py thread --id "18e..."

Create a Draft

Safest option — creates a draft for the user to review before sending.

uv run skills/gmail/scripts/gmail.py draft
--to "yoda@dagobah.net"
--subject "Training Schedule"
--body "Master, when shall we begin the next session?"
--cc "mace@jedi.org"

Send an Email Directly

uv run skills/gmail/scripts/gmail.py send
--to "yoda@dagobah.net"
--subject "Urgent: Sith Sighting"
--body "Master, I sense a disturbance in the Force."

Reply to a Message

Reply (creates a draft by default)

uv run skills/gmail/scripts/gmail.py reply --id "18e..." --body "Acknowledged, Master."

Reply and send immediately

uv run skills/gmail/scripts/gmail.py reply --id "18e..." --body "Acknowledged." --send

Reply to All

uv run skills/gmail/scripts/gmail.py reply-all --id "18e..." --body "Council noted." --send

Forward a Message

Forward with a note (creates a draft by default)

uv run skills/gmail/scripts/gmail.py forward
--id "18e..."
--to "luke@tatooine.net"
--body "FYI — see the original message below."

Forward and send immediately

uv run skills/gmail/scripts/gmail.py forward
--id "18e..."
--to "luke@tatooine.net"
--send

Trash / Untrash

uv run skills/gmail/scripts/gmail.py trash --id "18e..." uv run skills/gmail/scripts/gmail.py untrash --id "18e..."

Label Management

List all labels

uv run skills/gmail/scripts/gmail.py labels

Add/remove labels

uv run skills/gmail/scripts/gmail.py modify-labels --id "18e..." --add STARRED --remove UNREAD

Download Attachments

uv run skills/gmail/scripts/gmail.py attachments --id "18e..." --output-dir ./downloads

Safety Guidelines

• Prefer draft over send for new compositions — let the user review first.

• Reply/Forward defaults to draft — use --send flag only when explicitly requested.

• Trash is reversible — messages can be untrashed. Permanent deletion is intentionally not exposed.

• Threading: Reply, reply-all, and forward use proper In-Reply-To and References headers so Gmail threads them correctly.

JSON Output Structure

All commands produce JSON for easy parsing.

Search Result:

[ { "id": "18e...", "threadId": "18e...", "snippet": "Help me, Obi-Wan Kenobi...", "from": "Leia Organa <leia@alderaan.gov>", "to": "obiwan@jedi.org", "subject": "Urgent Message", "date": "Mon, 13 Feb 2026 10:00:00 -0700", "labels": ["INBOX", "UNREAD"] } ]

Read Result (includes full body):

{ "id": "18e...", "threadId": "18e...", "body": "Full message text...", "attachments": [ { "filename": "plans.pdf", "mimeType": "application/pdf", "size": "42000" } ] }