gmail

name	gmail
description	CLI for Gmail via Google's REST API — list, search, read, send, draft, label, delete. Use for all Gmail email operations.
last-updated	2026-07-04T00:00:00.000Z

gmail

Read and send email through the gmail CLI for Gmail via Google's REST API.

All interaction goes through the gmail CLI. Authentication is via OAuth 2.0, stored securely in ~/.gmail/token.json.

How it works

The Gmail CLI uses the Google Gmail REST API directly — no browser automation, no IMAP/SMTP. This is more robust and reliable than browser-based approaches.

• OAuth 2.0 authentication with automatic token refresh
• REST API for all operations (list, read, send, draft, label, delete)
• macOS Keychain integration for storing sensitive credentials
• Gmail-specific features: labels (not folders), threads, stars, spam, trash

Config lives in ~/.gmail/. The OAuth token is refreshed automatically.

Prerequisites

Verify the CLI is available:

which gmail

If missing, install it editable with uv:

cd /Users/dansmart/gitsky/dotfiles/agentic/skills/gmail
uv pip install -e .

Authentication

First-time setup

1. Create a Google Cloud project:

   • Go to Google Cloud Console
   • Click the project dropdown at the top → New Project
   • Name it (e.g., "Gmail CLI") and click Create

2. Enable the Gmail API:

   • Go to APIs & Services → Library
   • Search for "Gmail API"
   • Click Enable (wait for it to finish)

3. Configure OAuth consent screen:

   • Go to APIs & Services → OAuth consent screen
   • User Type: External
   • Fill in:
     • App name: "Gmail CLI"
     • User support email: your email
     • Developer contact: your email
   • Click Save and Continue
   • Skip "Scopes" (click Save and Continue)
   • Skip "Test users" for now (click Save and Continue)
   • Click Back to Dashboard

4. Create OAuth credentials:

   • Go to APIs & Services → Credentials
   • Click + Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Name: "Gmail CLI"
   • Click Create
   • Click Download JSON (or copy the JSON)
   • Save as ~/.gmail/credentials.json

5. Login:

   gmail login
   

   This opens a browser window for OAuth consent. Select your Google account, grant permissions, and you'll be redirected to a success page. The token is saved to ~/.gmail/token.json (chmod 600).

   If you get a 403 error: Make sure you completed step 2 (enable Gmail API) and step 3 (OAuth consent screen). The consent screen must be saved before credentials work.

6. Optional — store refresh token in Keychain:

   security add-generic-password -s 'gmail' -a '[e-mail]' -w '<refresh-token>'
   

Subsequent sessions

The OAuth token is automatically refreshed. If it expires, re-run gmail login.

Read

# List messages (newest first) — table format
gmail list
gmail list --limit 20
gmail list --unread
gmail list --starred
gmail list --label INBOX
gmail list --label SENT

# Search with Gmail query syntax
gmail list --query "from:[e-mail]"
gmail list --query "subject:invoice"
gmail list --query "has:attachment"
gmail list --query "after:2026-01-01 before:2026-07-04"

# Read a specific message (use ID from list)
gmail read <message-id>
gmail read --raw <message-id>    # JSON output

Gmail query syntax:

• from:[e-mail] — sender
• to:[e-mail] — recipient
• subject:keyword — subject line
• is:unread, is:starred, is:important
• has:attachment, has:drive
• after:YYYY/MM/DD, before:YYYY/MM/DD
• label:label-name — custom labels

Unread workflow

Process unread emails one at a time:

# Fetch unread messages
gmail list --unread --limit 1

# Read the message
gmail read <message-id>

# Mark as read (if needed — reading doesn't auto-mark)
gmail label --remove UNREAD --message-id <id>

Send

gmail send --to [e-mail] --subject "Hi" --body "Quick note"
gmail send --to [e-mail] --subject "Report" --body-file ./report.txt --cc [e-mail]
echo "body from stdin" | gmail send --to [e-mail] --subject Hi --body-file - --confirm

• --to takes a single email (Gmail API limitation for simple send)
• --cc for carbon copy
• Body from --body or --body-file (- reads stdin)
• Confirms first (prints message, waits for y/N) unless --confirm

