GOOGLE_CREDS_PATH=~/.config/gmail/credentials.json
GMAIL_TOKEN_PATH=~/.config/gmail/token.json

If these aren't set, the script falls back to ~/.config/gmail/credentials.json and ~/.config/gmail/token.json.

Commands

List inbox (full inbox, grouped by thread)

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py list --all

Returns JSON array grouped by thread. Each entry has: id, threadId, from, subject, date, snippet, unread, thread_count. If thread_count > 1, also includes all_ids.

This is the default command. Always use --all unless the user specifically asks for a time-filtered view.

List with time filter

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py list --hours 48

Read full email

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py read <msg_id>

Move email to label/folder

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py move <msg_id> "Label Name"

If the label doesn't exist, it creates it automatically
Removes from INBOX, adds to target label, marks as read

List all labels

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py labels

Reply to an email

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py reply <msg_id> "Your reply body here"

Automatically threads correctly (In-Reply-To, References headers)
Prefixes subject with "Re:" if not already there
Replies to the sender's From/Reply-To address

Reply with attachments

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py reply <msg_id> "Your reply body here" --attachments "/path/to/file1.pdf,/path/to/file2.png"

Send a new email

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py send "to@example.com" "Subject here" "Body here"

Send with attachments

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py send "to@example.com" "Subject" "Body" --attachments "/path/to/file.pdf,/path/to/other.xlsx"

Create a Gmail filter (auto-sort rule)

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py filter --from "sender@example.com" --label "LabelName" --archive --read

--from / --to / --subject / --query for criteria
--label to apply a label, --archive to skip inbox, --read to mark as read, --trash to trash
Creates the label automatically if it doesn't exist

List existing filters

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py filters

Re-authenticate

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/gmail/gmail.py auth

Workflow

Run list --all to show all inbox emails
Display as a table with columns: #, Unread, From, Subject, Replies, Time
Ask the user which to move and where
Run move for each, confirm results

Display Format

Use a proper markdown table for the inbox:

#	Unread	From	Subject	Replies	Time
1	*	someone@example.com	Re: Project update	3	2h ago
2		newsletter@co.com	Your weekly digest	1	5h ago

Replies column shows thread_count (1 = single message, 2+ = thread)
Each row is one thread (conversation), not individual messages

Drafting Rules

Always draft email content and show the user before sending
Never send without confirmation

One-Time Setup

If credentials.json is missing:

Go to Google Cloud Console
Create a project (or select existing)
Enable the Gmail API (APIs & Services > Library)
Go to APIs & Services > Credentials
Create an OAuth 2.0 Client ID > Desktop app
Download the JSON file
Save it to the path in your GOOGLE_CREDS_PATH (default: ~/.config/gmail/credentials.json)
Run the auth command (see above)
Browser opens, sign in, authorize, done

Error Handling

If credentials.json missing, show setup instructions above
If token.json missing, run auth automatically
If label not found, the script creates it
If any command fails, show the error and ask the user what to do

gmail

Gmail Skill

Purpose

Environment

More from earlyaidopters/claudeclaw

timezone

tldr

slack

google-calendar