Always show the draft to the user and get explicit approval before sending.

Drafts

# Create a draft
gmail draft --to [e-mail] --subject "Hi" --body "Draft message"
gmail draft --to [e-mail] --subject "Report" --body-file ./draft.txt

# List drafts
gmail draft --list
gmail draft --list --limit 5
gmail draft --list --raw    # JSON

# Show a specific draft
gmail draft --show <draft-id>
gmail draft --show <draft-id> --raw

# Delete a draft
gmail draft --delete <draft-id>

Delete / Trash / Spam

# Move to trash (can be recovered)
gmail delete <message-id> --trash

# Mark as spam
gmail delete <message-id> --spam

# Delete permanently (bypass trash)
gmail delete <message-id>

Labels (Gmail's folders)

Gmail uses labels instead of folders. A message can have multiple labels.

# List all labels
gmail label --list
gmail label --list --raw

# Create a new label
gmail label --create "Projects/Client-X"

# Add label to message
gmail label --add LABEL_ID --message-id <id>

# Remove label from message
gmail label --remove LABEL_ID --message-id <id>

Built-in label IDs:

• INBOX, SENT, DRAFT, SPAM, TRASH
• UNREAD, STARRED, IMPORTANT

Custom labels get auto-generated IDs (use gmail label --list to find them).

Archive

Archive removes the INBOX label (message stays in "All Mail"):

# Archive is just removing INBOX label
gmail label --remove INBOX --message-id <id>

Star / Unstar

# Star a message
gmail label --add STARRED --message-id <id>

# Unstar a message
gmail label --remove STARRED --message-id <id>

Output formats

Most commands support --raw for JSON output — useful for scripting:

gmail list --raw | jq '.[].id'
gmail read --raw <id> | jq '.payload.headers'

Error handling

• Not authenticated — run gmail login
• credentials.json not found — download from Google Cloud Console
• Token expired — automatic refresh; if that fails, re-run gmail login
• Gmail API error — network issue or API quota exceeded; retry

403 Error (login fails with 403)

If gmail login shows a 403 error in the redirect URL, check these:

1. Gmail API not enabled: Go to APIs & Services → Library → search "Gmail API" → click Enable. Wait 1-2 minutes after enabling.

2. OAuth consent screen incomplete: Go to APIs & Services → OAuth consent screen. Make sure you clicked Save and Continue through all sections (App info, Scopes, Test users). The status will show as "Testing" — that's fine for personal use.

3. Add yourself as a test user (if consent screen is in "Testing" mode):

   • OAuth consent screen → Test users section
   • Click Add Users
   • Add your Gmail address
   • Click Save
   • Wait 1-2 minutes, then try gmail login again

4. Wrong project selected: Make sure you're in the correct project when enabling the API (check the project dropdown at the top matches gmail-cli-501412).

5. Billing not required: The Gmail API is free for reasonable usage — you do NOT need to enable billing for basic send/read operations.

Etiquette & security

• Email is sensitive. Never paste message contents, addresses, or tokens into external services, logs, or other models.
• OAuth token in ~/.gmail/token.json is chmod 600 — never commit it.
• credentials.json (OAuth client secret) should also be kept private.
• Respect rate limits. Gmail API has generous quotas but don't hammer it.
• Re-confirm every send with the user before it goes out.

Differences from folder-based email

Gmail uses labels, not folders:

Concept	Folders (IMAP/OWA)	Gmail Labels
Organization	One folder per message	Multiple labels per message
"Move"	Copy then delete	Add/remove labels
Archive	Move to Archive folder	Remove INBOX label
Delete	Move to Trash	Remove all labels → auto-trash

This means a message can be in "Inbox" AND "Projects" AND "Important" simultaneously.

Gmail API limitations

• No attachments in this CLI version (API supports it, not implemented)
• Single recipient in --to (use BCC/CC workarounds or send multiple)
• No HTML body — plaintext only
• No threads — messages individually (Gmail threads via threadId not exposed)

These can be added in future versions if needed.